10.1 AIPS format for single-dish data

Single-dish data in AIPS is treated as uv data with different, but related random parameters and with the imaginary part of the visibility replaced by an additive calibration or offset. The u and v random parameters are replaced by parameters labeled RA and DEC, although other labels such as ELON, ELAT, GLON, and GLAT are also recognized. (Conversion between these coordinate systems is not provided in the “uv” plane although some conversion can be done on images.) The random parameter data are the sample coordinates in degrees. The TIME1 random parameter is the time (IAT) since midnight on the reference date in days as with real uv data. The BEAM random parameter corresponds to BASELINE and is used to separate data which should be edited and calibrated separately (e.g., separate beams of a multi-feed system, different polarizations or observing runs of a multi-polarization system). The actual beam number is recorded as 257 times the desired number so that visibility-data tasks will recognize the “baseline” as auto-correlation data. Two other random parameters, SCAN and SAMPLE, have no relation to any visibility parameters and are simply used to retain the “scan” number and sample number within the scan which are traditional in single-dish observations. Very little is made of these, but INDXR will make a new index entry when the scan number changes and PRTSD will display the scan and sample numbers. SDVEL uses the scan numbers to determine when to update the reference velocity in some observing modes. Single-dish data may be stored in compressed form, in which the weight and compression scale are stored as random parameters exactly as in true visibility data. This should not be done if the applied offset is large as in beam-switched continuum observations.

The measured single-dish flux, usually in units of degrees Kelvin, appears in the real part of the “complex visibility.” The imaginary part of the visibility is sometimes used to hold an offset which can be applied to the data to remove, for example, a time-variable bias. The data weight is used to weight the data and should be proportional to σ-2, where σ is the uncertainty in the flux. The visibility sample can contain multiple polarizations, described with the STOKES axis (values 1 through 4 for I, Q, U, and V, respectively). The sample can also contain multiple spectral-line frequencies, described with a FREQ axis giving the observed reference frequency and increment in Hz.

The uv-data header in an AIPS data set is expected to contain the reference (usually central) longitude and latitude given either as 1-pixel coordinate axes and/or in the “observed” coordinate location. The convolution size is usually used to hold the single-dish beam width (fwhm) and rest frequency and velocity information should also appear with spectral-line data. Many of the parameters can be added to the header by the user if they are missing and needed. Verbs ADDBEAM, ALTDEF, and PUTHEAD are useful for this purpose. A complete data set will also have an antenna extension file giving the location of the antenna. This allows tasks to compute things like zenith angles and Doppler corrections when needed.

10.1.1 On-the-fly data from the 12m

At the present time, the only reliable routes for single-dish data into AIPS are provided by the tasks OTFBS and OTFUV. These tasks work only on beam-switched continuum and on spectral-line observations, respectively, from the NRAO 12m telescope. They use files in the UniPops native format and do not read the FITS table format written by UniPops. Both programs are designed for “on-the-fly” or “OTF” observing modes in which the telescope takes data rapidly while continuously changing its pointing position.

10.1.1.1 Listing OTF input files

To read OTF files, you must first define an environment variable to point to the disk area in which your data resides. This environment variable and your file names should be in upper case letters, but there is an AIPS “feature” which allows you to use lower case. On Unix systems, you may set the environment variable and rename the files to upper case with

% cd  /my/disk/directory  C R

to switch to the disk directory containing your data.

% setenv  MYAREA  ‘pwd‘  C R

to define $MYAREA under c shell, or

% export  MYAREA=‘pwd‘  C R

to define $MYAREA under Bourne, bash, korn shells.

% mv mysdd.file MYSDD.FILE  C R

to rename the data file to upper case letters.

% mv mygsdd.file MYGSDD.FILE  C R

to rename the gain file to upper case letters.

Then start your AIPS session.

To review the contents of your data set, use the task OTFIN which will list SDD modes, IF and scan numbers, times, coordinates, velocities, and number of samples. This output should help in setting the range of scan numbers to be loaded by OTFUV or OTFBS. Type:

> TASK OTFIN ; INP  C R

to list the required inputs on your screen.

> DATAIN ’MYAREA:MYSDD.FILE  C R

to specify the name of the 12m raw data file, where MYAREA is an environment variable which points at a disk data area and MYSDD.FILE is the name of your file in that area. See 3.10. If your environment variable and/or your file name contain lower case letters, type the name carefully with the correct case for all letters and leave off the second (close) quote mark. When you use this “feature” of the AIPS compiler, you cannot type anything following the DATAIN name (or other string adverb) on that line.

> BCOUNT 0 ; ECOUNT 0  C R

to include all 12m scans in the file.

> BIF 0  C R

to include all SDD “IFs.”

> DOCRT -1  C R

to print the listing on the line printer, or

> DOCRT 1  C R

to view the listing, one page at a time, on your terminal window. The width given (if > 72) should match the width desired; a width of < 72, as given here, uses the actual width of the window and so maximizes the information per line.

> INP  C R

to review the parameters.

> GO  C R

to run the task.

10.1.1.2 Reading spectral-line OTF files into AIPS

To run OTFUV after running OTFIN, type

> TASK OTFUV ; INP  C R

to list the required inputs on your screen.

> DATAIN ’MYAREA:MYSDD.FILE  C R

to specify the name of the 12m raw data file, where MYAREA is an environment variable which points at a disk data area and MYSDD.FILE is the name of your file in that area. See 3.10.

> DATA2IN ’MYAREA:MYGSDD.FILE  C R

to specify the name of the 12m gain file corresponding to the file specified with DATAIN.

> BCOUNT n1 ; ECOUNT n2  C R

to include 12m scans n1 through n2 in the output file.

> BIF 0 ; EIF  0  C R

to include all SDD “IFs” matching the lowest numbered one found. IFs which do not match in central frequency or channel width are skipped.

> DOUVCOMP TRUE  C R

to write the data in a compressed format. This reduces the size of the file by nearly a factor of 3 with no significant loss of information in this case.

> XINC 1 ; YINC  1  C R

to write out all data samples with no time averaging. One can smooth by YINC samples and write out the data every XINC sample times in order to reduce the size of the output data set and improve the signal-to-noise of the individual samples with only a minor loss of information..

> DOWEIGHT 1  C R

to use offs and gains interpolated to the time of each observation. This seems to produce better results.

> DETIME 0  C R

to add no offset to the actual observation times.

> BCHAN 0; ECHAN 0  C R

to include all spectral channels.

> CHANSEL 0  C R

to flag no channels. CHANSEL 31,34,3  C R, for example, would mark channels 31 and 34 as bad. Data may be edited later more selectively.

> INP  C R

to review the parameters.

> GO  C R

to run the task.

While OTFUV runs, it will show you (on the message monitor or your window) the name and location of the output AIPS file created and then provide a list of the scans and IFs read and the gain scans used upon them.

In many cases, the 12m in OTF mode observes two separate polarizations using the same center frequency and spectral resolution. In the UniPops/12m nomenclature, these are separate “IFs.” A similar nomenclature is used to distinguish the feeds in the multi-feed system. OTFUV can now read up to eight IFs at the same time, avoiding the necessity of multiple runs of OTFUV, followed by a data sort to restore time order. OTFUV will distinguish the IFs not by an AIPS “IF axis,” but by assigning them beam numbers equal to the SDD IF number (or autocorrelator baseline number equal to the SDD IF number with itself).

You may append data from another IF in the first input data set or data from another OTF pass on the source to the AIPS data set created above, by entering new DATAIN and DATA2IN names and new BCOUNT and ECOUNT ranges, if needed and

> BIF m1 ; EIF m2  C R

to load IFs m1 through m2.

> DOCONCAT TRUE  C R

to enable the concatenation mode.

> OUTDISK n ; GETONAME m  C R

to select the output file, where n and m are the output disk and catalog slot number used by the first run of OTFUV.

> FQTOL ff  C R

to allow data sets within ff MHz of each other to be concatenated. Doppler tracking will cause two OTF passes to appear to be at separate frequencies. Narrow-band, wide-field observations should not be concatenated in this way; see the discussion of SDVEL below (10.2.4).

> GO  C R

to run the task appending the additional data.

Another way to concatenate two 12m IFs — or multiple observing runs — is to create two output files with OTFUV and then concatenate them with DBCON. If the two OTFUV files are in time order, then DBCON will actually merge the two data sets, retaining the time order. Avoid the use of multiple sub-arrays, which are a useless complication in this case, by setting DOARRAY = 0. To have the most “complete” antenna file, put the data set with the higher 12m IF in the first input name set (INNAME, INCLASS etc.)

10.1.1.3 Reading continuum OTF files into AIPS

The NRAO 12m telescope can observe in a beam-switched continuum on-the-fly mapping mode. Such data may be read into AIPS and reduced, in a somewhat experimental fashion, into images. To read in the data (after using OTFIN), enter

> TASK OTFBS ; INP  C R

to list the required inputs on your screen.

> DATAIN ’MYAREA:MYSDD.FILE  C R

to specify the name of the 12m raw data file, where MYAREA is an environment variable which points at a disk data area and MYSDD.FILE is the name of your file in that area. See 3.10.

> BCOUNT n1 ; ECOUNT n2  C R

to include 12m scans n1 through n2 in the output file.

> BIF 0 ; EIF  0  C R

to include all SDD “IFs” matching the lowest numbered one found. IFs which do not match in central frequency or channel width are skipped.

> INP  C R

to review the parameters.

> GO  C R

to run the task.

While OTFBS runs, it will show you (on the message monitor or your window) the name and location of the two output AIPS files created (one for “plus” and one for “minus” beam throws) and then provide a list of the scans and IFs read with the number of samples. The two output files will have the same names except for a “+” and a “-” as the sixth character of the output class.

10.1.2 Other input data formats

Another method for getting single-dish data into AIPS is through the use of FITS-format binary tables. If the data are able to be put in a usable table, then the AIPS FITS reading tasks such as FITLD (see 5.1.2) can be used to read them into a disk table attached to a cataloged file. Then SDTUV can be used to convert the table into the uv format described above applying a variety of calibrations along the way. Unfortunately, the non-AIPS program that did the UniPops to FITS conversion has been lost and the AIPS FITS readers cannot handle the FITS tables written by UniPops. There are two problems with the latter: AIPS is unable to handle tables with more than 128 columns while UniPops writes tables with around 200 columns. Even if AIPS could be extended in some special task, it would be unable to handle the current UniPops tables since the parameters given do not correctly describe the contents. Specialized unpublished knowledge about each receiver is required to disentangle the coordinate information and data structure.

The task SDTUV expects a sequence of related tables each with a number of keywords giving useful information such as scan, observer, telescope, object, scan start UT date and time, sample rate, velocity, and the like. The data are then a regular time sequence with each row of the table containing the right ascension, declination, and data for N receivers. Breaks in the time sequence are assumed to be new scans found in the next table. SDTUV has the ability to apply receiver position offsets and pointing corrections and to fit and remove receiver baselines using a sliding median window and spline fit. Interference rejection, lateral defocusing corrections, and a priori baseline removal are also offered. At present SDTUV is an example of what can be done rather than a directly usable task. It is limited to continuum problems currently and is moderately restricted in the number of data samples that can be read in any one scan.

Therefore, it will be necessary to write some sort of program in addition to those in the standard AIPS release to get single-dish data into AIPS. We encourage anyone who develops such a program to provide it to the AIPS group so that we may offer it to other single-dish users.