As of Sat Jun 15 8:08:26 2024

APCAL: Task to generate an amplitude calibration SN table


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 #

ANTENNAS                           Antennas to calibrate
SUBARRAY          0.0     9999.0   Subarray 0 -> all
STOKES                             Stokes type ('R','L',' ')
BIF               0.0     4096.0   Start IF number
EIF                                End IF number
FREQID                             Freq. ID to calibrate
SOURCES                            Sources to calibrate
TIMERANG                           Time range to calibrate

TYVER                              TY table version number.
GCVER                              GC table version number.
SNVER                              Output SN table version.
                                     0 -> highest unique
                                     appends to existing file
OPCODE                             Opacity correction opcode:
                                   '    ' -> no opacity corr.
                                     'LESQ' -> fit for opacity
                                   'PLOT' plot input fit
APARM                              Calibration parameters:
                                   (1) -> B factor (def. 1.0)
                                   Opacity parameters:
                                   (2) -> ZA limit (deg)
                                   (3) >=0  use spillover
                                   (4) > 0  use all FQ in
                                            opac. soln.
                                   (5) Limit to sec(z) plotted
                                   (6) > 0 => normalize Tsys
                                       by average Tsys
                                   (7) Use IF AP(7) for
                                       normalization instead
SOLINT                             Solution interval (min)
                                      0 -> use all data
INVERS                             WX table version number.
                                      0 -> use text file
CALIN                              Text file with weather info.
                                      Must be ' ' if using WX
                                      table (INVERS).
TRECVR                               Receiver temperatures (K);
                                      in (R,L) pairs.
TAU0                               Zenith opacities (per ant.)
DOFIT                              Fit type (per ant.)
                                     -1 -> no opacity correction
                                      0 -> apply TRECVR only
                                      1 -> solve for Trec using
                                           fitting method spec.
                                           in OPCODE; then apply
PRTLEV                             Print level
DOTV                               TV selection (<0 -> PL file)
LTYPE                              Plot labeling
GRCHAN          0.0                TV Graphics channel to use


Task:  This task takes as input a system temperature (TY) table and a
       gain curve GC table, as produced by ANTAB or loaded by FITLD,
       and generates a solution (SN) table containing amplitude gain
       calibration information.  A correction can be made for
       atmospheric opacity as well. The data can be used to solve for
       the opacity or a pre-defined receiver temperature can be
       NOTE: run MERGECAL before running this task using calibration
             transfer data loaded using FITLD. If you do not APCAL may
             fail producing an intelligible error message.
       Plots are made showing system temperature versus zenith angle
       and apparent zenith opacity as a function of time.

       The task assumes that all included IFs have the same receiver
       temperature and opacity.  If you wish to solve them separately,
       you may set BIF, EIF, and, optionally, SNVER.  If you end up
       writing multiple SN tables, you must combine them when running
       CLCAL (adverbs SNVER and INVERS).  Note, the behavior of this
       task has changed (Jan 8, 2020) when SNVER specifies an existing

       NOTE that source fluxes are used in the computation of opacity
       so for precision work, they should probably be entered in the
       SU table with SETJY.  These fluxes are the full flux in the
       antenna beam, not the VLBI correlated flux and are used to
       adjust the atmospheric temperature by the antenna temperature
       induced by the source.  In most cases, this is negligible.
  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.
  ANTENNAS...Antenna numbers to calibrate. A prefix of a minus sign
             on any one or more of the antennas in the list, means
             that all antennas in the list are not calibrated and all
             antennas not in the list are calibrated.
  SUBARRAY...Subarray number to calibrate (0 -> all, 1 at a time but
             all to the same SN table)
  STOKES.....Stokes type to calibrate ('R' -> RCP, 'L' -> LCP,
             ' ' -> both RCP and LCP)
  BIF........Start IF number to calibrate
  EIF........End IF number to calibrate
  FREQID.....Freq. ID to calibrate.  If there are multiple FREQIDs in
             the FQ table, then you can do only one at a time since
             the code requires the frequencies of each IF.  If there
             is only one, you may set FREQID=-1 to allow all FREQIDs
             in the TY and GC table to be used.  That may not be a
             good idea, depending on how far apart the FREQID
             frequencies are.
  SOURCES....Sources to calibrate. A prefix of a minus sign indicates
             that all sources except the given source are to be
  TIMERANG...Time range to calibrate, in format: start_day,
             start_hour, start_min, start_sec, end_day, end_hour,
             end_min, end_sec, where the day numbers are relative to
             the reference date in the catalog header.
  TYVER......System temperature TY table version number to use
             (0 -> highest)
  GCVER......Gain table GC table version number to use
             (0 -> highest)
  SNVER......Output solution SN table version number
             (0 -> new table with highest unique version
             number; else ***append*** to the specified SN table)
  OPCODE.....Opacity correction opcode:
               '    ' -> no opacity solution or correction.
               'PLOT' -> no fit, plot model specified in TRECVR, TAU0
               'GRID' -> If DOFIT(ant) > 0 then perform an opacity
                         solution using a simple grid search from zero
                         to twice the specified receiver temperature
                         (TRECVR) and zenith opacity (TAU0).  If TRECVR
                         and/or TAU0 are not set then reasonable
                         defaults will be used.
               'GRDR' -> If DOFIT(ant) > 0 same as 'GRID' except it adds
                         a search down-weighting system temperature
                         outliers.  This takes about 10 times longer
                         than 'GRID'.
               'OPAC' -> If DOFIT(ant) > 0 then perform an opacity
                         solution using a simplex minimization taking
                         the values of receiver temperature (TRECVR)
                         and zenith opacity (TAU0) as starting points.
                         If TRECVR and/or TAU0 are not set then
                         reasonable defaults will be used.
               'OPCR' -> If DOFIT(ant) > 0 same as 'OPAC' except it adds
                         a search down-weighting system temperature
                         outliers.  This takes about 20 times longer
                         than 'OPAC'.
               'LESQ' -> If DOFIT(ant) > 0 then perform an opacity
                         solution using a least squares method.  LESQ
                         does not use TRECVR or TAU0.
             If DOFIT <= 0 then the receiver temperatures specified in
             TRECVR are used WITHOUT ALTERATION.  If OPCODE is set, for
             best results set either CALIN or INVERS for the weather
             data.  Otherwise a peak ground temperature of 20 degrees
             Celsius will be used.
  APARM......Calibration parameters:
                  (1) B factor (def. 1.0)
              Opacity parameters (use only if OPCODE <> ' ', and
              DOFIT >1):
                  (2) Zenith angle limit (deg) (def. 75).  This
                      sets the range of Zenith angles that are
                      used in the fits.  Therefor a relatively large
                      number (like 75, the default) is desirable.
                  (3) >=0  then use nominal spillover correction
                      = 2  the use the 7mm correction for all
                           frequencies (as done before October 2014)
                      < 0  then no spillover correction
                  (4) > 0 then use all FQ in opacity solution
                           opac. soln. (NOT RECOMMENDED)
                      <=0 then solve for each FQ ID separately
                  (5) Plot sec(z) no higher than APARM(5);
                      < = 0 => very large
             (6) > 0 => Modify the recorded Tsys(IF,t) on the
                   assumption that the Tcal's are not qquite correct.
                   For each antenna, this operation does
                     alpha(IF) = average over time of
                        Tsys(IF,t) / average over IF of Tsys(IF,t)
                   We then use as Tsys(IF,t) = TsysIn(IF,t)/alpha(IF)
             (7) If APARM(6) > 0, use APARM(7) as the IF to define the
                 correct Tsys(t) rather than the average over all IFs.
                 APARM(7) < 1 or > Nif or Tsys(APARM(7),t) blanked
                 causes the average to be used.
  SOLINT.....Solution interval for opacity solution (min)
               0 -> use all data
  INVERS.....WX table version number, to be used instead of
  CALIN......Text file with weather information (in format
               'LOGICAL:FILE.NAME').  Leave blank if using the
               WX table.
  TRECVR.....Receiver temperatures (K) for each antenna in (R, L)
             pairs (i.e.,. Ant 1 RCP, Ant 1 LCP, Ant 2 RCP, Ant 2
             LCP,..).  If all 0 and OPCODE is set to 'OPAC', 'OPCR',
             'GRID', or 'GRDR' ('LESQ' does not use this input)
             then receiver temperatures are estimated from the TY
             table.  For most cases this default works well.
             If DOFIT <= 0 then the receiver temperature is
             used with NO FITTING.
  TAU0.......Zenith opacities (per antenna; no polarization
             dependence).  If all 0 and OPCODE is set to 'OPAC',
             'OPCR', 'GRID', or 'GRDR'  ('LESQ' does not use this
             input) then the zenith opacity is estimated depending
             on the observing frequency.
  DOFIT......Opacity correction type (per ant.; no polarization
             dependence).  If ANTENNAS is set to include the list of
             antennas (none < 0), then DOFIT refers only to those set
             in ANTENNAS, i.e., DOFIT(i) refers  to the antennas
             number in ANTENNAS(i).  Otherwise DOFIT(i) refers to
             antennna i.
               -1 -> do not do opacity correction
                0 & OPCODE <> ' ' -> APPLY TRECVR ONLY
                1 & OPCODE <> ' ' -> solve for receiver temp.
                   using method specified in OPCODE; then apply
  PRTLEV.....Print level (1 -> echo weather file as read)
  DOTV.......TV device selection (1 -> TV; <0 -> PL file)
  LTYPE......Labelling type, see HELP LTYPE for details:
             1 = border, 2 = no ticks, 3 or 7 = standard, 4 or 8 =
             relative to ref. pixel, 5 or 9 = relative to subimage
             (BLC, TRC) center, 6 or 10 = pixels.  7-10 all labels
             other than tick numbers and axis type are omitted.
             Less than 0 is the same except that the plot file
             version number and create time are omitted.
             Add n * 100 to alter the metric scaling.
  GRCHAN.....Graphics channel to use: 0 -> more than one.


APCAL: Task to generate an amplitude calibration solution (SN) table.
Documenter: A. J. Kemball, Amy Mioduszewski


APCAL reads the system/antenna temperatures in the TY table and
the gain information in the GC table and generates an amplitude
calibration solution (SN) table. A correction for opacity can
optionally be made.  The opacity is the attenuation caused by the
atmosphere.  The solution table can subsequently be smoothed or
edited using SNSMO, and is applied using CLCAL. This allows the
selection of primary flux density calibrators.  At present TY
and GC tables for VLBA stations are attached to the data. For
experiments before April 1998 the TY and GC tables can be filled
by task ANTAB which reads an external calibration text file.


APCAL takes as input the uv-file for which amplitude calibration
is to be generated and expects TY and GC tables.  General selection
adverbs are provided (TIMERANG, SOURCES, BIF, EIF etc.) to select
those source and time ranges for which amplitude calibration is
required. In most cases default values are appropriate in which
case no selection is performed. The version numbers of the input TY
and GC tables are specified by TYVER and GCVER respectively. The
output SN table is specified using SNVER.

APCAL can operate in two distinct modes:

i) No opacity correction (OPCODE = '    '):

   In this mode APCAL will generate amplitude calibration without a
   correction for atmospheric opacity. All adverbs below OPCODE
   excluding APARM(1), which specifies the b-factor, can be ignored
   in this case.

ii) Opacity correction (OPCODE = 'GRID', 'GRDR',  'OPAC', 'OPCR'
       or 'LESQ')

   In this mode APCAL will generate amplitude calibration including
   a correction for atmospheric opacity. A local solution for opacity
   can be solved for (DOFIT = 1) or nominal receiver temperatures can
   be entered in TRECVR and used directly (DOFIT >= 1).  Three
   algorithms are presently implemented for the local solution
   for opacity ('GRID', 'OPAC' or 'LESQ').  With "robust" versions of
   'GRID' and 'OPAC' available as 'GRDR' and 'OPCR'.  The robust
   fits down-weight system temperature outliers, but take significantly
   longer than their non-robust versions.

                   SOURCE FLUX DENSITIES

APCAL will look in the source (SU) table for source flux densities
only if they are required to generate the amplitude calibration gain
factors. This is the case when calibrating antennas for which Ta/Tsys
or Ta values have been entered (e.g.,. VLA) or, more generally, if an
opacity solution is being performed. The source flux densities are
entered in the SU table using task SETJY. An error will be reported by
APCAL if source flux densities are required but cannot be found in the
source table. For weak sources which are not going to be used as
primary flux density calibrators when applying the amplitude
calibration using CLCAL (as selected by adverb CALSOUR), unit flux
density should be entered. Separate frequency Id's must be calibrated
separately as the source table can store flux densities for only one
FREQID at a time.

                         WEATHER TABLE

This information is only required if the opacity solution is being

The ground weather data is provided as an WX table attached to the VLBA
data as of April 1998.  Use this table by setting INVERS to the table


The ground weather data also available in the general VLBA calibration
text file but needs minor editing before it can be used by APCAL.  Use
VLOG to get it in the correct format (recommended) or edit the file as

  i) Write the weather data section to a separate file.
 ii) Replace all asterisks (*) in column 1 by a comment marker (!)
iii) Comment out all data lines containing an asterisk after the
     temperature data by inserting a comment marker (!) in col. 1.
 iv) Add the keywords: "WEATHER station_name /" at the beginning
     of each station section. Terminate each station section with
     a line containing a single backslash "/"

A truncated example file is given below:

! For antenna(s):   SC,HN,NL,FD,LA,PT,KP,OV,BR,MK
! For UT timerange: 1994DEC01/335 at 23:02:00 to 1994DEC02/336 at 11:00:00

 ----- Weather information for SC -----
! All values are instantaneous readings at the time indicated.
! A '*' following a value indicates it is not reliable.
!              Temp   Press  DewPt   Wind Spd/Dir    Rain   Gust
!UT Day-Time    C      mBar    C      m/s    deg      cm     m/s
336-08:02:08   27.5  1012.2   23.5    2.6    95.0    0.00    6.0
336-08:10:40   27.5  1012.4   23.6    2.0   138.0    0.00    6.3
336-08:19:12   27.4  1012.6   23.0    2.1    92.0    0.00    4.2
336-08:27:44   27.5  1012.7   23.2    2.2   103.0    0.00    6.0
336-08:36:16   27.5  1012.5   23.8    1.6    85.0    0.00    6.0
336-08:44:48   27.5  1012.4   23.9    1.9    70.0    0.00    5.3
336-08:53:20   27.4  1012.7   23.9    1.4    92.0    0.00    5.3
! 336-09:01:52   27.3* 1012.4   23.7*   3.3    78.0    0.00    4.9
! 336-09:10:24   27.3* 1012.6   23.7*   3.3   111.0    0.00    4.6
336-09:18:56   27.3  1012.9   23.4    1.2   113.0    0.00    5.3
336-09:27:28   27.4  1012.6   23.6    2.5    88.0    0.00    4.9
336-09:36:00   27.4  1012.6   23.5    2.4    91.0    0.00    4.9
336-09:44:32   27.5  1013.0   23.7    2.3   110.0    0.00    5.6
336-09:53:04   27.5  1013.1   23.4    1.9   105.0    0.00    5.6
336-10:01:36   27.6  1013.3   23.2    2.1    99.0    0.00    6.3
336-10:10:08   27.6  1013.3   23.7    2.9   132.0    0.00    5.6
! ----- Weather information for HN -----