; VLBIN
;---------------------------------------------------------------
;! Task to read VLBI data from an NRAO/MPI MkII correlator
;# TASK UV VLBI
;-----------------------------------------------------------------------
;;  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
;-----------------------------------------------------------------------
;---------------------------------------------------------------
VLBIN     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
VLBIN: Task which creates uv data from NRAO-DECODE VLBI data.
INFILE
                                   Input VLBI uv file name.
                                   Eg., DBA0:[VLB.S12V]3C120.DAT
IN2FILE
                                   Antennas list file.
OUTNAME                            Output UV file name (name)
                                     blank => NONAME
OUTCLASS                           Output UV file name (class)
                                     blank => UVDATA
OUTSEQ            0.0     999.0    Output file sequence #
OUTDISK           0.0       9.0    Output disk drive #
SOURCES                            Source list
BCHAN             0.0   9999.0     Begin channel (delay or freq)
ECHAN             0.0   9999.0     End channel.If continuum data
                                   use 4 and 10 dly.If line data
                                   use start & stop dly channels
BDROP             0.0    999.0     Drop first BDROP and last
EDROP             0.0    999.0     EDROP freq chans on output.
NPOINTS           1.0              Max # 1000's of visibilities
                                   ** Set misc. parameters **
DOUVCOMP         -1.0        1.0   1 (T) => compressed data
VLBINPRM         -1.0   9999.0     1: =1 machine dly corr
                                   2: =1 trans dly to frq
                                   3: Num. pol. axis pix.
                                   4: Ith pol. axis pix.
                                   5: Reference day
                                      number (first day of
                                      entire VLB run). See
                                      HELP for more.
                                   6: =1 FBS corrections.
                                      =2 only do amp corr
                                   7: =1 Do not recalc
                                      u, v and w.
                                   8: Cal table int(min).
                                   9: =1 Van-Vleck corr.
                                   10: additional b-factor
                                    for line data, 0=>0.64,
                                    anything else => do nothing
                                    (IMPORTANT: see HELP)
                                   11:=1 reject autocorr
                                      data.
                                   12: FQ entry tolerance
                                       (kHz), see HELP.
                                   13: bandwidth (kHz) to
                                       accept, 0 => all.
                                   14: frequency (MHz) to
                                       accept, 0 => all.
                                   15: frequency tolerance
                                    (MHz) i.e. accept freq
                                    PARM(14) +/- PARM(15)/2
                                   16: true sideband of data
                                    (see help), 0 => take
                                    value in DECODE header.
                                   17: from May 1991 the NRAO
                                    MkII correlator stored
                                    autocorrelations in the
                                    wrong order, 0 => correct.
                                    1 => leave alone. See HELP
                                   18: Time between switch
                                    cycles (seconds)
                                   19: number of switch cycles
                                   20: switch cycle to accept
KEYVALUE                           Ref. freq value for cat.
                                   header (Hz). If 0 => 
                                   use value in data.
TIMERANG         -1.0    999.0     Start time (UT) :
                                   (1-4) = day of year,
                                   hours, mins, secs.
                                   Stop time (UT) :
                                   (5-8) = day of year,
                                   hours, mins, secs.

----------------------------------------------------------------
VLBIN
Task: VLBIN reads a VLBI NRAO-DECODE format data set from
a standard VAX/CONVEX disk file. VLBIN creates an AIPS uv
data set. VLBIN will pass frequency channels directly from the
VLB data set or transform delay channels into frequency chans.
VLBIN will not pass delay channels into AIPS.
Adverbs:
  INFILE........Input file name, 48 characters max.
                Eg., DBA0:[VLB.3C120]3C120CAL.DAT under VMS or
                MYVlB:3C120LOCAL.DAT under UNIX
  IN2FILE.......File containing a complete list of the VLB stns
                and sources used in the current experiment.
  OUTNAME.......Output UV file name (name). blank => NONAME
  OUTCLASS......Output UV file name (class). blank => UVDATA
  OUTSEQ........Output UV file name (seq #). 0 => highest unique
  OUTDISK.......Disk drive # of output UV file. 0 => highest
                with space
  SOURCE........Source name. (required)
  BCHAN,ECHAN...If input data set is in frequency channels,
                use BCHAN and ECHAN to define the range of
                channels to pass to AIPS. If input data set
                is in delay lags, use BCHAN and ECHAN to set
                transform window in delay channels. For 12
                delay lag input, use BCHAN=4, ECHAN=10. For 32
                delay lags, use BCHAN=14, ECHAN=20.  VLBIN
                will pass the sideband specified in the VLB
                data headers.If input data is spectral line
                data in delay lags set BCHAN=1 and ECHAN=
                whatever the last channel is ( usually 192 ).
  BDROP,EDROP...Drops the first BDROP and last EDROP frequency
                channels from the AIPS output records. Useful
                when transforming delay lags into frequency and
                dropping off the first and last freq channels.
  NPOINTS.......Maximum # 1000's of input visibilities. 0 => 1
  DOUVCOMP......If true (DOUVCOMP >= 0) the output data is written
                in compressed format which can result in a
                substantial reduction in disk space needed but only
                calibration routines are likely to interprete this
                data.
  VLBINPRM(1)...Set = 1 to calculate and apply machine delay
                correction. Do it.
  VLBINPRM(2)...Set = 1 to transform delay channel data into
                frequency channel data.
  VLBINPRM(3)...Specify the number of pixel elements on the
                polarization axis (1,2,3 or 4).
  VLBINPRM(4)...Current visibilities will be written into the
                VLBINPRM(4)'th pixel element on the polarization
                axis.
  VLBINPRM(5)...Specify a reference day number used to calc.
                the times carried in the vis. records. The
                day numbers in the vis. records are :
                day number of actual rec. time - ref. day num.
                Use the first day in the entire
                experiment, or earlier. Always use the same
                day number each time you run VLBIN for
                different sources in the same experiment.
                This bother allows safe merging of partial
                data sets by DBCON.Defaults to the day number
                in the first scan read in INFILE.
  VLBINPRM(6)...Set = 1 to enable full fractional-bit-shift
                corrections.
                Set = 2 to enable a correction for the amplitude
                loss only.
  VLBINPRM(7)...If > 0 VLBIN passes the u, v and w in the VLB
                data record headers. If <= 0 will recalculate
                u, v and w.
  VLBINPRM(8)...Interval (in minutes) at which to write the
                calibration table entries.
  VLBINPRM(9)...Set = 1 to enable the Van-Vleck clipping corr-
                ection to be done.
  VLBINPRM(10)..Additional b-factor. I am convinced now that
                b stands for bugger. If the Van-Vleck
                correction is all that you have done to your
                data then the cross-power amplitudes need to
                be adjusted by a further factor of 1.28 / 2
                (i.e. VLBINPRM(10) = 0.64). Type
                EXPLAIN VLBIN for mor details. Default:
                0 => 0.64 for line data, anything else =
                no correction
  VLBINPRM(11)..Set = 1 to reject all autocorrelation data.
  VLBINPRM(12)..FQ entry tolerance (kHz) for deciding what
                FQ ID number to assign to a frequency. The
                default (0) is that all data are given the
                same FQ number. If VLBINPRM(11) is negative then
                a new number is assigned to data that differ from
                any previous frequency by an amount greater
                than the frequency  equivalent of 30km/s
                (i.e. the maximum Doppler shift of a source in
                a day). If VLBINPRM(11) > 0 then the value is
                assumed to be the tolerance (in kHz) desired by
                the user.
  VLBINPRM(13)..The bandwidth to accept (kHz). Useful if your
                input file has data with multiple bandwidths.
                0 => all
  VLBINPRM(14)..The frequency to accept (MHz), only valid with
                VLBINPRM(15). 
  VLBINPRM(15)..The frequency tolerance to accept (MHz). VLBIN
                will accept data with freq between VLBINPRM(14)
                +/- VLBINPRM(15)/2.
  VLBINPRM(16)..The true sideband of the data, in some cases,
                e.g. the VLBA, the sideband recorded in the
                DECODE data header is incorrect, this can lead
                to problems inside VLBIN since the FFT will be
                done in the wrong direction. Setting
                VLBINPRM(16) to +1 (for USB) or -1(for LSB) will
                override the value in the DECODE header. 0 =>
                use the value currently there, this is sensible
                for most datasets.
  VLBINPRM(17)  From about May 1991 the NRAO correlator wrote
                the autocorrelation data for station A into the
                station B slot and vice versa. The default value
                of VLBINPRM(17) is to switch these back to the
                correct order. Setting VLBINPRM(17) = 1 will 
                leave the data as they are, that should be the
                value used for data correlated before May 1991.
  VLBINPRM(18)  Users may need to use switch cycles i.e. 
                switching between different video converters.
                VLBINPRM(18) specifies the switch cycle time
                in seconds
  VLBINPRM(19)  Specifies the number of switch cycles
  VLBINPRM(20)  Specifies the switch cycle to accept. 
                Example: If the switch cycle time is 30 seconds,
                and there are 3 cycles (i.e. 3 different video
                recorders), and the user wishes to select cycle
                2 then the parameters to be set are:
                   VLBINPRM(18) = 30
                   VLBINPRM(19) = 3
                   VLBINPRM(20) = 2
  KEYVALUE......The user can specify a reference frequency for
                the catalogue header (Hz). If = 0 use value in
                data.
  TIMERANG(1)-(4).Accept input data later than this start time:
                day of year,hours,minutes,seconds. (UT)
  TIMERANG(5)-(8)..Accept input data earlier than this stop time:
                day of year,hours,minutes,seconds. (UT)
                Default : 00d, 00h, 00m, 00.0s. - start (UT)
                         366d, 00h, 00m, 00.0s. - stop  (UT)
----------------------------------------------------------------
VLBIN : Creates an AIPS uv data set from VLB DECODE file.
DOCUMENTOR : J. M. Benson, NRAO/CV
RELATED TASKS : Most of AIPS.

                        PURPOSE

     VLBIN creates an AIPS uv data set from an external NRAO
DECODE file. VLBIN brings VLB cross-correlation spectra into
AIPS. Also, VLBIN reads delay lag data and transforms them into
frequency data for the global fringe fitting task, VBFIT.

                       COMMENTS

INFILE:
     The complete VMS file name of the input file, eg.,
INFILE='UMA1:[VLB.JMB]DATANAME.DAT'. The input file may be a
DECODE format VMS tape. If running on a UNIX system then the
file name of the input file must be of the form:
INFILE='MYAREA:DATANAME.DAT'; where MYAREA is an environment
variable which points to the area containing the data file
(e.g. setenv MYAREA /scr/vlbi/3c120). The name of the file in
MYAREA must be in upper case.

IN2FILE:
     A separate external file MUST be created by the user (and
text editor) containing the names of ALL stations used in the
current VLB experiment. The station names are entered in quotes
like this :
STATIONS='NRAO','VLA','OVRO','FDVS','MPI','JDRLMKII',
'OSO25','CRIMEA'
When VLBIN starts up, it will list the stations it found in
IN2FILE. A list of sources is also included in IN2FILE. These are
the sources whose data you wish transfered into AIPS. Enter the
source list like this :
SOURCES='3C120','OJ287','NRAO150','3C273'
Enter the delimited character at the end of the file, /.

VISIBILITY PHASE:
     The sign of the visibility phase is flipped as it
is entered into AIPS.

WEIGHTS:
     The AIPS visibility record weights are derived from the
correlator effective integration times. The integration times
are multiplied by a factor of five to keep the weights between 1
and 100.

AUTOCORRELATION DATA
     Autocorrelation data are now passed by VLBIN. Whether they
enter VLBIN as AC functions or spectra, they leave as spectra
with the same number of channels as the visibility data. The
AC weights are set equal to 1.0. If VLBINPRM(10) is set to 1.0 then
autocorrelation data are rejected.

TRANSFORMING, MACHINE DELAY and FBS CORRECTIONS:
     VLBIN will transform DECODE data in delay lags into an AIPS
file in frequency channels. To transform the delay lags, enter
VLBINPRM(2)=1. To correct the visibility phases for a slowly
varying machine delay term, enter VLBINPRM(1)=1. To apply a
correction for the processor fractional-bit-shift error, set
VLBINPRM(6)=1. If VLBINPRM(6)=2 the amplitudes only will be corrected
for the loss caused by the fbs error.

VAN-VLECK CLIPPING CORRECTION.
     If VLBINPRM(9) is set to 1 VLBIN will perform the full Van-
Vleck clipping correction, according to the formula:
     P(t) = sin ( (pi/2) * PC(t) )
where PC(t) is the cross-correlation function of the clipped
signals and P(t) is the true cross-correlation function. This
correction is only done for spectral line data (i.e. #channels
> 32) since it is only necessary when PC(t) is close to unity,
which occurs with some non-thermal maser sources.

OTHER QUANTIZATION CORRECTIONS
    The Van-Vleck clipping correction is applied to both auto
and cross-power data. There are two additional factor to be
applied to cross-power data only. One is a factor of 1.28 to
correct for the effects of the 3-level fringe rotator and the
bit-blanking when the digital fringe-rotator is at zero. The
second is the 'mysterious' factor of two by which the data have
to be divided. We do not know the cause of this factor of 2,
it is however real. Therefore the full correction that should be
applied to cross power data is:

             1.57 * 1.28
             -----------  = 1.005
                 2.0

In other words, the cross-power data does not really need to
be adjusted at all. However in order to avoid confusion we
apply the various corrections explicitly, therefore VLBINPRM(9)
applies the Van-Vleck clipping correction (1.57) to both
auto and cross-power data, VLBINPRM(10) applies the 1.28/2 =
0.64 correction to cross-power data only. The default is to
apply this correction to line data. This is not done to
continuum data because these effects are absorbed into the so-
called b-factor.

POLARIZATION AXIS:
     VLBINPRM(3) specifies the number of pixel elements in the
polarization axis. VLBINPRM(4) is the pixel location that VLBIN
will write the output visibilities. Watch out, VLBIN bloats the
output data set when VLBINPRM(3) is greater than 1. The empty pixel
locations carry visibilities with weight -99.0.

BCHAN, ECHAN, BDROP and EDROP:
      VLBIN will transfer VLBI spectral line data (frequency
channel records) directly into AIPS, or VLBIN will transform
VLBI data (delay lag records) into frequency channels and
write AIPS records. VLBIN will not transfer VLB delay lags
into AIPS records. AIPS currently has no use for delay lag
data. BCHAN and ECHAN set the range of input data channels
(or lags) that will be passed (or transformed and passed) into
AIPS. Thus for spectral line VLBI data which has already been
transformed you might set BCHAN=1 and ECHAN=128 to pass all line
channels, or BCHAN=54 and ECHAN=58 to pass only five frequency
channels. BDROP and EDROP are ignored for spectral line input
data.
      In the case of continuum VLB data, or spectral line data
which has not been transformed BCHAN and ECHAN set the range of
input delay lag channels to be transformed into frequency channels.
The number of resulting frequency channels is one-half the delay
lags transformed + 1 (Mk II VLB is single side band).
Eg., if BCHAN=2 and ECHAN=12, then six frequency channels are
created. Now, you may use BDROP and EDROP to delete frequency
channels from the low and high ends of the bandpass. If BDROP=1
and EDROP=1, channels 2,3,4 and 5 of the original six are copied
into AIPS. BDROP and EDROP should be useful in removing band-edge
distortions before the global fringe fitting process. The most
common transform mode to-date is to use BCHAN=4, ECHAN=10 which
transforms 7 delay lags centered on lag channel # 7 into 4 frequency
channels. For most Mk II spectral line data which is still in the
lag domain, the most common values of BCHAN and ECHAN are 1 and
192 respectively, this will produce a 96 channel spectrum within
AIPS.

U, V, W and VLBINPRM(7)
      There are two options for generating the u, v and w values
carried in the AIPS visibility records.
1) Set VLBINPRM(7) = 1,
VLBIN will copy u, v and w (processor delay * obs. freq) from
the data record headers in the input VLB data set. However, most
of the time u = v = 0.0 in the VLB data records. Then VLBIN will
calculate u and v using the precessed source coordinates and
the source hour angle at Greenwich at the processor station 'A'
wavefront arrival time :
  u =  BX*SIN(SHA) - BY*COS(SHA)
  v = -BX*SIN(DEC)*COS(SHA) - BY*SIN(DEC)*SIN(SHA) + BZ*COS(DEC)
2) The default setting VLBINPRM(7) <= 0 forces VLBIN to recalculate
  u, v and w.

FQ Numbers
FQ numbers are assigned to data whose frequency
characteristics differ from previous data, i.e. bandwidths are
different, a different sideband is recorded, or the frequency
itself differs by an amount greater than the maximum Doppler
shift possible (i.e. a difference greater than that caused by a
velocity change of 30km/s). It is also useful for the user to
have some control over this selection so VLBINPRM(11) allows the
definition of a frequency tolerance.  The default value of this
parameter, i.e. VLBINPRM(11)=0.0 will result in all data having the
same FQ number; if VLBINPRM(11) < 0 then the frequency tolerance
will be the maximum frequency difference due to the Earth's
rotation (i.e. 10**-4 * observing frequency). If VLBINPRM(11) > 0
then the vlaue is taken to be the desired frequency tolerance
in kHz.
An example: if the user had observed the 1665 and 1667 MHz line
of OH and wanted to just separate the two so he/she could process
all of the 1665 MHz data in one pass, then VLBINPRM(11) should be set
to 500.0, i.e. 500kHz, that allows a window of 1.0 MHz, and anything
that lies inside the first frequency found +/- 1 MHz would be
assigned the same FQ number.

FREQUENCY SELECTION
There is an alternative way of selecting frequncies than by
assigning FQ numbers. The user can select a frequency range
and/or bandwidth to accept. If VLBINPRM(13) > 0 then its
value is assumed to be the bandwidth in kHz that you wish to
read, if = 0 then all bandwidths are read and assigned multiple
FQ values.
If the user wishes to select a frequency range say from 1664.0 -
1666.0 MHz to read then he/she should use VLBINPRM(14) and (15).
Set VLBINPRM(14) to be the centre of the frequency range to read
(in MHz), then set VLBINPRM(15) to be 0.5 of the frequency range
to be read. In the above example that would mean setting
VLBINPRM(14)=1665.0, VLBINPRM(15)=1.0

REFERENCE FREQUENCY
Often the user will read a series of files into AIPS and will
wish to concatanate them later. This is made much simpler if
the catalogue reference frequencies are the same, this may not
generally be the case for spectral line experiments. You can
force the reference frequency to be a certain value if
KEYVALUE is not zero. KEYVALUE is a 2 element array, to set the
reference frequency to 22236.91 MHz you would set 
KEYVAL = 22236e6,0.910.0e3.

TIMERANG
      The TIMERANG input parameters are used to select input data
within a time range. Note, the TIMERANG(1) and TIMERANG(5) day numbers
are days of the year numbers. The VLBI data records keep the
day specification in days of the year number. The AIPS file
created by VLBIN, on the other hand, keeps day specifications
in each AIPS data record in terms of a relative day number.
The AIPS relative day numbers are with respect to the reference
date carried in the AIPS catalog header. The reference day
number is usually the first day in the observation, so the AIPS
day numbers in the data records are 0, 1, 2, so forth.

ANTENNA TABLES FILE:
      The header of the AN tables file contains information
concerning the array coordinates, the source coordinates and the
UT1, UTC and IAT times used. The GST, RA and DEC are given with
respect to UT = 0 hr on the reference day indicated in the AN
header.  In fact, the GST, RA and DEC are copied from the first
VLBI scan header record encountered by VLBIN. Warning: the RA
and DEC were actually precessed to UT = 12 hr on the reference
date (in the VLB prep-tape program).

EXECUTION TIME:
     The cpu time required for execution of VLBIN may be
estimated from the following formula :

     CPU (seconds) = N-total * 2E-03  +  N-aips * 13.3E-03,

where N-total is the total number of visibility records in the
INFILE (input) data set. N-total includes the visibility records
from all sources in the INFILE data set. N-aips is the number of
visibility records that VLBIN will create in AIPS (you could use
NPOINTS).

OUTPUT FILE SIZE:
     The size of the AIPS uv file created by VLBIN may be
estimated :

 Number of VAX blocks =
     NRECS * ( N-ran * 4 + N-cmplx * N-freq * N-pol * 4 ) / 512,

where NRECS is the number of visibility records in the uv file,
where N-ran is the number of random parameters per uv record
(usually 5), N-cmplx is the number of words per visibility
(usually 3), N-freq is the number of frequency channels (usually
4 or 6) and N-pol is the number of polarizations in the uv file
(usually 1).
