The macro language

The macro language encapsulates the fact that whatever numbers we need to extract from the visibility database are either antenna based, interferometer based (or equivalently, baseline based) and/or a function of time and/or frequency within the given observing band. One may want to extract data for a list of antennas, baselines, frequency channels with selection applied in time.

The macro language syntax is a hybrid of the implicit loops of the write statement of FORTRAN (see the manual for FORTRAN) and the format string used by the output functions of C (see documentation on printf in the manual for C). Three operators are defined in the language, namely base, chan and ant, which loop over a list of baselines, frequency channels and antennas respectively. The implicit loops loop over the body of the operators. The body is a list of semicolon (';') separated list of elements enclosed in pair of curly braces ('{' and '}'). Each operator must be followed by a body and the elements of the body can be another operator-body pair. Hence, nested loops are possible.

In the xtract program, the list of values for the operators is supplied as a list of comma (',') separated values for the keywords baselines, channels, and antenna respectively. An operator for time range selection is also required, but not explicitly defined. All macros are internally the body of this time range operator. The time range selection can be specified via the timestamps keyword.

Various elements which the syntax recognizes are listed in Table B.1. Some of these are independent of any operator, while others need to be part of the body of one or more operators. The elements and the operators required by these elements are also listed in the table.

Table B.1: List of elements which can be part of the body of operators in xtract macros

Elements	Operators Required	Description
ua,va,wa	ant (antenna based)	(u,v,w) co-ordinates of the antennas
u,v,w	base (baseline based)	$u_{ij}$ (= ${\tt ua}_i-{\tt ua}_j$) for the baseline $ij$
re,im	base,chan	Real and Imaginary parts of the
		visibility
a,p	base,chan	Amplitude and phase of the
		visibility
cno	chan	Frequency channel number
ha,ist,lst	none	Hour Angle, IST time stamp and
		LST in hrs.
az, el	none	Antenna Azimuth and Elevation
		angles in degree
delay,phs0,	ant	The delay in $\mu s$ applied to the
dphs		antennas at the delay cards,
		the fringe rotation phase,
		and the phase ramp applied at the
		output of FFT

ua,va,wa are the co-ordinates of the antenna in the ($u,v,w$) co-ordinate system in units of the wavelength of the center of the observing band and u=ua$_1$-ua$_2$, where the subscripts refer to the two antennas of a baseline.

The macro to produce a table of rows with Hour Angle ($HA$) value in the first column followed by two columns for the real and imaginary parts of the visibility at a single frequency for all selected baselines, would be

                fmt=base{ha;chan{re;im};\\n}

The special element $\backslash\backslash$n represents the actual character that will appear at the given position in the output (which is the NEWLINE character here). The only other special element that this syntax currently allows is $\backslash\backslash$t (TAB).

The (u,v,w) values for each baseline can be added to each row of the table by the following macro

        
                fmt=base{ha;u;v;w;chan{re;im};\\n}

However note that the following macro is in error

        
                fmt=ha;u;v;w;base{chan{re;im};\\n}

This is because the elements u,v,w are a function of the baseline and they do not appear as part of the body of the base operator. The macro parser will generate an error message pointing out the possible error in this macro.

The elements can also be qualified by a C-styled printf format field. Hence, for example, if the value $HA$ needs to be written with field length of 8 characters and precision of 3 digits, the fmt string would become

                fmt=base{ha%8.3f;u;v;w;chan{re;im};\\n}

The format for the numbers can be of type 'f','g','G','e', or 'E' (see the documentation on printf function of C language for more details).

Various output formats can be generated by changing the order of loops and elements in this syntax. Here are some examples. Each of these will generate a table. The values in the various columns will be as given in the explanation.

• fmt=base{ha;u;v;w;chan{re;im};\\n}
  

  Column 1 will be the Hour Angle. Columns 2,3, and 4 will have the u,v,w values followed by $2\times N$ columns for real and imaginary values for the N values that the chan operator can take. There will be one such row in the table for each value of the base operator.

• fmt=ha;lst;\\n;base{u;v;w;chan{re;im};chan{a;p};\\n}
  

  This format will generate a table with rows of unequal lengths.

  Row 1 will have only $HA$ and $LST$ values.

  Row 2 will have u,v,w in the first 3 columns followed by real, imaginary, amplitude and phase for all channels listed in the chan operator. There will be one such row for every value of the base operator.

• fmt=ha;base{u;v;w};\\n;base{chan{re;im}};\\n
  

  This macro will generate a table of set of two rows of unequal lengths per input data record.

  First row will have the $HA$ and $u,v,w$ values for each selected baseline.

  Second row will have the real and imaginary values of the visibilities for all channels of the chan operator and for all values of the base operator.