; INDXR
;---------------------------------------------------------------
;! writes index file describing contents of UV data base
;# TASK CALIBRATION SINGLEDISH
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 1997, 2002, 2007-2010
;;  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
;-----------------------------------------------------------------------
INDXR     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
INDXR     Task to index a uv data base.
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                             Input file for forced scan
                                   breaks
PRTLEV                             Print level
CPARM            -1.0     9999.0   1=> max. time gap (min).
                                       0 => use self-adaptive
                                       method, like other tasks
                                   2=> max scan length (min).
                                       0 => 60 min
                                   3=> CL/CS entry interval in
                                       minutes.   0 => 5 min,
                                       < 0 => don't create a
                                       new table.
                                   4=> VLBA only: recalculate
                                       CL entry group delays
                                       using IM table data.
                                       0 => No recalculation,
                                       1 => Recalculate delays.
                                   5=> VLBA only: recalculate
                                       CL entry atmospheric
                                       group delays and clock
                                       offsets using MC table
                                       data.
                                       0 => No recalculation
                                       1 => Recalculate delays
                                   6=> single-dish only: maximum
                                       "antenna"/"beam" number
                                       in data set (if no AN)
BPARM                              VLA and EVLA ONLY: Opacity
                                   and Gain-curve control
                                   (see help)
CALIN
                                   Antenna gains file
----------------------------------------------------------------
INDXR
Type:  Task
 Use:  Creates an index (NX) table and indexes the uv data file.  A
       maximum time gap and a maximum scan length may be specified. If
       no CL (CS for single-dish data) table is present, an empty one
       is (optionally) created.  It may be filled with initial
       calibration values if desired (CPARM(4) and (5) > 0 for VLBA,
       BPARM(1) and (2) >= 0 for VLA).  If those initial calibrations
       have already been applied, then set CPARM(4)=CPARM(5)=0 and
       BPARM(1)=BPARM(2)=-1.  Data must be in T* order and may be in
       single-source or multi-source format.  CL tables are not
       created for single-source files.  The NX table is used to speed
       access to uv data sets by giving offsets into the file for time
       ranges, source numbers, and the like.  CL and CS tables,
       version 1, are the basis for interferometer and single-dish
       calibration.  Usually they are created as the data are read in
       (for the VLA with FILLM, for the VLBA with FITLD, and for some
       single-dish data sets with SD2UV) and should not be replaced.
       If they are lost or were never created (i.e. OTFUV in OTF 12m
       data), then INDXR may be used to create them if they are
       needed.

       Parameters CPARM(1) and CPARM(2) are particularly important for
       single-source files.

       For VLA data, options similar to those of FILLM control how a
       new CL table is created.  Corrections for atmospheric opacity
       and/or antenna gain may be inserted into the CL table under
       control of BPARM and CALIN.  Note that the corrections in the
       CL table written by INDXR will be not be identical to those
       written by FILLM.  This is the result of FILLM having available
       correct zenith angles from the VLA model of the Earth, while
       INDXR uses a simpler spherical Earth model.  The differences in
       the gain corrections is rather less than the uncertainties in
       the parameters entering the opacity and antenna gain models.

       The default opacity model is now based on an algorithm of Josh
       Marvel.  It uses the older model which mixes surface weather
       data with a seasonal model but always evaluates it at K Band.
       Then a large table is used to relate the K Band opacity to that
       at other frequencies.  This allows different opacities for each
       IF, while the old method used the same opacity for any IFs
       within the same band.  The old method is available by setting
       BPARM(1) to 100.  See EVLA Memo # 143 "Improving the frequency
       resolution of the default atmospheric opacity model" by Josh
       Marvil (NRAO), 04/06/2010.

       For VLBA data, the IM and MC tables may be used to set the
       group delays, atmospheric group delays, and clock offsets under
       control of CPARM(4) and CPARM(5).
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.....Input file containing lists of times which scan
                may not cross (eg. clock setting event times
                for space VLBI observations) see explain INDXR
                for details.
  PRTLEV.....Print level.  If PRTLEV > 0 then echo the contents
                of INFILE as it is read otherwise read it
                silently. Setting PRTLEV > 0 may help in
                locating errors in the input file.
  CPARM......CPARM(1) = max. gap in data in minutes.  If a gap
                longer than CPARM(1) is found, a new index
                record will be started.
                0 => use the routines used by other tasks like UVCOP
                to look at the gaps actually in the data to determine
                what is likely to be a scan break.
             CPARM(2) = max. length (in minutes) of a scan. If
                an uninterrupted section of data on the same
                source longer than CPARM(2) is found, a new index
                record will be started. 0 => 60 min.  [For
                single-dish data, a "SCAN" random parameter, if
                present, will also be used to determine scan
                boundaries.  In this case, set CPARM(2) to a
                high value unless you want to subdivide scans.]
             CPARM(3) = interval of CL (CS for single-dish)
                table entries in minutes.  If there are no CL/CS
                tables associated with the data a new one will
                be created with null (1's and 0's) entries.
                0 => 5 min.
                If CPARM(3) < 0, then a new CL or CS table will
                not be created.
             CPARM(4) = VLBA-only delay recalculation option.
                When recreating a CL table, the geometric group
                delays used by the VLBA correlator are re-
                calculated using information from the IM table.
                0 => No recalculation, 1 => recalculate delays.
             CPARM(5) = VLBA-only delay recalculation option.
                When recreating a CL table, the atmospheric
                group delays and the clock offsets are re-
                calculated, together with their derivatives,
                using information from the model components
                (MC) table.
                0 => No recalculation, 1 => recalculate delays.
             CPARM(6) = single-dish only: the maimum antenna or
                beam number actually in the data set.  This is
                used to cover up for absent antenna (AN) tables
                only.
  BPARM......Opacity and gain curve control.  For non-VLA/EVLA
                data, INDXR forces BPARM(1) and BPARM(2) to -1.
             Opacity is controlled by BPARM(1) and BPARM(10):
                BPARM(1) <  0  ->  no opacity correction.
                BPARM(1) =  0  ->  BPARM(1) = 20
                0 < BPARM(1) <= 10  ->  opacity correction is done,
                    with zenith opacity given by BPARM(1).
                BPARM(1) > 10  ->  opacity correction is done, with
                    zenith opacity taken as weighted average from
                    surface weather and seasonal model, with the weight
                    of the surface weather portion given in BPARM(10),
                    and the weight of the seasonal model portion given
                    by 1 - BPARM(10).  This requires a weather table.
                    If it is missing, BPARM(10) will be set to 0 and
                    the surface weather ignored.
                BPARM(1) >= 100 -> same as above but using the old
                    model where opacities depend only on observing
                    band rather than being the new, IF-dependent
                    values.  BPARM(1) > 100 may be appropriate for
                    backwards compatibility, but should not be used
                    with the EVLA.
                BPARM(10) - weight of surface weather model.  0 -> 0.5
                    If you want 0 set it < 0.
             Gain curve is controlled by BPARM(2):
                BPARM(2) <  0     ->  no gain curve correction.
                0 <= BPARM(2) < 2  ->  gain curve correction, with
                    coefficients which vary as a function of band and
                    antenna.  These coefficients are read from a file.
                2 <= BPARM(2) < 3 ->  gain curve correction, with
                    coefficients which vary only as a function of band
                    only.  These coefficients are read from a file.
                BPARM(2) >= 3     ->  gain curve correction, with
                    coefficients specified in BPARM(3), BPARM(4),
                    BPARM(5), and BPARM(6) for all bands and
                    antennas.
  CALIN......The name of a file to provide the antenna gains used to
             populate the initial CL table.  If CALIN is left blank,
             it defaults to a system file located at:
             'AIPSIONS:VLA.GAINS'.  The file is in free format with
             fields: a 1-character band code, antenna number, begin
             date in form YYYYMMDD, end date YYYYMMDD, and 4 gain
             curve coefficients.  The EVLA should get a new file, but
             we use the old one for now.
----------------------------------------------------------------
INDXR: Task to generate index tables
DOCUMENTOR: Chris Flatters
RELATED PROGRAMS: most tasks that handle uv data.

INDXR generates a new index (NX) table for a uv data set and,
optionally, a null calibration table.  Records in the NX table
are used to speed access to selected times in the uv data and,
in some programs, to define scan boundaries that can not be
crossed.

Scans are defined independently for each subarray and will
change when either the longest scan or longest gap criteria set
using CPARM are exceeded, when the source ID changes, when the
frequency ID changes, when the scan ID changes or when a time
listed in the file specified as INFILE is encountered.

The external text file is intended to specify times at which
there is potentially some change to the parameters of the
experiment that will affect calibration.  The principal example
of such a change is a clock-setting event at a space VLBI ground
station.  A clock setting event potentially changes the residual
delay for that station so that it is invalid for a fringe-
fitting solution interval to contain an event.

The file contains a number of blocks each of which specifies
forced scan breaks for a single subarray.  Each block begins
with a header that specifies the subarray to which the block
applies and has the form

SUBARRAY = i /

where i is a positive integer.

This is followed by a list of zero or more times specified as
a day of the year and a UTC time.  This list should end with
a forward slash.

An example of a complete block would be

SUBARRAY = 1 /
325 14:27:36.765
325 14:32:45.321
/

If there is more than one block for a single subarray then the
times from all of the blocks for that subarray will be combined.
Blocks for subarray that are not present in the data will be
silently ignored.
