3.3 Your AIPS data catalog files

Your uv data sets and images are your largest inputs to, and outputs from, AIPS. A summary record of all your disk data sets (uv data, images, beams and temporary “scratch” data created by active tasks) is kept in your disk catalog files (one per disk). To interrogate this catalog file, use:

> INDI  0 ; MCAT  C R

to list all images on all disks, or

> INDI  0 ; UCAT  C R

to list all uv data sets on all disks, or

> SCAT  C R

to list all scratch files on all disks.

MCAT and UCAT list files based on the INDISK adverb, SCAT in 31DEC18 always lists all disks. In 31DEC12, M2CAT and U2CAT list files based on the IN2DISK adverb. M3CAT, U3CAT, M4CAT, U4CAT, OCAT, and UOCAT are similar for the IN3DISK, IN4DISK, and OUTDISK adverbs, respectively.

A complete listing of the catalog file, which may be printed with PRTMSG, can be generated by:

> CLRNAME  C R

to reset INNAME, INCLASS, INSEQ, INTYPE, and INDISK,

> CATALOG  C R

to generate the listing.

which will list all of your disk data sets. To limit the listing to a particular name, class, sequence number, type, and/or disk, use a combination of the adverbs INNAME, INCLASS, INSEQ, INTYPE, and INDISK. The INNAME and INCLASS adverbs allow a rather powerful wild-card grammar; type HELP  INNAME  C R for details. Unless you want a hard copy, it is faster to use MCAT and UCAT, although they respond only to the INDISK adverb. A typical listing looks like:

CATALOG ON DISK  1  
CAT USID MAPNAME      CLASS   SEQ  PT     LAST ACCESS      STAT  
 18   76 3C166L5OK   .IIM001.    1 MA 27-OCT-1996 22:30:18  
 19   76 3C166L5OK   .IBM001.    1 MA 27-OCT-1996 23:02:14  
 22   76 3C166L5OK   .IIM001.    2 MA 28-OCT-1996 15:30:45  
CATALOG ON DISK  2  
CAT USID MAPNAME      CLASS   SEQ  PT     LAST ACCESS      STAT  
 22   76 1200+519    .IIM001.    1 MA 01-NOV-1996 23:50:10  
 23   76 1200+519    .IBM001.    1 MA 01-NOV-1996 23:59:58  
 24   76 1200+519    .QIM001.    1 MA 28-OCT-1996 00:10:10  
 25   76 1200+519    .UIM001.    1 MA 28-OCT-1996 00:19:19  
 28   76 1200+519    .ICL001.    1 MA 02-NOV-1996 00:35:20 WRIT  
 31   76 SCRATCH FILE.IMAGR1.    1 SC 02-NOV-1996 00:35:37 WRIT  
 32   76 SCRATCH FILE.IMAGR1.    2 SC 02-NOV-1996 00:35:39 WRIT  
CATALOG ON DISK  3  
CAT USID MAPNAME      CLASS   SEQ  PT     LAST ACCESS      STAT  
  2   76 3C138 A C   .UVSRT .    1 UV 22-OCT-1996 12:56:50  
 36   76 1200+519    .UVXY  .    1 UV 02-NOV-1996 00:32:50 READ  
 37   76 1200+519    .IMAGR .    1 UV 02-NOV-1996 00:34:25 WRIT

This user (identification number 76) has eight image files, three on disk 1 and six on disk 2. He also has two sorted uv data sets and an IMAGR uv work file on disk 3. There are two scratch (temporary) files on disk 2 which were created by IMAGR running out of AIPS1 (this determines their IMAGR1 classname). Image data files (images and beams) are distinguished by the type code MA. The uv data files are distinguished by the type code UV and scratch files by type SC.

Note that this user has encoded useful information other than the source name into the image file names on disk 1. These images were of 3C166 at L band with 50 kilo-wavelength (uv) taper. Such information is also carried in AIPS history files (see 3.4 below), but it is often useful to place it at a level where CAT can see it. The user also gave the UVSRT file in slot 2 on disk 3 a name that encodes the source name (3C138), the VLA configuration (A), and the observing band (C). Careful choice of AIPS file names can save much other bookkeeping. The file name can be any valid string up to 12 characters long. Also note how SEQ numbers distinguish different versions of a file with the same name; this and the global variables in AIPS are helpful features when doing iterative computations such as self-calibration.

3.3.1 Speedy data file selection

Each catalog entry has an identification number called the “catalog slot number”. The CAT column at the left of the listing above shows these catalog numbers. They can be used to set up inputs quickly for AIPS programs that read cataloged disk data sets. Use:

> INDI  n1 ; GETN  ctn1  C R

where n1 selects the disk and ctn1 is the catalog slot number.

The verb GETNAME (abbreviated through minimum match as GETN above) sets the adverbs INNAME, INCLASS, INSEQ, and INTYPE used by many tasks and verbs. Some tasks require a second, a third and even a fourth set of input image name adverbs. For these, use:

> IN2D  n2 ; GET2N  ctn2  C R

to set the second set, and

> IN3D  n3 ; GET3N  ctn3  C R

to set the third set.

> IN4D  n4 ; GET4N  ctn4  C R

to set the fourth set.

The verb GETONAME (GETO for minimum match) sets the adverbs OUTNAME, OUTCLASS and OUTSEQ to those of a pre-existing output file. GETO is particularly useful with calibration tasks that copy extension tables (e.g.CL or FG tables) from one database to another or for restarting an image deconvolution.

3.3.2 Catalog entry status

Note that several catalog slots on disks 2 and 3 in our sample catalog listing above do not have blank entries in the STAT column. This listing was made while the user was running a Clean deconvolution with IMAGR on the sorted uv data set in slot 36 — this uv data file is opened for READing. The Clean image file, ICL001 in slot 28, and the scratch and IMAGR files are opened for WRITing. Procedures that attempt to read files which are opened for writing, or vice versa, will be rejected with appropriate error messages. You must therefore note any non-blank entries in the STAT column carefully. In some situations (mainly involving system crashes or abortion of tasks [3.1.2]) files may be left in READ or WRIT status indefinitely. If this happens, you may reset the file status with CLRSTAT  C R after issuing the appropriate INDISK and GETNAME. Note that a WRIT status on a file which is not, in fact, being used at present probably indicates that the data in the file have been corrupted. Such files should usually be removed from your catalog by first clearing the file status with GETN nn; CLRST  C R then deleting them with ZAP  C R.

Before using a data set as input to an AIPS task, check that the data set has a clear status. (It is possible to let two tasks read the same data at the same time, but this is not recommended as it will usually slow execution.) Also note the data set’s disk number and its ordinal number in the catalog, as these are useful for GETN, GET2N, etc.

3.3.3 Renaming data files

Files may be renamed, after they have been cataloged, using the AIPS verb RENAME. Typical inputs might be:

> INDI  2 ; INNA  ’1200+519’  C R

to select disk 2 and set the input (old) name.

> INCL  ’IIM001’ ; INSEQ  1  C R

to set the rest of the input name adverbs, i.e., to select the file in slot 22 on disk 2 in the example above.

> OUTN  ’1200+51 15K’ ; OUTSEQ  2  C R

to set desired output name and sequence number.

> INP  RENAME  C R

to review the inputs.

> RENAME  C R

to rename the I image to ’1200+51 15K’ and reset its sequence number to 2.

Two verbs can be used to alter the catalog numbers of files. RENUMBER moves a file to an empty, user-specified slot; a one-line command to do this would be SLOT n; RENUM  C R where n is the new slot number. Note that n may now be higher than any slot numbers currently in use. RECAT compresses the catalog (i.e., it removes gaps in the catalog numbers) without changing the order of the entries in the catalog.

3.3.4 Header listings

Every image or uv data set in AIPS has an associated header file that contains information needed to describe the data set in detail.

The header also contains information on the number of extension files of each type that have been associated with the data set. The most important file extensions that can be associated with AIPS image data are the HIstory file described below, the CC or Clean component files (see Chapter 5) and the PLot files and SLice files (see Chapter 6).

Multi-source uv data files may have many extensions (see Chapter 4). The most important are the HIstory file, the ANtennas file (subarray geometric data, date, frequency and polarization information, etc.), the BP (bandpass) file for bandpass calibration data, the CL (calibration) file for calibration and model information, the FQ (frequency) file for frequency offsets of the different IFs, the FG (flag) file for editing information, the NX (index) file (which assists rapid access to the data), the SN (solution) file for gain solutions from AIPS calibration routines, and the SU (source) file with source-specific information such as name, position, and velocity. Chapter 4 describes the use of these extensions in some detail.

You can list the header file of any catalog entry on your terminal by following the GETNAME step above with 

> IMHEAD  C R

for a detailed listing, or

> QHEADER  C R

for a shorter listing.

The output of IMHEAD and QHEADER can also be printed using PRTMSG (at PRIORITY  2).

Output from IMHEAD on a multi-source uv data set might look like:

Image=3C345     (UV)         Filename=Z17G1_A     .MULTI .   1  
Telescope=SBLNKGYO           Receiver=VLBI  
Observer=FAP                 User #= 1353  
Observ. date=27-FEB-1991     Map date=13-JUN-1995  
# visibilities    112813     Sort order  TB  
Rand axes: UU-L  VV-L  WW-L  BASELINE  TIME1  WEIGHT  SCALE  
           SOURCE  
--------------------------------------------------------------  
Type    Pixels   Coord value  at Pixel    Coord incr   Rotat  
COMPLEX      1   1.0000000E+00    1.00 1.0000000E+00    0.00  
STOKES       4  -1.0000000E+00    1.00-1.0000000E+00    0.00  
FREQ       128   2.2228990E+10   63.50 5.0000000E+05    0.00  
RA           1    16 41 17.608    1.00      3600.000    0.00  
DEC          1    39 54 10.820    1.00      3600.000    0.00  
--------------------------------------------------------------  
Maximum version number of extension files of type SU is   1  
Maximum version number of extension files of type CL is   3  
Maximum version number of extension files of type HI is   1  
Maximum version number of extension files of type AN is   1  
Maximum version number of extension files of type NX is   1  
Maximum version number of extension files of type FG is   1  
Maximum version number of extension files of type SN is   1

Output from IMHEAD on an image file might look like:

Image=3C219     (MA)         Filename=3C219-BC-6  .ICL001.   1  
Telescope=VLA                Receiver=  
Observer=BRID                User #=   76  
Observ. date=06-SEP-1992     Map date=18-APR-1994  
Minimum=-1.89720898E-04      Maximum= 5.05501366E-02 JY/BEAM  
--------------------------------------------------------------  
Type    Pixels   Coord value  at Pixel    Coord incr   Rotat  
RA---SIN   510    09 17 50.662  263.00     -0.300000    0.00  
DEC--SIN   640    45 51 43.555  294.00      0.300000    0.00  
FREQ         1   4.8726000E+09    1.00 2.5000000E+07    0.00  
STOKES       1   1.0000000E+00    1.00 1.0000000E+00    0.00  
--------------------------------------------------------------  
Map type=NORMAL              Number of iterations=   50000  
Conv size=   1.40 X   1.40   Position angle=   0.00  
Observed RA   09 17 50.600    DEC  45 51 44.00  
Maximum version number of extension files of type HI is   1  
Maximum version number of extension files of type PL is   5  
Maximum version number of extension files of type SL is   1

Both QHEADER and IMHEAD list the maximum version numbers of the table extension files associated with a data set. Because you may acquire many versions of such tables during calibration, these verbs are often invoked during calibration in AIPS. In 31DEC12, verbs IM2HEAD. IM3HEAD, IM4HEAD, and IMOHEAD, as well as Q2HEADER, Q3HEADER, Q4HEADER, and QOHEADER appeared to make comparable listings for the second, third, and fourth input and the output file naming adverb groups, respectively.