; BLAVG
;---------------------------------------------------------------
;! Average cross-polarized UV data over baselines.
;# TASK UV Calibration
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 2000
;;  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
;-----------------------------------------------------------------------
;---------------------------------------------------------------
BLAVG     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
BLAVG     Task to baseline average cross-polarized 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 #
SOURCES                            Source list. See important
                                      note in HELP file!
TIMERANG                           Time range to use.
FREQID                             Freq. ID to select.
                                   For phase alignment:
BCHAN             0.0     2048.0      Start channel 0=>all
ECHAN             0.0     2048.0      End channel 0=>all
BIF            -100.0      100.0      Lowest IF number 0=>all
EIF               0.0      100.0      Highest IF number 0=>all
ANTENNAS                           Antennas to use
FLAGVER                            Flag table version
DOCALIB          -1.0        2.0   If >0 calibrate data
                                   = 2 calibrate weights
GAINUSE                            Cal table to apply
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 #
SOLINT            0.0              Pre-averaging time (min)
REFANT            0.0      100.0   Reference antenna
----------------------------------------------------------------
BLAVG
Task:  This task averages cross-polarized UV data over baselines
       to allow R-L phase and delay offsets between IFs to be
       determined by FRING and POLSN.

Adverbs:
  INNAME.....Input UV file name (name). Sort must be '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.
  SOURCES....List of sources to process.  '*' = all;
             a "-" before a source name means all except ANY
             source named. NOTE! Selection of only ONE source is
             not implemented correctly -> use TIMERANG instead.
  TIMERANG...Time range of the data to average. In order:
             Start day, hour, min. sec, end day, hour, min. sec.
             Days relative to ref. date.
  FREQID.....Frequency identifier to select (you may determine
             which is applicable from the OPTYPE='SCAN' listing
             produced by LISTR).
  BCHAN......First channel to use for phasing. 0=>1
  ECHAN......Highest channel to use. 0=>all higher than BCHAN
  BIF........First IF to use for phasing. 0=>all.
             <0 => don't use this IF.
  EIF........Highest IF to use. 0=>all higher than BIF.
             Ignored, if BIF<0.
  ANTENNAS...A list of the antennas to include in the average.
             If any number is negative then all antennas listed
             are NOT to be used and all others are.
             All 0 => use all.
  FLAGVER....Specifies the version of the flagging table to be
             applied. 0 => highest numbered table.
              <0 => no flagging to be applied.
  DOCALIB....If true (>0), calibrate the data using information in the
             specified Cal (CL) table for multi-source or SN table for
             single-source data.  If > 1.5, also calibrate the weights
             (new for VLA, normal for VLBI).
  GAINUSE....version number of the CL or SN table to apply to
             the data.  0 => highest.
  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.
  SOLINT.....Pre-averaging interval (min).   0 => 1.0
  REFANT.....Reference antenna (must be given).
---------------------------------------------------------------
BLAVG:  Task to average cross-polarized UV data over baselines
DOCUMENTOR: K. J. Leppanen  NRAO/SOC
RELATED PROGRAMS:  FRING, POLSN, CRSFRING (procedure)

                   PURPOSE
     BLAVG averages cross-polarized data over baselines and
time. The purpose is to enable all available data to be used
for deriving R-L phase and delay differences between IFs.
These differences must be found and removed in order to
average cross-hand data over frequency channels and IFs.

                   USAGE
     BLAVG should be used only after parallel hand fringe
fitting has been completed. It is essential that all the RCP
and LCP fringe fit solutions have been properly referenced to
a single reference antenna using SNSMO (not by FRING; i.e. use
DPARM(7)=1 in FRING). The success of this referencing can be
checked by plotting the R-L difference of the phase solutions
for all antennas using SNPLT, STOKES='DIFF'. The differences
should be zero or constant within a few degrees, depending
whether the constant IF differences were removed before the
fringe fitting or not.
     Running BLAVG on the fringed data produces a new UV file
containing only cross-polarized data on one baseline (average
over the baselines specified by the input adverbs).  Run FRING
on it using the SAME reference antenna, and set DOCALIB and
ANTENNAS to 0. It is also important to set the delay and rate
windows to their default values, and the input averaging
interval DPARM(4) (given in seconds) to match the
pre-averaging interval used by BLAVG. See comment on SOLINT
below. Process the new SN table with POLSN and apply it to the
original CL table (the one used by BLAVG) bu using CLCAL. At
this point the phase and SB delay differences between IF's of
R and L systems should have been removed, which may be checked
by plotting cross-hand data with POSSM.

                   PRINCIPLE OF OPERATION
     BLAVG is based on the fact that after successful parallel
hand fringe fit the cross-hand visibilities on all baselines
show the same phase and delay offsets between the IFs (RL and
LR offsets show opposite signs). Thus averaging over
baselines can be used to reduce noise in the typically weak
cross-hand data. Due to the unknown phase offsets between
baselines (caused by source polarization structure and station
gain errors), the phases must be aligned before averaging
visibilities from different baselines.
     The averaging is done in two steps: first visibility
records on a single baseline are pre-averaged over the period
specified by SOLINT, and then the averaged visibilities from
different baselines are added together. Phasing is only
applied in this second step, and is done by complex
channel-by-channel division as the accumulation progresses.
The IFs and channels used for the phasing can be controlled by
the input adverbs, the default is to use all.  However, the
average itself always uses all IFs and channels.  Finally the
phases of the finished averages are rotated to force the phase
of the reference IF (usually 1) to zero. Note that this method
of averaging will retain ONLY the relative phase and delay
differences between the IFs.
     The BLAVG output will only have two polarizations, RL and
LR, marked as RR and LL, for FRING (see comment for REFANT).

                   COMMENTS
BIF,EIF:
     If data are bad or missing at some IFs and antennas in
the specified time range, these should be avoided using
adverbs BIF and EIF, or ANTEN.

SOLINT:
     Should be set roughly equal to the coherence time since
this gives the best preaverage SNR on a given baseline before
aligning the phases and averaging different baselines. When
running FRING, SOLINT should be set to the anticipated
phase stability time scale of the station electronics. For
example, if the phase differences between IFs (as obtained
from parallel hand fringe fit) show only negligible variation
over the period of observation, one can use a solution interval
covering the whole observation. Coherent use of all the data
is possible because of reference IF phase normalization.

REFANT:
     Use the same reference antenna used for parallel hand
fringe fit. Also, use this reference antenna for the
subsequent cross-hand fringe fit of the output. REFANT
affects numbering of the output baseline and labeling of the
polarizations. If REFANT is the first antenna of the output
baseline RL->LL & LR->RR; if is it the second RL->RR & LR->LL.

     BLAVG works only with TB sorted data for now.

