; ANTAB
;---------------------------------------------------------------
;! Read amplitude calibration information into AIPS
;# Task Calibration VLBI
;-----------------------------------------------------------------------
;;  Copyright (C) 1995-1999, 2001
;;  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 #
INFILE                             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.
  INFILE.....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:
      INFILE = 'disk$res:[username]cal.dat'             (VMS)
      INFILE = '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 INFILE 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.
=========================================================================






