AIPS HELP file for ANTAB in 31DEC24
As of Thu Apr 25 16:02:12 2024
ANTAB: Task to read amplitude calibration info. into AIPS
INPUTS
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
HELP SECTION
ANTAB
Task: !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
! WARNING: If you are using Tsys infomation from the *cal.vlba* !
! file for data observed with the RDBE/MARK5C system (all data !
! from the VLBA after Jan 31, 2014 and occasional data before !
! this date), please be aware that *cal.vlba files from between !
! the dates of Jan 31, 2014 and October 19, 2015 are from the !
! VLBA LEGACY system. The LEGACY system signal path is very !
! different from the RDBE/MARK5C system. Do not use *cal.vlba* !
! file from BETWEEN THE ABOVE DATES unless you understand what !
! you are doing. !
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
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.
ANTAB should be run before USUBA. In this way the correct
subarray can be put with each TY and GC record by USUBA.
Running it after USUBA requires near duplicate TY and GC
records for each subarray even though only one applies at any
one time, antenna, etc.
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. You must use the CALIN
appropriate for SUBARRAY, no KEYIN parameters are
available in CALIN to limit the subarray.
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.
EXPLAIN SECTION
ANTAB: Task to read external amplitude calibration info. into
AIPS
Documentor: A. J. Kemball, A. Mioduszewski
Related programs: APCAL, CLCAL, FITLD, SNPLT, PRTAB
CALIBRATION TRANSFER
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.
INPUT FILE
The user must create an external text file containing the amplitude
calibration information. The VLBA supplies amplitude calibration
information in a format which can be processed by the task VLOG so that
it is suitable for use by ANTAB.
Examples:
The directory path or environmental variables may be used.
CALIN= '/home/mycomputer/calfiles/cal.dat
CALIN = 'myarea:cal.dat' (UNIX)
CALIN = 'disk$res:[username]cal.dat' (VMS)
where $MYAREA is an environment variable set before starting
AIPS. Under UNIX:
percent setenv MYAREA /mnt/username (csh)
$ export MYAREA="/mnt/username" (ksh)
If your VLBI data contains modes that are different enough that
FITLD automatically creates multiple files (e.g., different numbers
of IFs or polarizations) then the cal file provided by the VLBA also
contains mixed modes. ANTAB cannot handle this and will die when
the mode change is encountered. Therefor you must create separate
cal files for each mode from the original cal file and run VLOG on
them separately.
************************************************************************
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 2560 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.hh col1 col2 ... etc
Day_no hh:mm.mm col1 col2 ... etc
Day_no hh:mm:ss.ss 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
.
.
The format of the time stamp is flexible; use decimal hours or
sexagesimal with decimal minutes or seconds.
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.
=========================================================================