; ANTAB ;--------------------------------------------------------------- ;! Read amplitude calibration information into AIPS ;# Task Calibration VLBI ;----------------------------------------------------------------------- ;; Copyright (C) 1995-1999, 2001, 2008 ;; 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 ;----------------------------------------------------------------------- ANTAB LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC ANTAB Task to read amplitude calibration info. into AIPS INNAME Input UV file name (name) INCLASS Input UV file name (class) INSEQ 0.0 9999.0 Input UV file name (seq. #) INDISK 0.0 9.0 Input UV file disk unit # CALIN Calibration file name. SUBARRAY 0.0 9999.0 Subarray (0=> 1) Output table versions: TYVER TY table to update GCVER GC table to update BLVER BL table to update SPARM List of stations to ignore PRTLEV Print level (0=>none; 1=> echo cal. file) OFFSET Increase the scan length of each side, minutes ---------------------------------------------------------------- ANTAB Task: This task reads amplitude calibration information supplied in an external text file and stores the information in the AIPS tables associated with the input uv-data file. This information, which includes system and antenna temperatures and antenna gain curves, can then be used to generate a solution (SN) table using task APCAL. The solution table is applied using task CLCAL in the standard manner, after optional editing or smoothing. In addition, baseline-dependent amplitude correction factors can also be entered which update the BL table directly. The BL table is applied by specifying a non-zero BLVER in those tasks that apply calibration. ANTAB must be executed separately for each subarray present in the data. ANTAB is intended primarily for use in calibrating VLBI data sets, and requires that the input uv-file be in the AIPS multi-source format with an associated index (NX) table. This task, in conjunction with APCAL, is a direct replacement for ANCAL. Adverbs: INNAME.....Input UV file name (name). Standard defaults. INCLASS....Input UV file name (class). Standard defaults. INSEQ......Input UV file name (seq. #). 0 => highest. INDISK.....Disk drive # of input UV file. 0 => any. CALIN......Calibration text file eg. 'FITS:ANTAB.CAL'. SUBARRAY...The subarray to calibrate. Run ANTAB separately for each subarray in the uv-data file. TYVER......Version number of the Tsys/Tant (TY) table to write (0 => highest). GCVER......Version number of the gain curve (GC) table to write (0 => highest). BLVER......Version number of the baseline based calibration (BL) table to write. (Only if BASELINE cards specified; 0 => highest) SPARM......List of additional 'stations' that KEYIN should ignore in the input file. PRTLEV.....Print level. A positive value will echo each line in the calibration file to the message console, which is useful for locating errors in the format of the calibration information. OFFSET.....Increase the scan length of each side. For non VLBA stations the TSYS measurement is provided between scans. As a result ANTAB can not match the measurement with source ID and frequency ID. OFFSET solves the problem increasing the scan by OFFSET minutes of each side. For VLBA and VLA it should be zero. ---------------------------------------------------------------- ANTAB: Task to read external amplitude calibration info. into AIPS Documentor: A. J. Kemball Related programs: APCAL, CLCAL, FITLD, SNPLT, PRTAB COMMENTS Amplitude calibration information for VLBA antennas is included in FITS files generated by the VLBA correlator from April 1 1999 onwards. ANTAB need only be run to load amplitude calibration data that was not transferred automatically. PURPOSE ANTAB reads external amplitude calibration information and stores that information in the AIPS tables associated with the input uv-data file. This information, which is supplied in a free-format text file, includes system and antenna temperature measurements taken during the observations, antenna gain curves and baseline-dependent amplitude correction factors. This information can subsequently be used to generate a solution (SN) table using task APCAL which, in conjunction with the baseline-dependent gains written directly into the BL table, can be applied to the uv-data in the standard manner (eg. task CLCAL). The generation of an intermediate solution (SN) table allows editing, smoothing and proper interpolation. This task, taken together with APCAL, is a direct replacement for ANCAL. COMMENTS The user must create an external text file containing the amplitude calibration information, using a text editor where necessary. The VLBA supplies amplitude calibration information in a format which requires little additional editing before suitable for use by ANTAB. Examples: CALIN = 'disk$res:[username]cal.dat' (VMS) CALIN = 'myarea:cal.dat' (UNIX) where $MYAREA is an environment variable set before starting AIPS. Under UNIX: % setenv MYAREA /mnt/username (csh) $ export MYAREA="/mnt/username" (ksh) ************************************************************************ Sometimes the KEYIN file contains additional lines for antennas that do not appear in the current data set. In this case ANTAB will fail citing 'UNKNOWN PARAMETER' and 'ERROR READING KEYIN FILE'. If, for example, the CALIN file contains records for MK [Mauna Kea] but MK does not occur in the data set, KEYIN would normally crash. This can be circumvented by setting SPARM = 'MK',''. Any element of SPARM which is not itself already recognized as a valid antenna, becomes an ignorable station. Any line in the input file containing an ignorable antenna is skipped - BE CAREFUL WITH SPARM, it is recommended that you first try running ANTAB with SPARM = '' to see what parts of the KEYIN file, if any, cause problems. ************************************************************************ The calibration text file can contain five different types of entries, identified by the following group keywords: i) CONTROL group: specifies default input format for Tsys or Tant entries. ii) BASELINE group: baseline-dependent ampl. gain factors. iii) GAIN group: gain curve entries iv) TSYS group: system temperature entries v) TANT group: antenna temperature entries. Each entry can extend over multiple lines and is terminated by a backslash "/". Only 200 characters per line are allowed and the delimiter (/) must be separated from the preceding character by at least one blank space. The input is free-format with no specific column requirements. Arithmetic expressions within parentheses will be evaluated, with allowed operators (+,-,*,/) eg. DPFU = (0.25*1.9). Any characters to the right of "!" are treated as comments. ANTAB may be run multiple times with the same values of TYVER, GCVER or BLVER. The more recent entries will overwrite older entries and the tables will be consolidated. Source identifications for the time entries in the calibration file are made using the index (NX) table. Consequently entries in the calibration file for time intervals not present in the uv-data file itself are ignored. If Tsys values are supplied for separate IF's in different text files (eg. VLA) these can all be appended to the same calibration file and identified with the appropriate index keywords as described below. All entries for a given antenna are consolidated over IF and polarization at the end of each ANTAB run. Specific descriptions of each group format are given below. Two important keywords, INDEX and INDEX2, which can be used in the CONTROL, TSYS and TANT groups, are explained in advance. These keywords specify the mapping between the column order used in the TSYS and TANT entries and the actual IF numbers and polarizations present in the AIPS uv-data file. The INDEX keyword consists of an array of 8-character strings which specify the mapping to be used for each column in the Tsys or Tant entry. The INDEX2 keyword supplements the information contained in the INDEX keyword and has exactly the same format. The allowed syntax for each entry is as follows (subject to an 8-character limit, and a unique mapping), a) 'R3' assign the colum to IF 3, RCP polarization. b) 'L1' assign the colum to IF 1, LCP polarization. c) 'R4|L4' assign the column to both IF 4 RCP and IF 4 LCP. d) 'R1:8' assign the column to all IF's 1-8 RCP. e) 'L10:16:2' assign the column to all even IF's 10-16 LCP. f) 'X' do not assign the column to any IF or polzn. If further assignments need to be made for a given column then use the keyword INDEX2 to supplement the above information. In all cases an INDEX entry must be provided for each Tsys or Tant column in the text file. For a sample Tsys format given below, 321 20:02.07 33.5 36.7 34.2 32.1 38.9 39.7 23.7 ! the index keywords could be used as follows: INDEX = 'R1:8:2', 'R3', 'X', 'X', 'X', 'X', 'X' INDEX2 = 'L1:8:2', 'L3', 'X', 'X', 'X', 'L7', 'X' This would map column 1 to IF 1-8 RCP and LCP, column 2 to IF 3 LCP and RCP, and column 6 to IF 7 LCP. The INDEX2 keyword is not necessary in all cases. ======================================================================= 1) The CONTROL group This must be the first group in the text file and is used to specify the default input format for the TSYS and TANT entries which may follow. The CONTROL group is optional; if not specified it will be assumed that Tsys values are supplied for all IF's and polarizations present in the uv-data file in IF-polarization column order at each Tsys or Tant time stamp (ie. 'R1', 'L1', 'R2', 'L2' .. or 'R1', 'R2', depending on the number of polarizations). An alternative default format may be specified using keywords INDEX and INDEX2 in the control group, in the manner described above. This will then be used for all antennas for which a specific INDEX format is not given. Example: CONTROL INDEX = 'R1', 'L1', 'R2', 'L2', 'R3', 'L3' / Note: INDEX2 keyword can optionally be added but the CONTROL keyword is required. No other keywords are expected in the control group. Unrecognized entries in the input calibration file are simply counted and reported by number. This minimises the editing necessary in modifying VLBA calibration files which may contain other information. ======================================================================== 2) The BASELINE group The baseline group is used to specify baseline-dependent amplitude gain corrections. These are entered directly into the BL table and are applied by general AIPS calibration tasks that accept a BLVER adverb. The format of these entries is as follows: BASELINE SC MK B = 1.9 / (* multiply all data in the St. Croix to Mauna Kea baseline by 1.9 in ampl. *) The exact form of the station names expected can be obtained by examining the AN table using PRTAB or PRTAN. Multiple BASELINE entries can be specified. These factors will be applied to all sources, IF's and polarizations on that baseline. ========================================================================= 3) The GAIN group This group is used to specify antenna-based gain curves, which are written in the gain curve (GC) table. Several formats are allowed for the gain curve entries but all require the following keywords: i) Antenna name as given in the AN table : eg. SC ii) Zenith point source sensitivity (K/Jy): DPFU = X: Single polarization DPFU = X,Y: Dual circular polarization (see RCP/LCP below). iii) Gain curve type : EQUAT : equatorial gain curve (function of Hour Angle/deg) ALTAZ : alt-az gain curve (function of Zenith Angle/deg) ELEV : elevation gain curve (in deg). GCNRAO: 2-d spherical harmonic expansion (Hour Angle/deg and (90-Declination)/deg), as used by GB 140 foot. With no further information the relative gain curves (with respect to zenith) will be assumed flat. Additional keywords can be supplied however, as follows: i) For EQUAT, ALTAZ or ELEV gain curves: a) TABLE or POLY = a0, a1, a2, ... The former indicates that the gain values are tabulated immediately after the GAIN group in a two-column format eg. 10.4 0.98 20.5 0.97 50.7 0.67 78.9 0.44 / where the first column is the gain ordinate (of type specified by EQUAT, ALTAZ or ELEV) and the second column the relative gain value. The POLY array specifies that the gain curve is a simple polynomial in the gain ordinate with coefficients of increasing order a0, a1, a2..etc. The POLY keyword can be used in conjunction with an OFFSET = x keyword which will shift the polynomial by x in the gain ordinate. This is the only case in which OFFSET can be used. b) DEC = x Specify the declination for which the gain curve is valid. Only allowed for EQUAT gain curves. Multiple GAIN entries can be given for each antenna with different DEC values to construct a two-dimensional gain curve for equatorially-mounted antennas. ii) For GCNRAO gain curves: a) The spherical harmonic coefficients are specified using the keywords: Gain curve term A00 1 A10 cos(90-dec) A11E sin(90-dec) cos(ha) A11O sin(90-dec) sin(ha) A20 0.5 (3 cos^2(90-dec) - 1) A21E 3 sin(90-dec) cos(90-dec) cos(ha) A21O 3 sin(90-dec) cos(90-dec) sin(ha) A22E 3 (sin^2(90-dec) cos(2 ha)) A22O 3 (sin^2(90-dec) sin(2 ha)) A30 2.5 cos^3(90-dec) - 1.5 cos(90-dec) Additional keywords for all gain curve types (EQUAT, ALTAZ, ELEV, GCNRAO) i) RCP or LCP Specify the polarization to which the gain curve applies. If not specified then assume it applies to all polarizations in the data. If DPFU = X, Y is specified, and the uv-data file has dual polarization, then X will be interpreted as the RCP value and Y as the LCP value. Separate gains for RCP and LCP in this case can also be specified as separate gain entries with the RCP or LCP keywords and DPFU = X. eg. a) RCP DPFU = 0.1 : Specify RCP gain b) DPFU = 0.2 : One gain for both RCP and LCP c) DPFU = 0.3, 0.4 : RCP = 0.3, LCP = 0.4 (only use this mode for dual-polzn. data) ii) FREQ = f1, f2 (* in MHz *) Sky frequency (in MHz) to which the gain curve applies. ANTAB will determine which IF and FQ-ID's are implied. Example: GAIN SC ELEV DPFU = 0.13 RCP FREQ = 4000,6000 TABLE / 10.0 0.56 20.0 0.78 . . 70.0 0.94 80.0 0.95 / (* This specifies the RCP gain curve at St Croix over the sky frequency range 4-6 GHz, with a zenith point source sensitivity of 0.13 K/Jy and a relative gain tabulated as a function of elevation. *) GAIN MK ALTAZ DPFU = 0.1 POLY = 1.0 / (* Flat gain curve for Mauna Kea, all IF's and polarizations, zenith point source sensitivity of 0.1 K/Jy *) ======================================================================= 3) The TSYS or TANT group These entries are used to identify a station with a list of Tsys or Tant values which follow it. The TSYS and TANT groups require a station name (as it appears in the AN table) and allow the following additional keywords: i) FT : Factor by which to multiply all values. Default of 1.0. ii) TIMEOFF : Time offset to be added to all entries. Default is zero. iii) SRC/SYS : All Tsys entries are actually Ta/Tsys (VLA) iv) RANGE = low,high: Range for permitted values. v) INDEX and INDEX2: see above. The format of the Tsys or Tant values which follow are: Day_no hh:mm.mm col1 col2 ... etc Example: TSYS SC FT = 1.05 INDEX = 'R1:8', 'L1:8' / 321 20:32.78 32.6 33.4 ! Values for RCP, LCP 321 20:34.01 31.6 35.8 . . Note: TANT entries are identical to TSYS entries except that the group keyword is different (TSYS vs TANT). Antenna temperatures may be measured in a wider bandwidth and should be assigned to all applicable IF's using the INDEX and INDEX2 keywords. Negative values or values of 999.9 are assumed indefinite. Records with invalid time formats are reported as an error. =========================================================================