; DELZN
;---------------------------------------------------------------
;! Determines residual atmosphere depth at zenith and clock errors
;# Task Calibration
;-----------------------------------------------------------------------
;;  Copyright (C) 2003-2004, 2006-2008, 2015
;;  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
;-----------------------------------------------------------------------
DELZN     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
DELZN     Determines residual atmosphere depth at zenith
INNAME                             Input UV file name (name)
INCLASS                            Input UV file name (class)
INSEQ             0.0     9999.0   Input UV file name (seq. #)
INDISK                             Input UV file disk unit #
SNVER                              Input SN table version
                                   0 => last
GAINVER                            Input CL table to copy to
                                   CL#=high+1 and then correct
                                   0=>high
APARM                              control parameters:
                                   1: what data to plot
                                      0=>zenith atmos. delay
                                      1=>clock error
                                      2=>Reference antenna
                                      3=>dispersion
                                   2: Number of terms in time
                                      polynomial for zen. atm.
                                      delay or dispersion
                                      0 => no atm fitting
                                   3: Number of terms in time
                                      polynomial for clock
                                      0 => no clock fitting
                                   4: Create CL table?
                                      0 => not create
                                      1 => create
                                   5: What correction to make
                                      in CL table?
                                      0 => only atmosphere
                                      1 => atmosphere + clocks
                                   6: Number of iterations in
                                      robust fit to data
                                      0 => none.
                                   7: > 0 -> plot points omitted
                                      from fit
                                   8: 0 => output file at evenly
                                           distributed times
                                      1 => output file at the
                                           CL table times.
                                   9: 0 => no plotting residuals
                                      1 => plot residuals
                                   10: 0 =>plot model vs
                                          recalculated data
                                      1 =>plot direct SN table
                                          data vs fitted models
                                          see help
SOURCES                            Source list ' '=>all.
CALSOUR                            Calibrator list ' ' => all
STOKES                             Stokes type to process
SELBAND                            Bandwidth to select (kHz)
SELFREQ                            Frequency to select (MHz)
FREQID                             Freq. ID to select, 0=>all
BIF               0.0      100.0   Lowest IF number 0=>all
EIF               0.0      100.0   Highest IF number 0=>all
TIMERANG                           Time range to use. 0=>all
ANTENNAS                           Antennas to select. 0=>all
SUBARRAY          0.0     9999.0   Subarray; 0 => 1.
NPLOTS                             Number of plots per page
                                     0=>5, -1=> Don't make plots
XINC              0.0     5000.0   Plot every XINC'th point
OPTYPE                             What data to read from the
                                   SN table:
                                   'MDEL' => multi band delay
                                   'PHAS' => phase delay
                                   'DISP' => dispersion
                                   'RATE' => fringe rate
                                   '    ' => 'MDEL'
OUTFILE                            Table of delays/derivatives
                                   for selected set of antennas
                                   in format suitable for
                                   CLCOR's option 'ATMO'/'ATMD'
PRTLEV                             0=> no printout.
                                   1 => print coefficients
                                   2 => print coefficients
                                        and their errors
                                        and rms of residual
DOHIST                             >0 => put coefficients in
                                         history file.
DOTV             -1.0       1.0    > 0 Do plot on the TV, else
                                   make a plot file
GRCHAN            0.0       8.0    Graphics channel 0 => 1.
BADDISK           0.0     9999.0   Disks to avoid for scratch
----------------------------------------------------------------
DELZN
Task:  This task estimates the zenith atmosphere delay dependence
       and clock error based on the SN table output for the selected
       calibrators.  For details on how to observe and use DELZN see
       AIPS Memo 110, "Strategy for Removing Tropospheric and Clock
       Errors using DELZN".

       The model that is fit for multi-band delay is
           MBdel = Clock(t) + Atmo(t) / sin (elevation)
       where both Clock and Atmo are polynomials in time with the
       order of the polynomials specified by APARM(3) and APARM(2),
       resp.  Dispersion is fit as Disp(t) / sin (elevation) with the
       order of the polynomial given by APARM(2).

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.
  SNVER......Input SN table version. If SNVER is equal zero or
             greater than the total number of the SN tables
             then SNVER is equal to the last existing SN table
  GAINVER....Input CL table version. If GAINVER is equal zero or
             greater than the total number of the CL tables
             then GAINVER is equal to the last existing CL table.
             The input CL table version (GAINVER) is copied to
             the output CL table version=(the last one+1), and then
             the output CL table is corrected.
  APARM......control parameters:
             1: what data to plot?
                0=> zenith atmosphere delay
                    Actually the following is plotted:
                    VAL(IANT-RANT)-CLOCK(IANT)+ATM(RANT)
                    The relevant polynomial presentation for ATM(IANT)
                    is plotted also
                1=> clock error
                    Actually the following is plotted:
                    VAL(IANT-RANT)-ATM(IANT)+ATM(RANT)
                    The relevant polynomial presentation for CLOCK(IANT)
                    is plotted also
                2=> reference antenna, if the reference antenna
                    is constant for the whole experiment
                    Actually the following is plotted:
                    -VAL(IANT-RANT)+CLOCK(IANT)+ATM(IANT)
                    The relevant polynomial presentation for ATM(RANT)
                    is plotted also.
                    The polynomial is the same (reference antenna)
                    But data are different as taken with different IANT
                3=> dispersion
                    what is plotted is VAL(IANT-RANT)+DISP(RANT)

                    VAL(IANT-RANT) data of SN table;
                    IANT is the antenna number;
                    RANT is the reference antenna number;
             2: Number of terms at the polynomial for zenith atmosphere
                presentation: linear =>2; quadratic => 3
                0 => no atmosphere fitting
             3: Number of terms at the polynomial for clock
                presentation: linear =>2; 2 is recommended
                0 => no clock fitting
             4: Create CL table?
                0 => not create
                1 => create
             5: What correction to make in CL table?
                0 => only atmosphere
                1 => atmosphere and clocks
             6: Number of iteration in robust attempt at a solution
                0 => none
                At each iteration of the input data (SN table), the
                residual of each data point relative to the solution
                is found.  If the residual exceeds given number of
                R.M.S, the data are not used in the following solution.
             7: > 0 => plot the data samples omitted during the last
                iteration of the robust solution.
             8: What times for the output file to calculate?
                0 => output file at the even distributed times at
                     the data time interval. This option is desired
                     when the calibrators and target sources are
                     located at the different UV data. So correction
                     of CL table should be excluded.
                     Put  APARM(4) = 0.
                1 => output file at the CL table times.
             9: 0 => do not plot residuals
                1 => plot residuals (in panel separate from values/fit)
            10: 0 => plot the requested model (APARM(1)) AND the
                     adjusted data versus time.
                     In the case of OPTYPE='MDEL', the adjusted data
                     are for antenna Ant
                     aparm(1)=0   MBdelays + model(RefAnt) - model(clock)
                              1   MBdelays + model(RefAnt) - model(Ant)
                              2   MBDelays - model(Ant) - model(clock)
                     where model(xx) is the fitted polynomila in time
                     for parameter xx.  The data samples are drawn as
                     vertical lines and the model of delay, clock, or
                     reference antenna delay is drawn as a connected
                     line,
                1 => plot the data directly and the fitted models
                     versus time.  The data are vertical lines and the
                     model points are horizontal lines.  If the
                     residuals are small, the two then make plus
                     signs.
              314 => fource simulated rate for optype='rate'
                       else => use the actual rate from the SN table
  SOURCES....list of sources to process.
             ' ' = all; a "-" before any source name
             means ALL listed sources will be skipped.
  CALSOUR....list of calibrators to use.
             ' ' = all; a "-" before any calibrator name
             means ALL listed calibrators will be skipped.
  STOKES.....The desired Stokes type of the output data:
             'R', 'L', '  '=> all available.
  SELBAN.....Bandwidth to select (kHz)
  SELFREQ....Frequency to select (MHz)
  FREQID.....Frequency ID to select. 0=>all
  BIF........First IF to process. 0=>all.
  EIF........Highest IF to process. 0=>all higher than BIF
  TIMERANG...Time range of the data to be used. In order:
             Start day, hour, min. sec, end day, hour, min. sec.
             Days relative to reference date. 0=>all
  ANTENNAS...A list of the antennas to be calibrated, plotted and
             corrected.  If any number is negative then all
             antennas listed are ignored.
             All 0 => use all antennas.
  SUBARRAY...The subarray to calibrate. Does only one at a time.
  NPLOTS.....Number of plots per page; 0=>5.
             If NPLOTS < 0, then no plots are made.
  XINC.......Plot every XINC'th point
  OPTYPE.....What data to read from the SN table:
             'MDEL' => multi band delay
             'DISP' => dispersion
             'PHAS' => phase delay
                  Formally OPTYPE = 'PHAS' works, but there is
                  nothing to solve the twopi phase ambiguity
             'RATE' => fringe rate
                  The OPTYPE='RATE' is recommended when accuracy
                  using delay is not high (bandwidth is small),
                  but accuracy using fringe rate is better
                  (time averaging is high)
             '    ' => 'MDEL'
  OUTFILE....For MDEL:
                Table of zenith atmosphere delays, clocks shift and
                their derivatives for selected set of antennas in
                format suitable for CLCOR's option 'ATMO'.
                The file format:
                       The first line is number of the data rows.
                       The remaining lines specify the data with one
                       line for each antenna/time as:
                       Column 1: antenna number;
                       Column 2-5: day, hour, min, sec
                       Column 6: zenith atmosphere delay, in cm
                       Column 7: clock delay, in cm
                       Column 8: derivative of the zenith atmosphere
                                 delay, in sec/sec*1.0E14
                       Column 9: derivative of the clock delay (clock
                                 drift), in sec/sec*1.0E14
                 The values given at the atmosphere/clock delay
                 and their derivatives correspond to the desired
                 corrections. CLCOR should add them to the corrected
                 CL table values.
             For DISP:
                Table of zenith dispersive delays and their
                derivatives for selected set of antennas in format
                suitable for CLCOR's option 'DISP'.
                The file format:
                       The first line is number of the data rows.
                       The remaining lines specify the data with one
                       line for each antenna/time as:
                       Column 1: antenna number;
                       Column 2-5: day, hour, min, sec
                       Column 6: zenith dispersive delay, in 1/cm
                       Column 7: derivative of the zenith dispersive
                                 delay, in sec/m^2/sec*1.0E14
  PRTLEV.....0 => Don't print the coefficients.
             1 => print the fitted coefficients for each antenna.
             2 => print coefficients and their errors and
                  rms of residual for each antenna.
  DOHIST.....if DOHIST > 0, the gain coefficients are written
	     into the history file.
  DOTV.......> 0 Do plot on the TV, else make a plot file
  GRCHAN.....Graphics channel 0 => 1.
  BADDISK....A list of disks on which scratch files are not to
             be placed.  This will not affect the output file.
----------------------------------------------------------------
DELZN:  Task to estimate the zenith delay and clock error dependence
        on time based on the CALIB output SN table for the selected
        calibrators.
Documenters: L.R. Kogan
Related Programs: CLCAL, ELINT

                            PURPOSE

   Model of the atmosphere delay and the clock error implemented into a
correlator never coincides with the actual values.
The task restores the residual atmosphere delay at the given elevation
observing calibrators at wide range of elevations. The task reads the
SN table, taking the information about the delays (rate) at given antenna
observing given calibrator. This delay (rate) is contributed by delay
at the atmosphere and delay (rate) due to the clock error.
   The task separates the atmosphere and clock delays using the
least square method to fit polynomial of the chosen degree to the clock
error and polynomial of the chosen degree for the zenith atmosphere delay.
   Having known these polynomials the task calculates the zenith
atmosphere delay and records it to the output file ready for use
as input file for the task CLCOR (option 'atmov').
   The  fitted zenith atmosphere delay and clock error is used to
correct the delay for target sources putting the correction to
the output CL table  by the same way CLCOR does at option 'atmov'.

For details on how to observe and use DELZN (OPTYPE='mdel') see
AIPS Memo 110, "Strategy for Removing Tropospheric and Clock Errors
using DELZN".


Leonia's explanantion of APARM(10)
  10: 0 =>plotting model vs  recalculated data
          for example: OPTYPE=MDEL;
          then the direct SN table data are:
          VAL(IANT-RANT) = MODEL_ZATM_IANT*MAP_IANT -
          MODEL_ZATM_RANT*MAP_RANT + MODEL_CLOCK             (1)

          If we want to plot zenith atmosphere at the IANT
          APARM(1)=0 then
          the fitted model of zenith atmosphere at the IANT
          MODEL_ZATM_IANT is derived from the equation(1) and
          plotted  as the function of SN table data VAL(IANT-RANT)
          and of MODEL_ZATM_RANT and of MODEL_CLOCK.
          Thus, the following equation is plotted:
                MODEL_ZATM_IANT = [VAL(IANT-RANT)+
                              MODEL_ZATM_RANT*MAP_RANT -
                              MODEL_CLOCK] / MAP_IANT        (2)
          The relevant polynomial presentation for the zenith
          atmosphere at the IANT is plotted also.
       1 =>plotting direct data versus fitted models:
           The direct data from SN table VAL(IANT-RANT)
           (left side of the equation 1)
           is plotted versus the right side of the equation 1.
           The relevant models are the fitting polinomials.
