AIPS HELP file for UVLOD in 31DEC24
As of Wed May 1 17:10:46 2024
UVLOD: Task which copies Export or FITS tape UV data to disk
INPUTS
DOALL -1.0 1.0 > 0 => all sources in file
OBJECT Source name (blank => any)
QUAL -1.0 999.0 Source qualifier (-1 => any)
BAND Frequency band ('L','C',...)
blank => any
BCOUNT 0.0 1000.0 Sequential source number to
begin the loading
NCOUNT 0.0 1000.0 Number of sources to check
and perhaps load. 0 means 10.
INTAPE 0.0 9.0 Tape drive # (0 => 1)
NFILES -9999.0 9999.0 # of files to advance on tape
DATAIN Disk file name (FITS ONLY)
DOUVCOMP -1.0 1.0 >=0 => compressed data (FITS)
DOCONCAT -1.0 1.0 > 0 => concatenate all UV
data selected in one file.
DOKEEP -1.0 1.0 > 0 -> keep fully flagged
data records
OUTNAME Output UV file name (name)
blank => OBJECT
OUTCLASS Output UV file name (class)
blank => UVDATA
OUTSEQ -1.0 9999.0 Output UV file name (seq #)
-1 => tape seq # (FITS)
0 => high unique
OUTDISK 0.0 9.0 Output disk drive #
NPOINTS 0.0 Max # 1000's of visibilities
Adverbs DOALL, OBJECT, QUAL, BAND, BCOUNT, NCOUNT,
and NPOINTS apply only to Export format data files.
NPIECE 0.0 90.0 Maximum uv table piece number
to be loaded
ERROR -1.0 3.0 >= 2 -> do not use AIPS
history in the FITS file
HELP SECTION
UVLOD
Type: Task
Use: To copy a UV data base from an Export or FITS tape to a
catalogued file. Export tapes are likely to be left within the
data file unless DOCONCAT is true and BCOUNT + NCOUNT encompasses
the last source in the file. In that case and the case of FITS
format, the tape is left following the End-of-File mark of the
specified file.
UVLOD (and PRTTP, IMLOD, FITLD, TPHEAD) now understand and
interpret the standard world coordinate system keywords CDi_j
and PCi_j. They are used if possible and problems reported.
Data from MeerKAT will automatically have the polarizations
swapped, unless the FITS file reveals that the data have already
been in AIPS.. If you do not want this you will have to run SWPOL
after UVLOD.
Adverbs:
DOALL......> 0 => load all sources matching adverbs OBJECT, QUAL, and
BAND in the tape file.
< 0 => load only first match. (Not for FITS)
OBJECT.....The source name. Blank => any name ok. Standard
"wild-card" conventions are supported.
QUAL.......The source name qualifier. -1 => all quals
BAND.......Frequency band. blank => any. Not used for FITS
BCOUNT.....Load sources beginning with sequence number BCOUNT (see
PRTTP listing of tape).
NCOUNT.....Check and perhaps load only NCOUNT consecutive sources from
the tape.
0 => 10 (DOALL > 0),
0 => 100 (DOALL <= 0).
INTAPE.....Tape drive #. 0 => 1
DATAIN.....48-character name of the disk file from which to read a
FITS file. It must be in the form
:
or
:::
where is the remote computer name, is the
environment variable (logical name) for the disk area in
which the file named is stored. is
usually omitted when the file is local to the current
computer. For multi-piece FITS uv-table files (see NPIECE
below and task FITAB), it is the base name without the
appended sequence number or the full name of the starting
piece. (If the file DATAIN does not exist, the task looks
for DATAIN with a "1" appended.)
NFILES.....# of files to skip on tape before reading data.
0 => no tape movement at all.
DOUVCOMP...If true (DOUVCOMP >= 0) the output data is written in
compressed format which can result in a substantial
reduction in disk space needed. This can cause some loss
of spectral dynamic range (storage is integer 0 - 32767)
and a really bad data value can destroy all good data
values. The real differences in weights between IFs and
polarizations and spectral channels within a record are
also lost. Only used for FITS files of the random-groups
type (e.g. written by FITTP or CASA exportuvfits).
Binary tables have the compression selected by the
compression state of the table (e.g. FITAB).
DOCONCAT...> 0 = True = concatenate all selected data into a single uv
data file. Ignored if DOALL > 0. Does not apply to older
UV fits files, but does apply to FITS uv-table files
produced by FITAB.
DOKEEP.....> 0 -> keep any fully flagged vis records. Otherwise
they are not copied from the input file. They are
counted and reported in any case.
OUTNAME....Output UV file name (name). Standard behavior with default
= (in order) OBJECT and source-name.qual for Export data.
Default = (in order) tape value, OBJECT, source name, and
'NONE' for FITS.
OUTCLASS...Output UV file name (class). Standard behavior with
default = 'UVDATA' for Export and (in order) tape value and
'UVDATA' for FITS.
OUTSEQ.....Output UV file name (seq #). 0 => highest unique.
< 0 => use tape value if present (FITS only).
OUTDISK....Output UV file disk drive #. 0 => highest with space for
the file.
NPOINTS....Read and store a maximum of NPOINTS*1000 UV points
per source. (Not used for FITS) 0 => 50.
NPIECE.....Maximum piece number to read in a multi-piece uv-table FITS
data set. 0 => maximum in the data.
ERROR......>= 2 => do not parse AIPS history cards found in the FITS
header. Do not use this option until you have tried UVLOD
without it. If you get mysterious errors (usually error 4
which implies premature end of file), then try UVLOD with
ERROR set to 2. For a period of time, data sets written
out with FITAB, read back in, and then written out with
FITTP could have so many AIPS history records in their
header as to cause UVLOD to read the data wrongly.
EXPLAIN SECTION
UVLOD: Task to load UV data from tape to disk.
RELATED PROGRAMS: FITTP, FITAB, UVEXP, EXIND, PRTTP, MOUNT, DISMOUNT
PURPOSE
UVLOD loads UV data from a magnetic tape to disk. The UV data may
be written either in FITS format or in Export format. Tapes with FITS
format can be generated from AIPS using the task FITTP (random groups
type) or FITAB (uv-tables). Tapes with Export format are generated from
the AIPS task UVEXP or from the DEC-10 using EXPVIS. The FITS format is
recommended since no information is lost due to arbitrary restrictions
in the format. Normally the u-v data set has been calibrated already,
as initial data calibration is not generally performed in AIPS.
However, self-calibration and some forms of editing of the data set are
often performed within AIPS once the data set has been loaded. Some of
the adverbs are used only for Export format and are ignored with FITS
format data.
FITS format files can be read from a disk file on one of the AIPS
disks. This uses the adverb DATAIN.
GENERAL COMMENTS
The tape must be properly mounted and the correct density
specified. This is most easily done using the MOUNT command in AIPS.
When through reading the tape and no other tape processing is
anticipated, use DISMOUNT to free the tape drive for other users.
OUTDISK:
Make sure there is enough space for the source data on the
specified OUTDISK (see below). This is especially important if many
large data bases will be written onto the disk.
COMMENTS FOR FITS FILES
Most of the adverbs are ignored for FITS files. DOALL, OBJECT, QUAL,
BAND, BCOUNT, NCOUNT, and NPOINTS have no interest for FITS files of
either the random groups (FITTP) or table form (FITAB found only in
15APR99 and later).
NPIECE:
Maximum piece number in a multi-piece (multi-file) uv-table FITS
data set to be read. 0 => maximum in the data. These files are written
by FITAB in 15APR99 and later AIPS. If the first piece to be read is
noit the first piece written, position the tape, or set DATAIN, to the
first file to be read.
DOCONCAT:
If multiple pieces of uv-table files are being read, they will
automatically go into the same output disk file. If you wish this disk
file to be a pre-existing disk file, give DOCONCAT > 0 and specify the
output file name. Defaults NAME and CLASS will work, but it is
recommended that you set OUTSEQ. If OUTSEQ=0 or DOCONCAT<= 0, a new
file will be created. DOCONCAT does not apply to the random-groups form
of uv FITS files.
COMMENTS FOR EXPORT FILES
DOALL:
If DOALL is TRUE (> 0.0), UVLOD will load all sources matching the
OBJECT, QUAL, and BAND adverbs in the range from BCOUNT through
BCOUNT+NCOUNT-1. Each selected source will be put in a separate
catalogued disk file. The initial value is FALSE (<= 0), in which case
only the first source or sources (depending on DOCONCAT) matching these
adverbs will be loaded.
BCOUNT:
The PRTTP and EXIND tasks give a sequential listing of all sources
on the Export tape. This adverb specifies the first source within a
file that is considered for loading onto disk.
NCOUNT:
For Export tapes, this adverb specifies the total number of sources
which will be considered for loading on disk
DOCONCAT:
This adverb is considered only if DOALL is false (<= 0). If
DOCONCAT is true (> 0), UVLOD will concatenate the data for all sources
selected via the OBJECT, BAND, QUAL, BCOUNT, and NCOUNT adverbs. This
concatenation may be desirable for certain types of data (e.g. position
tracking of planets, frequency tracking of spectral lines). UVLOD does
not modify phases and the like for different source positions in the
concatenated sources. However, it does convert the baselines from time
units to wavelengths at the frequency given on the tape for the
particular source. This is exactly what is desired for
frequency-tracked data.
For a tape file containing a large number of sources from which
only one source is desired, it is a good idea to set DOALL false and
DOCONCAT false (<= 0). Otherwise, UVLOD will read through the entire
tape file (to BCOUNT+NCOUNT sources) before ending, even if the desired
source has long since been loaded to disk. This will waste both CPU and
user interactive time.
NPOINTS:
This adverb specifies the maximum number of UV points which will be
transferred to disk from an Export tape (not used for FITS-style tapes).
The value of NPOINTS is 1000 times the number of points to be
transferred, and should also be set at the lowest multiple of 1000
higher than the number of points to be loaded to disk (e.g., NPOINTS=17
for a data set containing 16,201 visibility records). The number of
visibility records can be found by running EXIND or on a log of the
EXPVIS program executed at the VLA.
There is a 20 percent leeway in NPOINTS. If you set NPOINTS=17, the UVLOD
will read upto 20,400 uv points before terminating. A warning message is
given if more data are found.
INTERACTION WITH OTHER PROGRAMS:
PRTTP will print out the contents of an entire tape including
Export uv files, IBM map files, and all kinds of FITS files.
FITTP and FITAB (15APR99 and later) are different means of using AIPS to
write UV data from disk to tape (e.g., after self-calibration); this
data can later be reloaded from both formats using UVLOD. In general,
the data are not in 'XY' sorted order after being loaded via UVLOD, so
UVSRT may need to be run to sort the data properly for some imaging
tasks.
EXECUTION TIMES:
The execution time depends on the location on the tape of
the desired data. If the user starts reading from the
beginning of the tape, required CPU time may be only 10 seconds
for data near the beginning of the tape and several minutes for
data close to the end of the tape, with a roughly linear
relation in between (i.e., most of the CPU time for a data set
not at the beginning of the tape is spent reading through the
tape to find the desired data set).
In an otherwise empty VAX 11-780 it takes about 5.5 min
to load 500,000 visibility points (all four polarizations)
DISK SPACE:
The size of a data set loaded via UVLOD is linearly
proportional to the number of UV records in the data. The
ratio of disk blocks to visibility records is roughly 1:7, so a
data set containing 50,000 visibility records will occupy
approximately 7,000 blocks of disk space. Be sure there is
enough space on OUTDISK to hold the data.