3.3 Your  data catalog files

Your uv data sets and images are your largest inputs to, and outputs from, . 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:

MCAT and UCAT list files based on the INDISK adverb, SCAT always lists all disks. 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:

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:

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  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  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  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  programs that read cataloged disk data sets. Use:

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:

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  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  verb RENAME. Typical inputs might be:

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  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  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  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 

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:

Output from IMHEAD on an image file might look like:

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 . 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.