; UVLOD ;--------------------------------------------------------------- ;! Read export or FITS data from a tape or disk ;# TASK UV TAPE FITS ;----------------------------------------------------------------------- ;; Copyright (C) 1995, 1998-1999, 2003, 2007-2008, 2010 ;; Associated Universities, Inc. Washington DC, USA. ;; ;; This program is free software; you can redistribute it and/or ;; modify it under the terms of the GNU General Public License as ;; published by the Free Software Foundation; either version 2 of ;; the License, or (at your option) any later version. ;; ;; This program is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. ;; ;; You should have received a copy of the GNU General Public ;; License along with this program; if not, write to the Free ;; Software Foundation, Inc., 675 Massachusetts Ave, Cambridge, ;; MA 02139, USA. ;; ;; Correspondence concerning AIPS should be addressed as follows: ;; Internet email: aipsmail@nrao.edu. ;; Postal address: AIPS Project Office ;; National Radio Astronomy Observatory ;; 520 Edgemont Road ;; Charlottesville, VA 22903-2475 USA ;----------------------------------------------------------------------- UVLOD LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC UVLOD: Task which copies Export or FITS tape UV data to disk 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. 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 ---------------------------------------------------------------- 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. 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. 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. ---------------------------------------------------------------- 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% 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.