; UVAVG
;---------------------------------------------------------------
;! Average or merge a sorted (BT, TB) uv database
;# TASK UV UTILITY
;-----------------------------------------------------------------------
;;  Copyright (C) 1995
;;  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
;-----------------------------------------------------------------------
;---------------------------------------------------------------
UVAVG     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
UVAVG     Task to average or merge 'BT' or 'TB' sorted UV data.
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 #
OUTNAME                            Output UV file name (name)
OUTCLASS                           Output UV file name (class)
OUTSEQ           -1.0     9999.0   Output UV file name (seq. #)
OUTDISK           0.0        9.0   Output UV file disk unit #.
XINC              0.0              Write every XINC'th record.
YINC              0.0              Averaging time (sec).
                                     Will not be multiplied by
                                     0.95 as in older versions.
                                   Input avg time for merge.
ZINC              0.0              Time (secs) to which data
                                   were pre-averaged. It must be
                                   close to the true one.
                                   0 => ignore
OPCODE                             'MERG' for Merge function.
                                   Anything else for average.
OPTYPE                             'CROS' - merge xc data
                                   'AUTO' - merge ac data
                                   Anything else => merge all.
----------------------------------------------------------------
UVAVG
Task: This task will average or merge a 'BT' or 'TB' sorted
uv data set in time.
Adverbs:
  INNAME.....Input UV file name (name). Sort must be 'BT'
             or 'TB'.  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.
  OUTNAME....Output UV file name (name).    Standard defaults.
  OUTCLASS...Output UV file name (class).   Standard defaults.
  OUTSEQ.....Output UV file name (seq. #).  Standard defaults.
  OUTDISK....Disk drive # of output UV file. 0 => highest with
             space for the file.
  XINC.......Write only every XINC'th output record.
  YINC.......Averaging time (sec).   < 0.2 => 0.2
             This must be the correct input average time for
             the merging function.
  ZINC.......Time (sec) to which data have already been
             pre-averaged. UVAVG uses this to estimate the size
             of the output file. 0 => ignore.
  OPCODE.....'MERG' for merge function, anything else for
             average.  Merge selects the data with the highest
             weight within each YINC seconds.  For use on VLB
             data where some baselines are repeated in
             processing and for putting together polarization
             or spectral line data sets.
  OPTYPE.....'AUTO' - just merge autocorrelation spectra;
             'CROS' - just merge cross-power spectra;
             '    ' - merge both.
             Adverb only used in MERG mode.
---------------------------------------------------------------
UVAVG:  Task to average 'BT' or 'TB' sorted UV data
DOCUMENTOR: R. C. Walker  NRAO/CV
RELATED PROGRAMS:  UVSRT

                   PURPOSE

     UVAVG averages or merges 'BT' or 'BT' sorted uv data
bases.  The average function is especially useful if a large
data base can be reduced in size to make it more manageable.
Care should be taken that the average time is not so long that
'time average smearing' occurs - ie. that the longer baselines
sweep through enough uv space in an integration interval to
smear significant structure.
     Averaging is often used after VBFIT on VLBI data.  Longer
averages are allowed at that point because relatively high
residual fringe rates due to atmosphere etc have been removed.
     The merge function in UVAVG replaces VBMRG and works on
'TB' or 'BT' data with the same restrictions as for averaging.
This function is used to eliminate duplicate data after
multi-pass VLBI processing and to form full polarization or
many channel spectral line data bases from separate channel
inputs.  The input data sets must have records long enough to
hold the full number of channels - see DBCON if changes need
to be made.
     UVAVG can be used to thin out a data set while leaving
it properly configured for self cal.  If XINC greater than
1 is specified, UVAVG will only write every XINC'th output.
If the input data is in 'TB' sort order, all baselines for
every XINC'th time interval are written so that complete
data sets for each time remain and can be self-cal'ed.  This
function should be useful, for example, if a small data set
sharing about the uv coverage of the main data set and not
subject to time average smearing is desired for the first
few iterations of hybrid mapping or self cal.  The function
works in either the merge or average modes.
     The time windows used for merging or averaging are of
a length set by YINC and are timed such that one record
begins at 0 hours UT (not IAT).
     There is a limitation on the product of the number of
baselines (NBAS) and the number of words per visibility record
(LREC) that can be averaged if the input sort order is 'TB'.
The limit is currently  NBAS*(LREC+1) < 14790.  Typically LREC
is 3 times the number of correlators (4 for polarization) plus
5 (for u, v, w, time, and baseline).  It should be possible
to average 8 correlators on 30 antennas (435 baselines - if
28 antennas are in the AN file, as is the usual VLA case,
space is allocated for all possible combinations) or larger
numbers of correlators on smaller arrays.  There is also a
limit of 30 to the number of stations allowed in the antenna
file.  The space limitations do not apply if 'BT' sort order
is used.
     UVAVG marks the data with a time that is the weighted
average time of the data when averaging and is the time of the
record containing the last accepted correlator data when
merging.  For most purposes, this is proper, but it can cause
trouble when VLBI data is transfered to the Caltech package.
The times for data points corresponding to the same average
interval are not the same so they are treated as separate
points by VBCIT.  This does not work well in the Caltech
format.  To avoid the problem, the data can be averaged in the
Caltech package or UVAVG output can be run through the Caltech
averaging program with the same average time that was used in
UVAVG.  The records should be properly combined in this way.

                   COMMENTS

XINC:
     This controls the output.  It should be an integer and
causes only every XINC'th record to be written.  For 'TB'
sorted data, all baselines for every XINC'th time interval
are written so the data set may still be self-caled.

YINC:
     This sets the averaging time in seconds.  For averaging,
specify the output average time.  For merging, specify the
input average time.  If YINC is not correctly specify, the
merging function may not behave correctly.

ZINC:
     ZINC defines the pre-average time interval in seconds,
i.e. the time to which the data in the input file have
already been averaged.
     If ZINC is set to 0 then the output file created will
initially be as large as the input file. After UVAVG has
finished the unused disc space allocated to the output file
will then be released. If ZINC is nonzero then UVAVG will
estimate the size of the output file needed (plus a little
extra, just in case..) and will still shrink it after it has
finished if necessary. The use of ZINC is recommended if
particularly large files are being averaged.

OPCODE:
     If OPCODE='MERG' is specified, UVAVG selects data from one
input record for each YINC time interval.  The data selected
for different correlators (polarizations, spectral channels
etc.) can come from different input records.  Normally either
the record with the highest weight, or, if the weights are
equal, the last record in, are selected.  If the weights
are equal and the amplitudes differ by more than a factor of
two, the record with the highest amplitude is selected.  The
u, v, w, time, etc in the output record are those of the
last bit of data selected, regardless of polarization etc,
for that output record.
     If OPCODE not equal to 'MERG', the data is averaged,
weighted by the data weights.

OPTYPE:
     When MERG mode is specified a problem may arise if the
autocorrelation data have a different averaging time from the
cross-correlation data (common in VLBI experiments). In this
case the YINC will be different for the two sorts of data.
When this occurs you must run UVAVG in MERG mode on the data
twice, setting YINC to the appropriate value for the XC or
AC data and then setting OPTYPE to either 'CROS' or 'AUTO'.
In this case only the relevant data are merged, the other data
type is passed through unscathed.

SORT ORDER:
     The input data base must be in 'BT' or 'TB' sort order.
See above discussion of data set size limitations for 'TB'
sorted data.

EXECUTION TIMES:
     The run time on an otherwise empty VAX 11-785 is

                 3.0 * (D / 100,000) cpu minutes

where D is the number of input UV points.
(This run time is for AVER and may be out of date - RCW)
