ANALYZ

i. Getting Started in Analyz Analyz is (and has been for many years) the current online data reduction program at Arecibo. Being an old program, Analyz is a very basic, fairly limited program. On the positive side, Analyz is fairly easy to learn and to program.

To start up Analyz, just type ``Analyz" somewhere that you have a reasonable amount of disk space (i.e. in your /share area). (Note that Analyz is happiest when started from an xterm window.) You will then be asked to supply a name, number of channels per register, and number of registers. Usual answers are ``$<$proj_number$>$ 8192 800". By entering these values and hitting return, you have created three files in whatever directory you are currently in - a9999anz.anz, a9999lib.anz, and a9999hist.anz. As long as you always log into Analyz with the same user name (i.e. a9999) and from the same directory, these files will be referenced. If you log in with a different user name, Analyz will blatantly ignore these files.

1. a9999anz.anz is the file to which Analyz is going to write all your register information when you exit the program. This allows you to restart Analyz at a later time and still have the same information in the registers as when you last exited. On the negative side, this file has to be big enough to accommodate the (total # registers) $\times$ (# channels/register) values (8192x800 in the above example). As long as this file exists in your user area, you do not need to type the number of desired registers & channels when restarting Analyz. That is, once you've created this file you do not need to re-create it (and in fact you don't want to, or you will lose your register information). The next time you start Analyz, simply type your user name, and this file will be automatically attached.

2. a9999lib.anz is where the functions in your Analyz library are stored. That means that if you wish to run Analyz in more than one location, or you wish to take Analyz home with you and you want to still be able to use the same (user-supplied) functions, just copy this file to your new directory, and then be sure to log in to Analyz with the a9999 (or whatever) user name.

3. a9999hist.lib contains a history of all the commands you've typed into Analyz.

The next question you will be asked is what correlator libraries you wish to use. These are a set of libraries created by Phil Perrilat which provide many of the basic analysis commands. It is important that you type the correct library name here.

You will now be `inside' Analyz. If this is your first time running Analyz, you may now want to attach some external functions to you library, such as the HI analysis libraries or Murray Lewis' Analyz libraries. These libraries will provide you with a number of functions created by various staff members at Arecibo. As an example, if you are doing HI observing, you may want to attach the HI analysis routines. This is done by down loading the hi_now.cmd file from http://www.naic.edu/$\sim$astro/analyz into your Analyz directory, and then typing:

1. ``$\sim$hi_now.cmd" to source the library functions. If you now type ``ls" you will discover you have a whole bunch of new functions in your library. Cool.
2. Now type ``autoexecute" and you will be up and running. (NOTE - as long as you keep using the same a9999lib.anz file, you never need to repeat this.)

Your next step is to attach a data file to Analyz. If you are observing and wish to look at the online data, just type ``atoldata" (attach online data). If you wish to look at old data, type
``attach $<$data_file$>$ data", where your data file will typically be called something like corfile.02mar00.a9999.1 (corfile = correlator file, 02mar00 = the data when the data was saved, a9999 = your project number, and 1 = the first, or second, or third, or...) file for that project for that day). Until you've received an email telling you your files have been moved, your data will reside in ``/share/olcor/$<$data_file$>$".

If you wish, you can now verify that your data is really there. To do this, just type ``corlist", and Analyz will begin listing the data in whatever file is attached. If you do this, you will get something that looks like:

   Scan   grp   time  bw integ  bd lag   pwrRatio      power      attn
          num  ofRec Num  secs  id cfg    ratio       counters     db
909000001    1  61532  5  60.000 6   9  1.054  1.069    -0     -0 -1 -1  1.0
909000001    1  61532  5  60.000 7   9  0.935  0.945    -0     -0 -1 -1  1.0
909000001    1  61532  5  60.000 8   9  0.949  1.049    -0     -0 -1 -1  1.0
909000001    1  61532  5  60.000 9   9  1.094  0.919    -0     -0 -1 -1  1.0
909000001    2  61632  5  60.000 6   9  1.057  1.072    -0     -0 -1 -1  1.0
etc.

This tells you that you are looking at scan 909000001, data dump number 1, taken at 06:15:32, using foour subcorrelators (the four entries as num 1), with a 60s integration time, and with a 3.125 MHz bandwidth (bw num = 1 (50MHz), 2 (25 MHz), 3 (12.5 MHz), etc.).

Now that you know you have data attached to the Analyz program, you can start plotting it, examining it, etc. To do this, you need to understand Analyz a bit. Basically, Analyz works just like an old HP calculator whose plotting routines come from pgplot. Data in Analyz is stored in two ways - in temporary registers (x, y, z, and t) and in ``permanent" registers (the ones that are written to your a9999anz.anz file when you exit). The x, y, z, & t registers are what's currently available for plotting, manipulation, etc. The other registers, numbered 1 to the total number of registers you asked for (i.e. 800), are places in which you can store and recall data arrays.

For example, when you enter a value (i.e. 10) into Analyz, that value goes into the x register (that is, into all the elements of it - 8192 for the above example Analyz session). If you enter another value (i.e. 30), it goes into the x register, and the first value moves into the y register. So now the x register is set to 30 and the y register is set to 10. If you enter yet another value, say 50, then you would have x = 50, y = 30, z = 10. As Analyz only keeps track of the x, y, z, and t registers, entering a fourth value (100), would give you x = 100, y = 50, z = 30, and t=10, while a fifth value (36) would shift the registers so that x=36, y=100, z=50, and t=30. You could now plot the entered values one of two way - either with the ``plot" command, which simply plots the x register against array (channel) number, or with the ``plotxy" command which will (yup, you guessed it!) plot the x value against the y value.

You can make all this slightly more complicated by actually reading data into one of the numbered register and then recalling it into the temporary registers. A number of routines exist which will allow you to enter your data into a register(s). A quick method of doing this is to type ``corget", which will first read the next data set into the x register, and then store your individual correlator board data into registers 1 - 4. You can now recall the data from one of these numbered registers, by typing, say ``rcl 1". This tells Analyz to go to the numbered register 1 and put that data into your x register. If you now type ``plot", you will get a plot of the data from correlator board 1 against channel (array) number. If you have your frequency values stored somewhere (i.e. in register 8 if you type ``setfrq" while using the HI analysis routines), you could type ``rcl 8", putting the signal data into the y register and the frequencies into the x-register. ``plotxy" will now plot your signal data against frequency.

You can continue complicating your life by the ``doit", ``domany", etc. commands. Essentially, each of these commands is told a scan number to look at, how many data dumps comprises your ON scan, and what register to store it in. These functions are described a bit more fully below.

Finally, (and continuing in the HP calculator vein), Analyz will readily let you manipulate your data with basic arithmetic functions. Again, just enter the commands like you would on any reverse-Polish calculator. For example, suppose you wanted to compute an (ON/OFF $-$ 1), multiply your result by 3.4, and then store everything into register 100. Assuming register 20 holds your ON data and 22 holds the relevant OFF information, you would type something like this:

>rcl 20
>rcl 22
> /
>- 1
>* 3.4
>sto 100

If all of this seems confusing, either (1) you're too young. Go borrow a real HP calculator from someone (the kind with reverse Polish notation) and this'll start making sense, or (2) you need to sample some good Puerto Rican rum (Barrilitos is a good choice) and then try reading these directions. (Both Analyz and these directions were written by people who live in PR and enjoy Barrilitos, after all.)

ii. More Analyz Stuff

Listing a function: If you can't remember what a function does, typing ``listf $<$function name$>$'' gives a quick listing of the function and any documentation that was attached to it. If you really want to know the painful details of a function, typing ``trace $<$function name$>$'' shows you both the function details and the details of all other sub-functions called by that function.

Writing your own functions: One of the bonuses (there are a couple) of Analyz is the ease with which anyone can write their own Analyz functions. This is done by placing a series of Analyz commands together on one line (each separated by a semicolon), and then following that by a colon and a function name. Once you hit return, Analyz will ask you to give some sort of documentation to your function (you can just hit return if you don't want any) and then presto - you have created an Analyz function.

As a simple example, say you find yourself typing ``rcl 200;han 5;rcl 8;plotxy" repeatedly. You can save yourself some effort by making a function. Now, just type
``rcl 200;han 5;rcl 8;plotxy:myplot"
Then the next time you want to ``rcl 200;han 5;rcl 8;plotxy", you just have to type ``myplot" and Analyz will do all that typing for you.

For a more complicated example, let's say you want to run the above command, but you want to be able to choose what register your data is in. In this case, you need to rely on the ``pr" variables - variables which obtain their values from user input. (There are seven pr variable - pr1 - pr7.) In this case, your function will look like this: ``rcl pr1;han 5;rcl 8;plotx:myplot", and to run it you have to type ``myplot $<$register number$>$".

One thing to keep in mind when writing functions is that Analyz was written for a Harris computer. This means it cannot deal with lines longer than 80 characters in length. If you have a really long function, you need to break it into sub-functions. This can make things get really complicated, but if you have a long observing run, it'll give you something to play with at 3 a.m. Another 3a.m. pitfall is that if you hit return ($<$cr$>$) with no input, analyz will re-execute the last command you typed. This means that accidentally (or intentionally) hitting return a few times can cause analyz to just keep re-executing a command, over, and over (and over and...) again.