; APCAL
;---------------------------------------------------------------
;! Apply TY and GC tables to generate an SN table
;# Task Calibration VLBI
;-----------------------------------------------------------------------
;;  Copyright (C) 1995-2000, 2003-2004, 2006, 2008, 2011, 2013-2014
;;  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
;-----------------------------------------------------------------------
APCAL     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
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
OPCODE                             Opacity correction opcode:
                                   '    ' -> no opacity corr.
                                   'GRID','GRDR','OPAC','OPCR',
                                     'LESQ' -> fit for opacity
APARM                              Calibration parameters:
                                   (1) -> B factor (def. 1.0)
                                   Opacity parameters:
                                   (2) -> ZA limit (deg)
                                   (3) >=0  use spillover
                                            correction
                                   (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
----------------------------------------------------------------
APCAL
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
       provided.
       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.
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.
  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 (-1 -> all)
  SOURCES....Sources to calibrate. A prefix of a minus sign indicates
             that all sources except the given source are to be
             calibrated.
  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 overwrite the specified SN table)
  OPCODE.....Opacity correction opcode:
               '    ' -> no opacity solution or correction.
               '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.  CALIN MUST BE BLANK, OR ELSE INVERS
             IS IGNORED AND INVERS MUST NOT BE ZERO.
  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
Related programs: ANTAB, CLCAL, FITLD, SNPLT, SNSMO, PRTAB, VLOG

                         PURPOSE

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.

                         OVERVIEW

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
performed.

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
number and setting CALIN=''.  IGNORE BELOW IF YOU ARE USING AND
ATTACHED WX TABLE.

          WEATHER INFORMATION FROM AN EXTERNAL TEXT FILE

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
follows:

  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
WEATHER SC /
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 -----

----------------------------------------------------------------------
