%-----------------------------------------------------------------------
%;  Copyright (C) 1995-2025
%;  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
%-----------------------------------------------------------------------
\chapts{Reducing VLBI Data in \AIPS}{vlbi}

\renewcommand{\titlea}{31-December-2025 (revised 25-November-2025)}
\renewcommand{\Rheading}{\AIPS\ \cookbook:~\titlea\hfill}
\renewcommand{\Lheading}{\hfill \AIPS\ \cookbook:~\titlea}
\markboth{\Lheading}{\Rheading}

% what about gain curves that do/do not include OPACITY!!!
% give additional resources for finding cal files for VLA, VSOP, and EVN!!!
% improve discussions of SNSMO, SHOUV!!!
% improve explanations in polarization section!!!
% add plots to polarization sections!!!
% discuss merits of averaging RR and LL for determining solutions !!!
% reference a paper that uses a polarization calibrator !!!
% add phase referencing to recipe structure !!!

% other VLBI resources
This chapter describes the reduction of \Indx{VLBI} data in \AIPS\ .
A Step-by-step recipe, covering both simple and more difficult
situations, is presented.  See \Rappen{VLBAeasy} for simpler and
shorter recipes suitable for straightforward observations.  Procedures
to simplify some of the VLBI reduction steps are mentioned and become
available to you after you enter the command {\us RUN VLBAUTIL \CR}\@.
There is also a VLBA pipeline, {\tt VLBARUN}, which is useful for
simple datasets, see \Sec{vlbarun}.  If you have very old VLBI data,
in Mk III or Mk IV format, see \Sec{oldvlb}.  We also include here
some background information concerning the structure of VLBI data
sets, the data  reduction philosophy and a description of some of the
effects for which corrections must be determined and applied.  It is
important to understand these aspects if you wish to reduce your data
reliably.  For more background information on VLBI data reduction
consult {\it VLBI and the VLBA\/}, Astronomical Society of the Pacific
(ASP) Conference Series No. 82, 1995.

% other AIPS resources
Programs of particular interest for VLBI may be found in \Rchap{list}
or displayed from inside \AIPS\ by typing {\us ABOUT\qs VLBI\CR} or
{\us APROPOS\qs VLBI \CR}\@.  Remember, the best and most complete
information available on all \AIPS\ verbs and tasks may be found in
their {\tt EXPLAIN} files.  A {\tt 15APR97} or later version of \AIPS\
is required to support full Space VLBI data reduction.

% content note
Most types of VLBI data, once read into \AIPS, appear very similar in
structure as far as the user is concerned.  We shall concentrate on
describing the reduction path for data produced by the \Indx{VLBA}
correlator, but most operations also apply to MkII, MkIII, and MkIV
data.  See \Sec{oldvlb} where we draw the reader's attention to any
differences.  The few extra steps necessary for calibrating
phase-referencing observations are described in \Sec{phaseref}.
Note that successful phase-referencing observations require careful
planning {\bf before} the observations.  See VLBA Scientific Memo
No.~24 by J. Wrobel, C. Walker, J. Benson, and A. Beasley.

% reading in external files
Some of the VLBI-related tasks require the ability to read files
resident outside \AIPS\ .  To communicate to \AIPS\ the directory in
which these files exist it is necessary to define a logical pointer or
environment variable.  Please refer to \Sec{externfile} to see how
this is done.

While the majority of VLBI observations are continuum observations,
more sophisticated data reduction techniques are increasingly common.
Continuum VLBI observers sometimes also apply spectral-line VLBI
techniques to improve the dynamic range of their data sets.  For these
reasons, this chapter is organized to make the discussion of data
reduction techniques more uniform.  The overview in this section of
the steps involved for several type of VLBI data reduction is meant to
guide the user through the rest of the chapter.  It is strongly
recommended that you read the overview carefully before proceeding.

The expected size of the output \uv\ data file can be an important
consideration in VLBI data reduction. The \indx{disk space} required
by \AIPS\ for a compressed dataset is given by the relation:
$${\rm Disk\ Space} = 4\ {\rm x}\ 10^{-6}\ N_{Stokes}\ N_{chan}\
N_{IF}\ {{N_{ant}\over2}(N_{ant}+1)}\ {{T_{expt}}\over{\triangle
T}}\ {\rm MBytes}$$
where $T_{expt}$ is the total observing time, $\triangle T$ the
correlator integration time, $N_{Stokes}$ the number of polarization
correlation pairs $(RR,LL,RL,LR)$, $N_{chan}$ the number of spectral
channels per IF, $N_{IF}$ the number of IF's, and $N_{ant}$ the number
of antennas in the network.  Space VLBI (SVLBI) data can have
different integration times for the ground and space baselines of
$\triangle T_g$ and  $\triangle T_s$, respectively, and therefore the
total \indx{disk space} requirement is larger.  If $N_{ant}$ is the
number of ground telescopes,
 $${\rm Disk\ Space} = 4\ {\rm x}\ 10^{-6}\ N_{Stokes}\ N_{chan}\ N_{if}\
 \left[{1\over2}N_{ant}(N_{ant} - 1){T_{expt}\over \triangle T_g} +
 N_{ant}{T_{expt}\over\triangle T_s}\right]\ {\rm MBytes}$$
In uncompressed format the same data set will require two-three times
the disk space.  Be forewarned that some tasks
attempt to create uncompressed scratch files which may not fit into
the available disk space.  The amount of available free disk space can
be determined using the {\tt AIPS} command {\tt FREE}\@.  The blocks
referred to in the {\tt FREE} output are equal to 1024 bytes.

Note that certain operating systems are still subject to a
\indx{2-Gigabyte limit} for any individual file, as a result of their
32-bit file systems. Larger \AIPS\ files are supported on DEC Alpha,
SGI (running XFS), HP, Solaris (revision $\ge 2.6$), and Linux (kernel
$\ge 2.4.2$).  The last three require all \AIPS' C code to be compiled
with an additional option.  The size of the output file can be reduced
by IF selection or limited concatenation in {\tt FITLD} or by time- or
spectral-averaging later using {\tt UVAVG}, {\tt SPLAT} or {\tt
AVSPC}\@.

It is possible to construct data sets on disk that cannot be written
to a single tape using {\tt FITTP} because {\tt FITTP} uncompresses
the data when writing to tape.  The task {\tt FITAB} is designed to
address this problem.  {\tt FITAB} writes data in compressed form to
tape and can write data in pieces to multiple tapes.  Note that {\tt
FITAB} is only available in {\tt 15APR99} and later releases and that
versions of {\tt FITLD} from earlier releases cannot read such data.
Packages other than \AIPS\ may also be unable to understand these
files.

One large point of divergence in the reduction of continuum
\indx{polarization} \Indx{VLBI} data is the question of whether or not
to determine separate LL and RR phase solutions.  The
polarization-specific portions of the recipe given below are based
upon the premise that L and R phase solutions should always be
determined separately on the grounds that it is safer and should work
with data from a wide variety of antennas.  If the L-R phase offsets
for antennas in your data set are small and constant in time, you may
consider modifying the recipe in \Sec{vlbrecipe} by determining
averaged LL,RR phase solutions everywhere except in step 7.

\Sects{VLBI data calibration recipe}{vlbrecipe}

See \Rappen{VLBAeasy} for simpler and shorter recipes suitable for
straightforward observations.

\xbit
\ITEM{1.}{LOAD THE DATA}
For data from the \Indx{VLBA} correlator, run {\tt \tndx{FITLD}}
(\Sec{fitld}); if needed, follow up with {\tt MSORT}, {\tt USUBA},
{\tt INDXR}, {\tt VBGLU}, {\tt VBMRG}, and {\tt MERGECAL}
(\Sec{vlbsort}--\Sec{vlbDBCON}).  For data from a MkIII correlator,
see \Sec{oldvlb}.  Data from the Penticton correlator should be loaded
using {\tt FITLD}, sorted ({\tt MSORT}, \Sec{vlbsort}), and indexed
({\tt INDXR}, \Sec{vlbINDXR}).

\ITEMs{POLARIZATION:}
The combination of the VLBA correlator and {\tt FITLD} incorrectly
labels polarizations for dual parallel-hand correlation (RR and LL
only), even if RR and LL are in different frequency bands (\eg\ LL at
5 GHz and RR at 8.4 GHz).  For these types of data, you must run {\tt
FXPOL} (\Sec{fxpol}).

\ITEM{2.}{EXAMINE THE DATA}
It is important to familiarize yourself with the data set before
proceeding further, especially if you have little experience with VLBI
data. There are many \AIPS\ tasks for the examination of your data
(see \Sec{vlbexam} for a fuller discussion).  Minimally, you should at
first run {\tt LISTR}, {\tt IMHEAD}, {\tt EDITR}, {\tt POSSM}, {\tt
VPLOT}, and {\tt PRTAN}\@.  At later stages you will probably find
{\tt SNPLT}, {\tt PRTAB}, {\tt DTSUM}, and {\tt SHOUV} useful for
examining data and calibration tables.

\ITEMs{SVLBI:}
\iodx{SVLBI}
Task {\tt OBPLT} allows you to examine different aspects of the
spacecraft orbit.

\ITEM{3.}{PROCESS THE CALIBRATION FILES}
You will have either received calibration files, or instructions on
where to obtain them.  Some calibration files can be automatically
processed into a form suitable for use within \AIPS\ using {\tt VLOG}
(\Sec{vlblogs}).  {\tt {\tndx{ANTAB}}} is now the primary \AIPS\ task
for loading calibration information from log files.

\ITEMs{VLBA CORRELATOR:}
The VLBA correlator will usually attach
calibration information directly to your data for all VLBA and some
other antennas.  This obviates the need to run {\tt VLOG}, {\tt
ANTAB}, {\tt PCLOD}, and {\tt UVFLG} to process your {\it a priori\/}
calibration information for VLBA antennas.  Some information for
non-VLBA antennas must usually still be loaded from text files.

\ITEMs{POLARIZATION:}
Be careful to make sure that the polarization labeling of the IFs in
the calibration text files is the same as the labeling in the data.

\ITEM{4.}{CORRECT FOR THE IONOSPHERE}
For low frequency experiments ($< 3$GHz), {\tt \tndx{TECOR}} should be
run to remove at least part of the ionospheric contribution to the phase
offsets.  This should also be considered for higher frequencies
(\eg\ 8~GHz) for abnormal ionospheric conditions.

\ITEM{5.}{CORRECT FOR THE EARTH ORIENTATION PARAMETERS}
For phase referencing experiments correlated at the VLBA correlator,
particularly between 5-May-2003 and 2-August-2005, {\tt
\tndx{CLCOR}} (OPCODE='EOPS') should be run.  This will correct the
possibly inaccurate Earth Orientation Parameters used by the VLBA
correlator.  This is particularly important for astrometry experiments
but can effect any phase referencing experiment including those
correlated outside the above range of dates.

\ITEM{6.}{EDIT THE DATA}
Identifying and \indx{editing} bad data now can save you time later.
Data should first be edited using {\tt UVFLG} to apply editing
information supplied with your calibration files (\Sec{vlbedit}).
Some useful tasks for examining and editing data are {\tt EDITR}, {\tt
UVFLG}, {\tt TVFLG}, {\tt SPFLG}, {\tt EDITA}, {\tt BPEDT}, {\tt
FLAGR}, {\tt FINDR}, {\tt VPLOT}, and {\tt QUACK}\@.

\ITEMs{POLARIZATION:}
You may want to edit the data consistently in all polarizations
(select {\tt STOKES = 'IQUV'} within {\tt EDITR}, {\tt TVFLG} or {\tt
SPFLG}) --- this can greatly simplify the imaging stage (see step 15).

\ITEM{7.}{POLARIZATION: ADD PARALLACTIC ANGLE CORRECTION}
For alt-az mounted antennas, a parallactic angle correction for the
rotating orientation of the antenna feeds with respect to the observed
source must be performed as the first step in the phase
\indx{calibration} using {\tt CLCOR} (\Sec{vlbCLCOR}).
This step should be performed no later than immediately after the
\Tsys\ calibration.

\ITEMs{PHASE REFERENCING:}
You {\it will} want to perform the parallactic angle correction
described above for phase referencing observations even if you only
correlated the parallel hands ({\tt RR}, {\tt LL}).

\ITEM{8.}{APPLY SAMPLER CORRECTION}
{\bf We now advocate a new amplitude calibration strategy based on VLBA Scientific
Memo \#37 (Walker 2015).  This strategy interleaves the classic {\it a priori}
calibration with instrumental delay and bandpass calibration to improve
the calibration of data from the new Roach Digital Backend (RDBE) on the VLBA
(see VLBA Observational Status
Summary for a description of the RDBE and VLBA Scientific Memo \#37 for a
discussion of  amplitude problems when using the RDBE).}  With data from before
the RDBE you can use either the old or new strategy.
First corrections for sampler biases should be applied using {\tt ACCOR}
(\Sec{accor}) for data from the VLBA and some other correlators.
Some correlators apply this correction to the data before writing them
out --- notably the EVN JIVE correlator and correlators used for the
Australian LBA.  The VLBA hardware and software (DiFX) correlators do
{\it not} apply this correction to the data.  Therefore, {\tt ACCOR}
is required for the VLBA correlators and any others that do not apply
the correction.  {\tt ACCOR} should be benign (do nothing) for those
correlators that do apply the correction prior to reading the data
into \AIPS\@.  Note that you can always run {\tt ACCOR} and look at
the {\tt SN} table produced with {\tt PRTAB} or {\tt SNPLT} to see if
it was benign or not.

\ITEM{9.}{CALIBRATE THE INSTRUMENTAL DELAYS}
{\it Phase-cal\/}s, or measured single-band and multi-band
instrumental phase errors, should be applied using {\tt PCCOR}
(\Sec{pccor}).  You can manually perform a phase-cal by running {\tt
\tndx{FRING}} on a limited subset of your data to account for missing
phase-cal information or to refine the reported phase-cal measurements
(\Sec{PCCORhand}).\Iodx{VLBI}

\ITEMs{SPECTRAL-LINE:}
Delay calibration should be carried out only on the continuum sources
at this stage.  Since there should be no pulse-cals, the ``manual''
phase-cal method should be used.

\ITEMs{POLARIZATION:}
If running {\tt FRING} to determine the instrumental delays, be certain
to solve for independent left- and right-polarization delay solutions
{\tt APARM(3) = 0}.  Run {\tt RLDLY} after calibrating the instrumental
delays, to determine a single delay offset between left and right
\indx{polarization} (\Sec{vlbPCAL}).

\ITEM{10.}{CALIBRATE THE COMPLEX BANDPASS RESPONSE FUNCTION}
Run {\tt BPASS} or {\tt CPASS} to determine the \indx{bandpass}
response function using the {\it cross-power} spectra (\Sec{vlbBPcal}).
The normalization should be over the full bandwidth, be careful because
the default channel selection is the inner 75\% of the band.  If you
use the inner 75\%, it can lead to amplitude errors of up to 15\%.

\ITEMs{SPECTRAL-LINE:} The bandpass response function should be
determined using only the continuum calibrator sources.  \iodx{spectral-line}

\ITEM{11.}{APPLY ONE MORE AUTOCORRELATION CORRECTION AND THEN FINISH
{\it A PRIORI} CALIBRATION}
After determining the bandpass calibration  the autocorrelations are
probably different from unity by a few percent.  To correct this run
the task {\tt ACSCL}, applying the previous calibration and bandpass
correction.  Then finally use {\tt {APCAL}} to complete the {\it a
priori\/} amplitude \indx{calibration} (\Sec{vlbcamp}) --- this is
called the \Tsys\ method of amplitude calibration.  {\tt APCAL} can
also be used to perform opacity corrections.\Iodx{VLBI}

\ITEMs{SPECTRAL-LINE:}
Unless the line emission is very weak, you may wish to defer amplitude
calibration of your {\it line sources only\/} until step 16 below.  The
template method described there is much more accurate than the
\Tsys\ method.

\ITEM{12.}{FRINGE FIT THE DATA}
Estimate and remove residual delays, rates and phases using {\tt
FRING} or {\tt \tndx{BLING}}  and {\tt CLCAL}
(\Sec{fring}--\Sec{bling}).

\ITEMs{SPECTRAL-LINE:}
Only fringe-fit the calibrator source at this stage.  Check the
coherence of the target source using the resulting solutions to decide
whether or not to zero the rate solutions using the {\tt 'ZRAT'}
option in {\tt SNCOR} (\Sec{lineFRING}).  It is probably better to
force the rates to be zero in {\tt FRING} rather than zeroing them
after the fitting.

\ITEMs{PHASE REFERENCING:}
You should {\bf not} fringe-fit on the {\it target\/}, or
phase-referenced source.  Rather, you should fringe-fit on the {\it
cal\/}, or phase-reference calibrator.  When you apply the solution,
be sure to set the {\tt CALSOUR} and {\tt SOURCES} adverbs in {\tt
CLCAL} appropriately to interpolate the solutions for the cal source
onto the target source (see \Sec{vlbpref}).  If you are not interested
in astrometric calibration and your target source is strong enough,
you may wish to consider fringe-fitting on it to further refine the
phase calibration (\Sec{phaseref}).

\ITEM{13.}{POLARIZATION: ESTIMATE THE INSTRUMENTAL POLARIZATION}.
Correct for the instrumental polarization terms, commonly known as
`D-terms' using {\tt PCAL} or {\tt LPCAL} on the polarization calibrator
(\Sec{vlbDterm}).  This polarization calibrator should first be fully
calibrated and imaged before this step can be performed.

\ITEM{14.}{POLARIZATION: CALIBRATE THE POLARIZATION POSITION ANGLE}
If a calibration source with known polarization orientation is
available, use {\tt CLCOR} to make a final correction to adjust the
polarization angles of the target source data (\Sec{vlbPCAL}).

\ITEMs{SPECTRAL-LINE or POLARIZATION:}
The bandpass response function should be determined using only the
calibrator source.  Unlike step 7, this step cannot be skipped.

\ITEM{15.}{APPLY THE DOPPLER CORRECTION} (\indx{spectral-line}
data only).
Run {\tt CVEL} to compensate for the changing Doppler shifts of the
antennas with respect to the source during the observation and between
the different observations (\Sec{cvel}).\Iodx{VLBA}\Iodx{VLBI}

\ITEM{16.}{SPECTRAL-LINE: REFINE THE AMPLITUDE CALIBRATION}
Run {\tt ACFIT} to amplitude calibrate the program source using the
template spectra method (\Sec{acfit}).  Note that the traditional
\Tsys\ method (\Sec{vlbcamp}) can also be used if the line
emission is too weak for the template method to work successfully.

\ITEM{17.}{SPECTRAL-LINE:DETERMINE RESIDUAL RATES}
Now estimate the residual rates ONLY by running {\tt FRING} or {\tt
BLING} on one or a few spectral points on the target source
(\Sec{lineFRING}).

\ITEM{18.}{APPLY CALIBRATION, AVERAGE, AND INSPECT THE FINAL DATA}
Run {\tt SPLIT} or {\tt SPLAT} to apply the calibration solutions
and to average the data in frequency if appropriate (\Sec{vlbSPLIT}),
and {\tt UVAVG} to average the data in time (\Sec{vlbUVAVG}).  You can
also run {\tt SPLAT} to combine these three operations into a single
step.  It is recommended that you take the time to inspect the
calibrated data to see if more editing is needed, and to check that no
gross calibration errors remain in the data (\Sec{vlbverify}).

\ITEM{19.}{SELF-CALIBRATE/IMAGE OR SELF-CALIBRATE/MODEL-FIT THE
DATA}
The final complex gain corrections are determined by iterating
self-calibration with imaging of the resultant data set.  This is
called hybrid-mapping.  Alternatively, self-calibration can be
iterated while fitting models directly to the data --- the goal is to
self-calibrate using the best model possible.  The options are
outlined in \Sec{vlbimag}.

\ITEMs{SPECTRAL-LINE:}
One final distinction remains between continuum and spectral-line
data.  Only one or a few spectral points are used to determine final
complex gain corrections which are then applied to all spectral points
in the line data.  After applying these gains, the line source data
can be imaged to form an image cube.

\ITEMs{POLARIZATION:}
While the Stokes I and Stokes V images formed using the {\tt RR} and
{\tt LL} visibilities will be real-valued, the Stokes Q and Stokes U
images formed using {\tt LR} and {\tt RL} visibilities can, in
principle, be complex-valued.  You must use a fully complex imaging
and deconvolution technique (see the {\tt HELP} files for {\tt CXPOL},
{\tt CXCLN}, and {\tt CXIMAGR}) or you can simply edit the {\tt LR} and
{\tt RL} visibilities to enforce the condition that whenever you have a
{\tt RL} visibility on a baseline, you also have the {\tt LR} visibility
on the same baseline; this ensures that the Stokes Q and U images are
real-valued and allows you to use the standard imaging tasks.
\iodx{calibration}
\xeit

\Sects{Pipeline for the VLBA}{vlbarun}

{\tt \Tndx{VLBAPIPE}} and {\tt \Tndx{VLBARUN}} are two similar pipeline
procedures which use the VLBA calibration procedures (from
{\tt \indx{VLBAUTIL}}) and some logic to calibrate and image VLBA data.
They both attempt to make intelligent decisions on defaults, so they can
be run fairly automatically, if the names of the sources are known.
{\tt VLBAPIPE} and {\tt VLBARUN} have been given options to flag data on
elevation, to flag excessive fluxes with {\tt CLIP}, and to apply
auto-flagging with {\tt RFLAG}\@.  The option to clip out bad system
temperatures, replacing them with good ones, with {\tt TYSMO} was also
added.  The two pipelines differ primarily in the order in which they
carry out their operations.  Most importantly, {\tt VLBAPIPE} runs {\tt
FRING} on all calibration scans before computing the bandpass.  If the
primary calibrator was onserved with multiple scans, this order should
help to make the scans phase coherent.  If desired, {\tt VLBAPIPE} and
{\tt VLBARUN} will produce diagnostic plot  files and write them to disk
creating an HTML file to ease examination of these files.  Images will
be produced, optionally including self-calibration of the calibration
sources.  Since only one self-cal, phase only iteration is run, the
images should be considered diagnostic in nature.

The two piplines use essentially the same input adverbs, except for the
meaning of the {\tt DOFLAG} parameter.  Sample inputs for procedure
{\tt \Tndx{VLBAPIPE}} are:
\dispt{RUN \tndx{VLBAUTIL} \CR}{to acquire the procedures used by {\tt
           VLBAPIPE}.}
\dispt{RUN \tndx{VLBAPIPE} \CR}{to acquire {\tt VLBAPIPE}.}
\dispt{DATAIN\qs{\it /dirname/data.fits} \CR}{to set data file to load
            from disk.}
\dispt{OUTDISK\qs{\it n\/} \CR}{to set disk for output.}
\dispt{OPTYPE\qs 'CONT' \CR}{to say this is a continuum data set.}
\dispt{CLINT\qs 0 \CR}{to use default.}
\dispt{CHREFANT\qs 'FD' \CR}{to set reference antenna to Fort Davis.}
\dispt{TIMERANG\qs 0 \CR}{to have VLBARUN determine a good instrumental
           delay calibration scan.}
\dispt{INVER\qs 0 \CR}{{\tt PC} table to use, -1 if you want to force
           manual phase cal.}
\displ{CALSOUR\qs 'CAL-BAND', 'CAL-PHASE', 'CAL-AMP' \CR}{to
           list calibrators, bandpass calibrator {\it must} be first.}
\displ{SOURCES\qs 'CAL-PHASE', 'TARGET', $\ldots$ \CR}{to
           list phase referencing and target pairs.}
\dispt{CHINC\qs -1 \CR}{to determine channel increment based on the
           data channel width.}
\dispt{INFILE\qs '' \CR}{set if you want to apply a zenith delay file
           produced by {\tt \Tndx{DELZN}}.}
\dispt{SOLINT\qs 0 \CR}{to use default.}
\dispt{IMSIZE\qs 512 \CR}{to make images and specify size of target
           images.}
\dispt{FACTOR\qs 0 \CR}{to make calibrator images 128x128.}
\dispt{DOCLIP\qs $fp , fc$ \CR}{to run {\tt CLIP} to flag a sample
           when the parallel-hand flux is above $|fp|$ or the cross-hand
           flux is above $|fc|$.  If $fp$ is positive, the clip is
           done after amplitude calibration; if negative, it is done
           before the bandpass and amplitude calibration.  The
           values for $fp$ and $fc$ are different in these two cases.}
\dispt{DOFLAG\qs 1 \CR}{to run {\tt RFLAG} on each source
           individually.}
\dispt{TYSMOLEV\qs 100\CR}{to clip system temperatures above 100 K with
           median-window filtering at 10 K and replacing the clipped
           values with nearby good ones.}
\dispt{ELEVLIM\qs 15 \CR}{to flag out all data for which the elevation
           is $< 15$ degrees.}
\dispt{GET2N\qs {\it ctn2\/} ; NMAPS=1 \CR}{to use a model for the
           bandpass calibration.}
\dispt{SELFCAL\qs 1 \CR}{to do one pass of self-cal, phase only on each
           calibrator prior to the final {\tt SPLIT}\@>}
\dispt{BPASS5\qs -2 \CR}{to normalize bandpass scans before the fit.
           Default is +1 to normalize the bandpass functions themselves
           without normalization of the data.}
\dispt{BPSOLINT\qs 0 \CR}{to make a solution for each calibration scan.
           {\tt BPSOLINT=-1} averages all calibration scans.}
\dispt{DOBAND\qs 3 \CR}{to interpolate the bandpass over time.  {\tt
           DOBAND=1} (the default) averages all bandpass records.}
\dispt{CALTASK\qs 'CALIBS' \CR}{to use {\tt FRING} for the initial time
           series calibration but use {\tt CALIB} for any self-cal.
           Other choices are {\tt 'CALIB'} and {\tt 'FRING'} (the
           default) to use the specified task for all time series
           calibrations.}
\dispt{DOPLOT\qs 1 \CR}{to make some diagnostic plots; level 2 makes an
           awful lot of plots.}
\dispt{OUTFILE\qs '{\it /directory/name} \CR}{to specify directory for
           output plots.  If this is set, plots are written out from
           \AIPS\ and organized in an HTML file for easy viewing.
           The plots, HTML file, and message file contents are put in
           a dated subdirectory below the specified directory.}
\dispt{OUTTEXT\qs '{\it email@somewhere.edu} \CR}{to specify an e-mail
           address if the user wants to be notified when the pipeline
           is done.}
\dispt{BADDISK 0 \CR}{to specify which disks to avoid for scratch.}
\dispt{VLBAPIPE \CR}{to run the procedure.}
\dispe{{\tt VLBAPIPE} or {\tt VLBARUN} will then run and produce the
requested number of diagnostic plots.  For details on the plots produced
for each level of {\tt DOPLOT}, see {\tt EXPLAIN VLBAPIPE}.  If an
e-mail address is specified then a {\tt VLBAPIPE DONE} or {\tt VLBAPIPE
FAILED} message will be sent.  However, the {\tt VLBAPIPE FAILED}
message will only be sent if the pipeline failed because of problems
with the inputs, if it failed because a task it was running failed this
message is not sent.  It is highly recommended that the user read the
explain file for {\tt VLBAPIPE} before use.}

The only adverb that differs between the two pipeline scripts is {\tt
DOFLAG}\@.  In {\tt VLBAPIPE}, the pipeline will shut down after running
{\tt RFLAG} if $0 < {\tt DOFLAG} < 10$ to allow you to rerun the
pipeline using the {\tt RFLAG} flag tables.  Presumably, the calibration
in the second pass should be better.  If {\tt DOFLAG} $\ge 10$ in {\tt
VLBAPIPE} or {\tt DOFLAG}$ > 0$ in {\tt VLBARUN} the pipeline invokes
{\tt RFLAG} and then continues to the optional self-cal step followed by
{\tt SPLIT} and {\tt IMAGR}\@.  {\tt VLBARUN} uses the value of {\tt
DOFLAG} as an initial clip level in {\tt RFLAG} but only if it is
greater than 100.  {\tt VLBAPIPE} does not use the initial clip option
in {\tt RFLAG}, leaving that to the {\tt DOCLIP} adverb.

Note that editing with {\tt CLIP} is always a good idea.  {\tt RFLAG}
appears to work well at low frequencies but to be overly enthusiastic
at C-band and above.  Note that the flagging is done after all
calibration steps, so you may examine your data with and without the
new flags to determine their correctness.  {\tt RFLAG} is run using
baseline-dependent clip levels and so should work with arrays
containing high-sensitivity telescopes as well as the VLBA\@.  You may
wish to use {\tt VLBAPIPE} without {\tt RFLAG} (or to discard the flags
produced by {\tt RFLAG}) and then run {\tt SPFLG} to flag the
visibility data interactively.  Then use {\tt \Tndx{VLBAPIPE}} over
again applying the manually produced flags.  Procedure {\tt
R\_RESTART} ({\tt P\_RESTART} in {\tt VLBARUN}) will clear away all plot
and calibration tables from your data set, leaving any flag tables.  Do
not delete version one of the {\tt CL} and {\tt FG} tables since they
contain the initial calibration and on-line flagging information.

A similar {\tt RUN} file named {\tt \Tndx{VLBAMPHC}} is available
to calibrate, flag, and image data sets for secondary phase stopping
centers when DiFX has been used to correlate multiple centers from a
single pointing.

In {\tt 31DEC21}, a similar pipeline was constructed to inspect
autocorrelation data for RFI.  {\tt \Tndx{VLBARFI}} reduces the data set
using many of the steps of {\tt VLBARUN}\@.  After the amplitude
calibration, the pipeline writes out the autocorrelation data with {\tt
SPLAT} and then runs {\tt \tndx{VBRFI}} to analyze the statistics of the
autocorrelations and to write then into a text file and optionally to
plot them.  Task {\tt \tndx{PLRFI}} may be used later to plot one or more
of these output text files.  In {\tt 31DEC22}, {\tt VLBARFI} may be run
with no calibration and statistics determined with medians using {\tt
\Tndx{VLBRF}} rather than {\tt VBRFI}\@.

\Sects{Loading, fixing and inspecting data}{loadingvlbidata}

In theory, \AIPS\ can process data from multiple frequency bands ({\tt
FQ} numbers in \AIPS\ parlance) coexisting within the same data set.
However, it is recommended that the data be separated into different
frequency bands as soon as possible after loading the data and process
each {\tt FQ} number separately.  If you wish to do this, you should
do it immediately after performing the relevant steps in
\Sec{loadingvlbidata}.  The {\tt VLBAUTIL} procedures {\tt VLBAFQS} and
{\tt VLBAFIX} do this automatically ({\tt VLBAFIX} is recommended and
does other ``fixing'' tasks like fixing subarrays etc.).  If you
want to do this by hand use the task {\tt UVCOP}\@.
%\vfill\eject

\subsections{Loading data from the VLBA correlator}

\Subsubsections{Running {\tt FITLD}}{fitld}
\Todx{FITLD}\Iodx{VLBI}

The information below applies to data from the VLBA Correlator in what
the VLBA archive calls ``raw'' format, more formally known as FITS-IDI
format.  The archive now also contains data called ``calibrated''
which have been run through a few of the simplest VLBA procedures but
which are nowhere near calibrated.  These files are recommended under
normal circumstances.  They may also be loaded with {\tt FITLD}, but
the {\tt DOCONCAT} option does not work with the FITS table format
used in the archive.

Data generated by the \Indx{VLBA} correlator are loaded from DAT (or
Exabyte) tape (or from disk files) into \AIPS\ using {\tt FITLD}\@.
First, physically load your tape and {\tt \tndx{MOUNT}} it
(\Sec{magtape}), then run {\tt FITLD}\@.  Often the data on your tape
will be divided into a number of separate files (corresponding to
separate ``correlator jobs'').  In this case, run {\tt FITLD} with
{\tt NCOUNT} set equal to the number of files on the tape (or a
suitably large number), as listed on the paper index which comes with
the tape.  The adverb {\tt ANTNAME} allows the user to control the
antenna numbering if desired.  Also set {\us DOCONCAT = 1 \CR} to
ensure that all tape files with the same structure are concatenated
into a single \AIPS\ file.  Note that standard tape handling tasks
(\eg\ {\tt PRTTP} and {\tt TPHEAD}) can be used to inspect the tape
contents.

Note that antennas, sources, frequency IDs, and other things may be
numbered differently in different correlator jobs.  {\tt FITLD} fixes
all this for you, but only if you set {\tt DOCONCAT = 1} and, better
still, load as many files as possible in each execution of {\tt
FITLD}\@.  {\tt FITLD} can load VLBA correlator data from multiple disk
files so long as they have the same name plus a consecutive
post-pended number beginning with 1.  If you forget to put all the
related data together with {\tt FITLD} you can use {\tt \tndx{MATCH}}
to align the antenna numbers followed by {\tt DBCON} later.

Typical inputs to {\tt FITLD} would be:\Iodx{VLBI}
\dispt{TASK\qs 'FITLD' ; INP \CR}{to review the inputs.}
\dispt{INTAPE {\it n\/}\CR}{to specify the input tape number.}
\dispt{NFILES\qs 0 \CR}{to skip no files on tape.}
\dispt{DATAIN\qs ' ' \CR}{to load from tape, not from disk.}
\dispt{OUTNAME\qs 'TEST' ; OUTCL\qs 'FITLD '\CR}{to specify the name
           of the output file.}
\dispt{OUTSEQ \qs 0; OUTDI \qs 1 \CR}{to specify the sequence number
           and disk of the output.}
\dispt{OPTY ' ' \CR}{to load any type of file found.}
\dispt{NCOUNT\qs 20 \CR }{to load 20 tape files.}
\dispt{DOUVCOMP\qs 1 \CR}{to save disk space by writing compressed
           data.}
\dispt{DOCONCAT\qs 1 \CR}{to concatenate files with same data
           structure into one disk file.}
\dispt{CLINT\qs $\triangle t$ \CR}{set CL table interval to $\triangle t$
           minutes (see discussion below).}
\dispt{DIGICOR\qs 1 \CR}{to request digital corrections (usually VLBA
           correlator only).}
\dispt{DELCORR\qs 1 \CR}{to request delay decorrelation corrections
           (VLBA correlator only).}
\dispt{WTTHRESH\qs 0.65 \CR}{flag incoming visibilities with correlator
           weights less than 0.65.}
\dispt{DOWEIGHT\qs 1 \CR}{to have the data weights include channel
           bandwidth and integration time as well as correlator
           weights.}
\dispt{SOURCES\qs ' '; QUAL\qs 0\CR}{to accept all sources found.}
\dispt{TIMERANG\qs 0 \CR}{to accept data from all times.}
\dispt{BCHAN\qs 0; ECHAN\qs 0; BIF\qs 1; EIF\qs 0 \CR}{to accept all
           channels in all IFs.}
\dispt{SELBAND\qs 0 \CR}{bandwidth to select (kHz).}
\dispt{SELFREQ\qs 0; FQTOL\qs 0\CR}{frequency to select with tolerance
           of 10 kHz.}
\dispt{OPCODE\qs ' '\CR}{to not copy the tape statistics table ('VT'
           table).}
\dispt{GO \CR}{to run the program.}
\pd

This may seem a bit formidable.  For straightforward VLBI
observations, there is a collection of procedures to simplify matters
including the loading of data.  Enter
\dispt{RUN \tndx{VLBAUTIL} \CR}{to acquire the procedures; this need
           be done only once since they will be remembered.}
\dispt{INTAPE {\it n\/}\CR}{to specify the input tape number.}
\dispt{NCOUNT\qs 20 \CR }{to load 20 tape files.}
\dispt{OUTNAME\qs 'TEST' ; OUTDI\qs 1 \CR}{to specify the name and
           disk of the output file.}
\dispt{DOUVCOMP\qs 1 \CR}{to save disk space by writing compressed
           data.}
\dispt{CLINT\qs $\triangle t$ \CR}{to set the {\tt CL} table interval
           to $\triangle t$ minutes (see discussion below).}
\dispt{INP\qs VLBALOAD \CR}{to review the inputs.}
\dispt{\Tndx{VLBALOAD} \CR}{to run the procedure.}
\dispe{Because the data files tend to be very large, you will usually
write compressed data ({\tt DOUVCOMP=1}).  These files take about 1/3
of the space of `uncompressed' data sets, but cause information about
the weights of individual polarizations, spectral channels, and IFs to
be lost.  There is some loss in dynamic range and sensitivity when the
weight information is (partially) compromised.  (See \Rappen{size} for
an expanded discussion of when to and when not to write `compressed'
data sets.)  If your observation has more than one DAT or Exabyte
tape, simply run {\tt \Tndx{FITLD}} for each tape.  Setting {\tt
DOCONCAT 1} and setting the output file name completely will ensure
that the data from separate tapes with compatible observing band/data
structure will be appended to existing \AIPS\ files.  Generally, after
loading all of your data, you will have one file for each such
observing band and/or observing mode.  However, observations which
require multiple passes through the correlator will have one file per
observing mode {\it per correlation pass\/}.  Data from separate
correlator passes can be concatenated using task {\tt VBGLU} and/or
merged with task {\tt VBMRG}\@.\Iodx{VLBA}}\Iodx{VLBI}

Adverb {\tt CLINT}, which specifies the {\tt CL} table time sampling
interval, must be short compared to the anticipated coherence time.
{\tt CLINT} should be set such that the shortest anticipated
fringe-fit interval is spanned by a few {\tt CL} entries. Time
sampling in the {\tt CL} table that is too coarse can lead to
calibration interpolation errors when applying the fringe-fit
solutions at later stages of the data reduction.  If the interval is
made unnecessarily short the {\tt CL} table may become unmanageably
large.\label{sect:clint}

It is recommended that corrections for digital representation of the
correlated signals be performed in {\tt FITLD} under control of adverb
{\tt DIGICOR}, but only for data from the VLBA correlator.  {\tt
DIGICOR} should be set to one for all continuum and nearly all
spectral line experiments.  Set {\tt DIGICOR} to 3 or 4 if the digital
corrections are desired for a non-VLBA correlator, \eg\ some versions
of the DiFX correlator.  In the special case of spectra with very
strong narrow features, the absence of correlator zero-padding may
limit the accuracy of the quantization corrections.  See the {\tt
FITLD} help file for further information.  The details of digital
correction for FX correlators can be found in {\it Radio Science\/}
{\bf 33}, 5, 1289--1296,  ``Correction functions for digital
correlators with two and four quantization levels'', by L. Kogan.

Adverb {\tt DELCORR} enables amplitude corrections for known delay
decorrelation losses in the VLBA correlator, as described in \AIPS\
Memo~90 (1995, ``Delay decorrelation corrections for VLBA data within
\AIPS'' by A. J. Kemball). Setting {\tt DELCORR=1} will create a
correlator parameter frequency ({\tt CQ}) table for each file written
by {\tt FITLD}\@.  Do this for the VLBA correlator only.  The presence
of this table enables the delay decorrelation correction once the
residual delays have been determined in fringe-fitting. These
corrections will not be applied if the data were not correlated at the
\Indx{VLBA} correlator or if the {\tt CQ} table is missing.  For older
{\tt FITLD} files the {\tt CQ} table can be generated using task {\tt
\tndx{FXVLB}} and this must be done before any changes in the
frequency structure of the file are made. The {\tt CQ} table is used
for rate and delay amplitude decorrelation corrections after residual
delay and rate errors have been determined by fringe-fitting, and are
being applied to the data.  The {\tt CQ} table has no immediate effect
on the data written by {\tt FITLD} but is essential for later
processing.

The {\tt WTTHRESH} adverb can be applied to drop incoming data with
playback weights less than the specified limit.  Note that data
flagged in this way are {\it unrecoverable\/} except by re-running
{\tt FITLD}\@.  The data weights are normalized to unity so good data
usually have correlator weights close to 1.0.  If {\tt DOWEIGHT > 0},
the actual data weights will be scaled by twice the product of the
channel bandwidth in Hz and the integration time in seconds.  This
should make the weights approximately one over the rms squared.  You
should examine your data carefully if you use {\tt WTTHRESH} to make
sure that you have not discarded too much data at this stage.
Typically 0.8 or higher is good for the VLBA, but for non-VLBA
stations a lower value such as 0.6 or 0.7 may be
appropriate.\Iodx{VLBI}

Calibration data have been transferred from the correlator with your
data if your data include VLBA antennas and were correlated after 1
April 1999 and before late 2009, when the DiFX correlator came on
line and your {\tt IMHEADER} listing shows the presence of {\tt
GC}, {\tt TY}, {\tt WX}, {\tt PC} and {\tt FG} tables, as in the
example below.  If you loaded more than one tape file, you must merge
the calibration tables.  {\tt VLBALOAD} does the merging for you.
See \Sec{caltransfer} for
additional details.  Note that, as this example shows, it is possible
your data have calibration transfer tables even though they were
correlated before 1 April 1999.  If your {\tt IMHEADER} does not show
{\tt GC} and {\tt TY} tables, you do not have calibration transfer and
must manually load calibration information in from text files.  Also,
even if you have calibration transfer, you may still have to manually
load calibration information for some non-VLBA antennas (see {\tt
https://science.nrao.edu/facilities/vlba/calibration-and-tools/caliblogs}
for some information in this regard).

The output files produced by {\tt FITLD} are in standard multi-source
format (as described in \Sec{uvtape}) and contain data from all the
target and calibrator observations in your observation.  {\tt FITLD}
also writes a large number of extension \indx{tables} including an
index ({\tt NX}) table, and many tables containing calibration
information. A description of the \Indx{VLBA} correlator table types
is given in \Sec{vlbtables}. If you are missing the {\tt CORR-ID}
random axis, your \AIPS\ release is stale (pre-{\tt 15APR97}) and you
are strongly encouraged to upgrade to the latest release; much of the
information presented in this chapter will not be usable with pre{\tt
15APR97} releases of \AIPS\@.  Your catalog header should be similar
to the one, obtained using verb {\tt IMHEADER}, given below.  If you
have {\tt GC}, {\tt TY}, {\tt FG}, {\tt WX}, and {\tt PC} tables as in
this example data header, your data were processed with calibration
transfer - see \Sec{caltransfer} for more details.\Iodx{VLBI}
\vskip 5pt
\bve
 Image=MULTI     (UV)         Filename=329         .OVLB  .   1
 Telescope=VLBA               Receiver=VLBA
 Observer=TM008               User #=   44
 Observ. date=23-SEP-1998     Map date=06-JAN-1999
 # visibilities      6567     Sort order  **
 Rand axes: UU-L  VV-L  WW-L  TIME1  BASELINE  SOURCE  FREQSEL
            INTTIM  CORR-ID  WEIGHT  SCALE
 ----------------------------------------------------------------
 Type    Pixels   Coord value     at Pixel     Coord incr   Rotat
 COMPLEX      1   1.0000000E+00       1.00  1.0000000E+00     .00
 STOKES       1  -2.0000000E+00       1.00 -1.0000000E+00     .00
 FREQ        16   4.9714900E+09        .53  5.0000000E+05     .00
 IF           8   1.0000000E+00       1.00  1.0000000E+00     .00
 RA           1    00 00 0 .000       1.00        .000000     .00
 DEC          1    00 00 0 .000       1.00        .000000     .00
 ----------------------------------------------------------------
 Coordinate equinox 2000.00
 Maximum version number of extension files of type HI is   1
 Maximum version number of extension files of type CQ is   1
 Maximum version number of extension files of type AT is   1
 Maximum version number of extension files of type IM is   1
 Maximum version number of extension files of type CT is   1
 Maximum version number of extension files of type GC is   1
 Maximum version number of extension files of type TY is   1
 Maximum version number of extension files of type FG is   1
 Maximum version number of extension files of type PC is   1
 Maximum version number of extension files of type MC is   1
 Maximum version number of extension files of type OB is   1
 Maximum version number of extension files of type AN is   1
 Maximum version number of extension files of type WX is   1
 Maximum version number of extension files of type FQ is   1
 Maximum version number of extension files of type SU is   1
 Keyword = 'OLDRFQ  '  value =  4.97149000D+09
\end{verbatim}\eve

Note that the sort order of the output data set is listed as {\tt **}
rather than {\tt TB} and that there are no attached {\tt CL} and {\tt
NX} tables.  This happens when {\tt \Tndx{FITLD}} detects what might
be a sub-array condition (two frequency IDs or two sources observed at
the same time) on reading the data.  In clear cases, the actual
simultaneous frequency IDs and sources will be reported.  In this case,
{\tt FITLD} detected the use of multiple integration times on
different baselines in the data set; this is common for SVLBI data.
The message reported by {\tt FITLD} in this case takes the form:
\bve
**********************************************
FITLD5:  Subarray or multiple dump-rate condition found.
FITLD5:  NX/CL tables deleted.
FITLD5:  Use USUBA to set up subarrays.
FITLD5:  Rerun INDXR using CPARM(3) and (4)
FITLD5: *******************************************
\end{verbatim}\eve

\dispe{Unless any of the following criteria are met, the data written
by {\tt FITLD} are immediately ready for further processing.}

\xbit
\item\ If the sort code has been blanked as in this example, you must
      sort the data (use {\tt \tndx{UVSRT}} or {\tt MSORT})\@.
\item\ If the source subarray condition is encountered, you may need
      to run {\tt \tndx{USUBA}} {\it after} doing any {\tt ANTAB} that
      may be needed.\@.\Iodx{VLBI}
\item\ If the frequency ID subarray condition is encountered, you must
      separate the frequency IDs into separate data sets; procedure
      {\tt VLBAFQS} will do this for you.
\item\ If {\tt FITLD} does not leave behind {\tt CL} and {\tt NX}
      tables, you must run {\tt \tndx{INDXR}} to create them.
      Procedure {\tt \Tndx{VLBAFIX}} will do all of the above for you.
\item\ If you wish to join together data processed in multiple
      correlator passes, you must run {\tt VBGLU} and/or {\tt
      VBMRG}\@.
\xeit

{\tt \Tndx{FITLD}} can also be used to load archived \AIPS\ data
previously written to tape using either {\tt FITTP} or {\tt FITAB}, as
described in \Sec{uvlod}\@.  In this case the \Indx{VLBA}
correlator-specific adverbs, such as those enabling digital and delay
corrections, are not active.

\Subsubsections{Calibration transfer}{caltransfer}

Beginning on 1 April 1999, the \Indx{VLBA} correlator attaches
calibration information for VLBA and some non-VLBA antennas directly
to the output FITS files.  If your {\tt IMHEADER} listing shows {\tt
GC}, {\tt TY}, {\tt WX}, {\tt FG}, and {\tt PC} tables, then the
correlator has provided calibration information; this service is
called {\it calibration transfer\/}.  Note that projects correlated at
slightly earlier dates may also have calibration transfer information.
You must have {\tt 15APR99} or later version of \AIPS\ to take
advantage of calibration transfer. Not all antennas provide all the
information needed for calibration transfer to the VLBA correlator,
see $${\tt
https://library.nrao.edu/public/memos/vlba/ops/VLBAO\_34.pdf}$$
for the latest information on this subject.  For those antennas for
which calibration information was not transferred by the VLBA
correlator, you must process the log files in the traditional way as
outlined in \Sec{vlblogs}.  Calibration for the VLA and the GBT began
to be transferred with the FITS files in November 2003.\Iodx{VLBI}

{\it Between April 1999 and late 2009} the information processed by the
correlator was somewhat redundant so
that the calibration tables, the {\tt GC} table in particular, must be
merged using {\tt TAMRG}, a  very general and hence complicated task.
There are a couple procedures to do this for you
in the {\tt VLBAUTIL} package, {\tt VLBAFIX} and {\tt VLBAMCAL}, if you
have previously run {\tt VLBAFIX} your tables have been merged:
\dispt{RUN \tndx{VLBAUTIL} \CR}{to acquire the procedures; this should
           be done only once since they will be remembered.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
             input file.}
\dispt{INP\qs VLBAFIX \CR}{to review the inputs.}
\dispt{\Tndx{VLBAFIX} \CR}{to run the procedure.}
X\dispe{You should use {\tt VLBAFIX} after you have finished loading
the data from tape, but before you either change the polarization
structure of the data with {\tt FXPOL}, load any
calibration data for non-VLBA telescopes, or apply the calibration
data.}

At this point it is a good idea to save the tables that were loaded with
your data with {\tt TASAV}.  This protects you from having to reload
the uv data from scratch if one of the original tables is damaged in some
way.  If you need to copy a table from the {\tt TASAV}'ed file use
{\tt TACOP}.


\Subsubsections{Repairing VLBA data after {\tt FITLD}}{vlbafix}

As listed above, there are a variety of reasons why VLBA data may need
some repair after {\tt FITLD} has been run.  They may need to be
sorted into strict time order, to have the subarray nomenclature
corrected, to be split into different frequencies, to have the
polarization structure fixed, and/or to have the original index ({\tt
NX}) table and calibration (({\tt CL}) recreated.  These repairs can
all be done by the procedure {\tt VLBAFIX}, which will examine the
data and perform any of the necessary fixes.  If the data contain
subarrays then the procedure must be told to split the data into
multiple subarrays ({\tt SUBARRAY=2}), otherwise it will assume no
subarrays and force all the data into one subarray.{\tt
\Tndx{VLBAFIX}} is intended to replace {\tt VLBASUBS}, {\tt
VLBAFQS}, {\tt VLBAMCAL} and {\tt VLBAFPOL}, all of which can be
run individually instead.  Also we have recommended in the last few
sections that {\tt VLBAFIX} be run, if you have already run it, it does not
need to be run again.
\dispt{RUN \tndx{VLBAUTIL} \CR}{to acquire the procedures; this should
           be done only once since they will be remembered.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
             input file.}
\dispt{CLINT\qs $\triangle t$ \CR}{to set the {\tt CL} table interval
           to $\triangle t$ minutes (see discussion above in
           \Sec{clint})\@.}
\dispt{OUTDISK\qs{\it m\/} \CR}{to specify the output disk when
           needed.}
\dispt{INP\qs VLBAFIX \CR}{to review the inputs.}
\dispt{\Tndx{VLBAFIX} \CR}{to run the procedure.}
\dispe{Remember that all of the {\tt VLBAUTIL} procedures have {\tt
HELP} files with good discussions about when to use the simple
procedures and when to use the tasks directly.\Iodx{VLBI}}

\Subsubsections{Sorting and indexing VLBA correlator data}{vlbsort}

If multiple integration times are used on different baselines, the
VLBA correlator will write data that are not in strict time-baseline
({\tt TB}) sort order.  {\tt VLBAFIX} (\Sec{vlbafix}) will sort
your data if needed, if you want to do the sorting by hand do the
 following. In general, task {\tt UVSRT} can be used to
sort randomly ordered \uv\ data files in \AIPS, but has significant
disk space requirements through the use of intermediate scratch files.
A special task, {\tt \Tndx{MSORT}}, has been written which uses a
direct memory sort with sufficiently large buffers to accommodate the
scale over which the data deviate from true time-baseline sort order.
No intermediate scratch files are used and it can be significantly
faster than {\tt UVSRT} for this special case.  {\tt MSORT} competes
with {\tt UVSRT} in performance even in other cases, particularly when
the individual visibility records are large due to many spectral
channels and/or IFs.  The inputs to {\tt MSORT} are similar to those
required by {\tt UVSRT} and take the form:
\vfill\eject
\dispt{TASK\qs 'MSORT' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
             input file.}
\dispt{OUTDISK {\it n\/} ; OUTNAM\qs ' ', OUTCLA\qs ' '}{to specify the
             output file.}
\dispt{SORT\qs '\qs' \CR}{to select default sort order ('TB' or
             time-baseline).}
\dispt{GO \CR}{to run the program.}
\dispe{Note that if the input and output file names are identical, the
input file is sorted in place.  In-place sorting  is dangerous, but
may be necessary if there is insufficient disk space for a second copy
of the data set or for the intermediate scratch files required by {\tt
UVSRT}\@.  {\it Never abort an in-place sort in progress because you
will destroy the integrity of your data set.}}

\Subsubsections{Subarraying VLBA correlator data}{vlbasubs}

If the project was observed without using subarrays (defined as times
at which separate antennas are simultaneously observing different
sources or at different frequencies), {\it this step involving\/ {\tt
USUBA} is not necessary and should be skipped\/}.

If the observations have been scheduled in separate subarrays, defined
either by source or frequency selection, the subarrays should be
labeled in \AIPS\ before proceeding any further.  The \Indx{VLBA}
correlator does not conserve subarray information, which in any event
often has no unique characterization.  This is specified in \AIPS\
using task {\tt \Tndx{USUBA}} which allows subarrays to be defined
through either the input adverbs, an external {\tt KEYIN} text file,
or through the use of an automatic algorithm to identify and label
subarrays found in the data. The automatic algorithm is recommended,
{\it but its results should be checked closely}.  Note that {\tt
ANTAB} tables do not know about subarrays that will be assigned by
{\tt USUBA}, so you must run all {\tt ANTAB}s before running {\tt
USUBA}\@.

If you have subarrays, they need to be sorted, have the subarray
nomenclature corrected, and/or have the index ({\tt NX}) table and
calibration ({\tt CL}) version 1 table rebuilt.  In this case,
there is a simplified procedure to combine the three repair operation,
{\tt VLBASUBS}.  Only use this procedure if you know you have subarrays.
\dispt{RUN \tndx{VLBAUTIL} \CR}{to acquire the procedures; this should
           be done only once since they will be remembered.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
           input file.}
\dispt{CLINT\qs $\triangle t$ \CR}{to set the {\tt CL} table interval
           to $\triangle t$ minutes.}
\dispt{INP\qs VLBASUBS \CR}{to review the inputs.}
\dispt{VLBASUBS \CR}{to run the procedure.}
\dispe{The only user-controllable input is the {\tt CL} table interval;
see discussion above.  {\tt VLBAFIX} will perform this operation if
requested (\Sec{vlbafix}).\Iodx{VLBI}}

For automatic subarray labeling by {\tt USUBA}, representative input
parameters would be:
\dispt{TASK\qs 'USUBA' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
             input file.}
\dispt{OPCODE\qs 'AUTO' \CR}{to identify subarrays automatically.}
\dispt{TIMERANG\qs 0 \CR}{to include all times.}
\dispt{ANTENNAS\qs 0 ; SOURCES\qs ' ' \CR}{to include all antennas and
              sources.}
\dispt{FREQID\qs -1 ; SUBA\qs 0 \CR}{to include all frequency IDs and
              subarrays.}
\dispt{INFILE\qs '\qs ' \CR}{to use no external file for subarray
              identifications.}
\dispt{GO \CR}{to run the program.}
\dispe{Sometimes {\tt FITLD} erroneously identifies a subarray
condition, usually because of spurious total-power data points.  In
such cases, you can set {\tt OPCODE = '\qs' ; SUBARRAY = 1} to force
all data into the first subarray.}

In circumstances requiring {\tt USUBA}, one often wants the
calibration in one subarray to apply to other subarrays.  {\tt USUBA}
will make the subarray column have value 0 which means all.  Other
tasks may not be so obliging so you may need to use {\tt TABED} or
verb {\tt \tndx{TABPUT}} to change tables from subarray-specific to
subarray-general.

%\vfill\eject   %???
\Subsubsections{Indexing VLBA correlator data}{vlbINDXR}

If {\tt FITLD} had not written {\tt NX} or {\tt CL} tables or it was
necessary to sort the data as described in \Sec{vlbsort}, you must run
task {\tt \Tndx{INDXR}}\@.  If {\tt VLBAFIX} (\Sec{vlbafix})  was
run this is done automatically.  {\tt INDXR} will generate an {\tt NX}
table and, if need be, a {\tt CL} table. Typical parameters for {\tt
INDXR} are:
\dispt{TASK\qs 'INDXR' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
               input file.}
\dispt{PRTLEV\qs 0\CR}{to print minimal details of progress.}
\dispt{CPARM\qs 0, 0 , $\triangle t$ , 1 \CR}{to set the {\tt CL}
              interval to $\triangle t$ and recalculate the model.}
\dispt{GO \CR}{to run the program.}
\dispe{Note that {\tt CPARM(4)} can be set to zero unless the
correlator model is required in later reduction (\eg\ in astrometry or
geodesy observations)  The {\tt CL} table sampling interval $\triangle
t$ should be chosen subject to the same considerations given regarding
adverb {\tt CLINT} in the discussion of {\tt FITLD} in
\Sec{clint}\@.  {\tt VLBAFIX} will perform this operation if needed
(\Sec{vlbafix}).}

\Subsubsections{Concatenating VLBA correlator data}{vlbDBCON}

Sometimes an observation is correlated using multiple passes through
the \Indx{VLBA} correlator.  In this context, multiple pass means
different IFs/pass; this is due to data rate limitations in the
correlator.  Be careful to have {\tt FITLD} load each pass into a
separate disk file; otherwise a very confused data set will be
produced.  If it is desired to join together the IFs correlated on
each pass, the task {\tt \Tndx{VBGLU}} should be used.  {\tt VBGLU}
can only handle data sets that have the same polarization and spectral
channel parameters.  In {\tt 31DEC21}, it can join data sets from
different days while previously it required the oservation date to be
the same. If the IFs are not observed at the same time, the file becomes
rather larger due to the many flagged IFs.  But, this option does allow
rather different frequencies to be imaged together correctly.  Task {\tt
\tndx{MATCH}} may be used to make the antenna, source, and frequency ID
numbers in one data set the same as those in another data set so that
they may be used as inputs to {\tt VBGLU}\@.  Note that {\tt MATCH} is
very fussy about details.  You may use {\tt \Tndx{RESEQ}} to renumber
antennas and {\tt \Tndx{RESOU}} to renumber sources in order to bring
data sets into agreement. \Iodx{VLBI}

The inputs to {\tt VBGLU} are rather simple.  Each of the input files
to be glued together is specified via {\tt INNAME}--{\tt IN4NAME},
and an output file is specified via {\tt OUTNAME}\@.  The choice
of input file 1 is no longer important.  No data are lost in the revised
version of this task.
\dispt{TASK\qs '{\tt VBGLU}' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
              input file.}
\dispt{IN2DISK\qs{\it n\/} ; GET2N\qs {\it ctn\/} \CR}{to specify the
              $2^{\und}$ input file.}
\dispt{IN3DISK\qs{\it n\/} ; GET3N\qs {\it ctn\/} \CR}{to specify the
              $3^{\urd}$ input file.}
\dispt{IN4DISK\qs{\it n\/} ; GET4N\qs {\it ctn\/} \CR}{to specify the
              $4^{\uth}$ input file.}
\dispt{OUTDISK\qs{\it n\/} \CR}{to specify the output disk.}
\dispt{GO \CR}{to run the program.}
\pd

With the changes in recording technology, it is also possible that a
correlator will not have enough playback units for all antennas in an
experiment.  In this case, multiple correlations will also have to be
done in order to correlate every possible baseline.  But, inevitably,
certain baselines will appear more than once in these correlations.
{\tt FITLD} will load all passes into a single data set (if {\tt
DOCONCAT=1}) or separate disk files which may be concatenated, after
{\tt MATCH}, with {\tt DBCON}\@.  Note that {\tt MATCH} is very fussy
about details.  You may use {\tt \Tndx{RESEQ}} to renumber antennas
and {\tt \Tndx{RESOU}} to renumber sources in order to bring data sets
into agreement.  Sort the data set into {\tt 'BT'} order with {\tt
UVSRT}\@.  Then task {\tt \Tndx{VBMRG}} may be used to discard any
duplicate data.  Task {\tt \tndx{DBAPP}} may be used to avoid the $2^n$
proliferation of files, but only if the files are fairly similar in
antennas, subarrays, and frequency IDs.


\Subsubsections{Labeling VLBA correlator polarization data}{fxpol}

The \Indx{VLBA} correlator does not preserve \indx{polarization}
information unless it is operating in full polarization mode.  This
results in polarizations not being labeled correctly when both RR and
LL polarizations are observed without RL and LR\@.  Each VLBA
correlator band is loaded into \AIPS\ as a separate IF and is
assigned the same polarization.  {\tt \Tndx{FXPOL}} takes a data set
from the VLBA correlator and produces a new data set that has the
correct IF and polarization assignments.  Unfortunately, there is no
reliable way to determine the polarization of each IF from the input
data set  and you must specify the polarization assignments using the
{\tt BANDPOL} adverb.\Iodx{VLBI}

Most VLBA setups assign odd-numbered bands to RCP and even-numbered
bands to LCP\@.  In this case {\tt BANDPOL} should be set to {\tt
'*(RL) '} (the default) and {\tt FXPOL} will generate a new data set
that is of equal size to the input data set, but has two polarizations
and half the number of IFs.  This case normally applies if {\tt LISTR}
shows pairs of IFs with the same frequency and {\tt QHEADER} shows one
pixel on the {\tt STOKES} axis with coordinate value {\tt RR}, but
there may be exceptions to this rule when non-VLBA antennas are used.

There is a procedure for use with
VLBA-only data that attempts to determine which of the above cases
applies and then runs {\tt FXPOL} for you, if you ran {\tt VLBAFIX}
(\Sec{vlbafix}) this has already been done:
\dispt{RUN \tndx{VLBAUTIL} \CR}{to acquire the procedures; this should
           be done only once since they will be remembered.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
             input file.}
\dispt{INP\qs VLBAFPOL \CR}{to review the inputs.}
\dispt{\Tndx{VLBAFPOL} \CR}{to run the procedure.}
\dispe{Use {\tt VLBAFPOL} to check whether you need to relabel the
polarizations in your data after loading the data, looking for
subarrays, and merging redundant calibration data, but before reading
any calibration data from non-VLBA stations.  {\tt VLBAFPOL} assumes
that all of your {\tt FREQID}s have similar polarization setups.  For
this reason, you should normally run {\tt VLBAFPOL} after copying each
frequency ID to a separate file using {\tt VLBAFQS} (\Sec{vlbcalib}).
This strategy also reduces the amount of disk space needed for {\tt
VLBAFPOL}.}

To use {\tt FXPOL} directly, typical inputs are:
\dispt{TASK\qs 'FXPOL' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
              input file.}
\dispt{BANDPOL\qs '*(RL)' \CR}{to specify the normal VLBA polarization
              structure.}
\dispt{GO \CR}{to run the program.}
\dispe{Consult {\tt HELP \Tndx{FXPOL}} for further information
about more complicated cases.  Note that {\tt FXPOL} has to write a
new output file since the structure of the data is being changed.  All
standard extension files are also converted, but it is still a good
idea to run {\tt FXPOL} before running the calibration tasks.}

In single-polarization observations, LL data may simply be mis-labeled
as RR or vice-versa.  This does not need to be corrected within \AIPS\
but the user needs to take this into account when selecting or
calibrating the data, particularly in specifying the
\indx{polarization} in the amplitude calibration text file
(\Sec{vlblogs}). The Stokes axis can however be modified.  Before
running {\tt PUTHEAD}, you should run {\tt IMHEAD} to check which axis
is the Stokes axis in the catalog header.
\dispt{INP\qs \tndx{PUTHEAD}\CR}{to review the inputs.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
              input file.}
\dispt{KEYWORD\qs 'CRVAL{\it m\/}' \CR}{to select the Stokes or
              $m^{\uth}$ axis in the header.}
\dispt{KEYVALUE\qs = -2 \CR}{to set the Stokes value to 'LL' (or -1
             for 'RR').}
\dispt{PUTHEAD \CR}{to set the coordinate value.}
\pd

\Subsubsections{Ionospheric corrections}{sTECOR}

\Todx{TECOR}\Iodx{VLBI}
At low frequencies (2~GHz and lower) the ionosphere can cause large
unmodeled dispersive delays, seen as rapid phase wrapping.  This can
be of particular importance in phase referencing observations, where
phases must be interpolated over weak sources.  Even at high
frequencies (\eg\ 8~GHz) the ionosphere can be important, depending on
the experiment and the condition of the atmosphere during the
observation.  One way to remove at least some of the ionospheric phase
offsets is by applying a global ionospheric model derived from GPS
measurements.  The \AIPS\ task {\tt \Tndx{TECOR}} processes such
ionospheric models that are in standard format known as the IONEX
format.  These models are available from the Crustal Dynamics Data
Information System (CDDIS) archive.  There is a procedure
which is part of {\tt VLBAUTIL}, called {\tt \Tndx{VLBATECR}} that
automatically downloads the needed IONEX files from CDDIS and runs
{\tt TECOR}\@.  It will examine the header and the {\tt NX} table and
figure out which dates need to be downloaded, so the observation date in
the header must be correct and an {\tt NX} table must exist.  See {\tt
EXPLAIN VLBATECR} for other requirements.  {\tt TECOR} also determines
the ionospheric Faraday rotation which is applied in the calibration of
the cross-hand visibilities.

\dispt{RUN \tndx{VLBAUTIL} \CR}{to acquire the procedures; this should
           be done only once since they will be remembered.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
             input file.}
\dispt{INP\qs VLBATECR \CR}{to review the inputs.}
\dispt{\Tndx{VLBATECR} \CR}{to run the procedure.}

You can also download the files manually from the CDDIS archive
through anonymous ftp and run {\tt VLBATECR} or {\tt TECOR}, see {\tt
EXPLAIN TECOR} for detailed instructions on how to retrieve the
models.  {\tt TECOR} interpolates between the maps of electron content
in the ionosphere; therefore IONEX files must be retrieved to cover
the entire experiment.  Presently, each IONEX file contains maps every
2 hours from hours 00:00 to 24:00.  Before November 2002, they
contained maps every 2 hours from hours 1:00 through 23:00.
Therefore, for example, if an experiment prior to November 2002
started at 0:00 then files must be retrieved for the day of the
experiment and the previous day so the times between 0:00 and 0:59 can
be interpolated.  More recent experiments require two or more files
only if they occurred in two or more days.

Typical inputs to {\tt TECOR} are:
\dispt{TASK\qs 'TECOR' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
              input file.}
\dispt{INFILE\qs 'FITS:JPLG1230.01I' \CR}{to set the name of the IONEX
              file.  If there is more than one file, this name {\it
              must\/} be a standard format and be the first file.  See
              {\tt EXPLAIN TECOR} for more details.}
\dispt{NFILES\qs $n$ \CR}{to set number of IONEX files to be read.}
\dispt{SUBARRAY\qs 0 \CR}{to process all subarrays.  This option
              allows you to process subarrays used on different
              dates.}
\dispt{ANTENNAS\qs 1 2 3 4 6 7 8 9 10 \CR}{to find corrections for all
              antennas except antenna 5 in a ten antenna experiment.
              This is important because if the IONEX models do not
              cover an antenna and it is not excluded here then all
              the solutions for that antenna will be undefined and the
              data flagged when the {\tt CL} table is applied.}
\dispt{GAINVER\qs 1 \CR}{to apply corrections to the first {\tt}CL
              table.}
\dispt{GAINUSE\qs 2 \CR}{to create {\tt CL} table 2 with the
              corrections.}
\dispt{APARM\qs 1  0 \CR}{to correct for dispersive delay; otherwise
              only the ionospheric Faraday rotation will be
              corrected.}
\dispt{GO \CR}{to run {\tt TECOR}, correcting for the ionosphere in a
              new {\tt CL} table.}
\pd

The dispersive delays should be checked using {\tt \tndx{EDITA}}
(option {\tt DODELAY=3}), {\tt SNPLT} (options {\tt INEXT 'CL'; INVERS
2; OPTY 'DDLY'}) and {\tt VPLOT} (options {\tt BPARM 0; APARM 0; DOCAL
1; GAINUSE 2}).  {\tt \tndx{TEPLT}} plots parameters from the {\tt TE}
table written by {\tt TECOR}, in particular the Faraday rotation, total
electron content, and dispersive delay.  It can also plot the difference
of two {\tt TE} tables in multiple parameters.  {\tt \tndx{MFIMG}} can
be used to make an image cube of the IONEX data after which {\tt
TVMOVIE} and other image display tools will let you examine the data
given to {\tt TECOR}\@.  {\tt \Tndx{TECOR}} is only as good as the
models, which at this time are quite rough.  Therefore, it is a very
good idea to compare the corrected and uncorrected phases using {\tt
VPLOT}\@.\Iodx{VLBI}

Extensive studies have revealed that {\tt TECOR} usually over-corrects
data.  It removes the time-dependent IFRM, but leaves behind an extra
rotation measure that changes some with obsering date and very slightly
with source.  A package of software called {\tt ALBUS} has been found
to give somewhat better solutions for the IFRM\@.  In {\tt 31DEC24} a
task also named {\tt \Tndx{ALBUS}} was written to invoke this package
to correct $uv$ data including dispersive delay which is important to
VLBI data.  Unfortunately, the complications of this package require
the Linux operating system and an outside program called {\tt
apptainer}.  See EVLA Memo 235 for details.\footnote{"Testing
Ionospheric Faraday Rotation Measure Models", Perley R., Greisen, E.,
Tremou, L., Butler, B., Willis, T., October 2024}

{\tt \tndx{CLCOR}} has a {\tt OPCODE = 'IONO'} to make delay corrections
for the ionosphere, similar to the {\tt 'ATMO'} operation which is for
the atmosphere (\Sec{delzn}).

\Subsubsections{Corrections to the Earth Orientation Parameters}{sEOPcor}

This correction is only useful for experiments correlated at the VLBA
correlator.  VLBI correlators must use measurements of the Earth
Orientation Parameters (EOPs) to take them out of the observations.
These change slowly with time and therefore the EOPs used by the
correlator must be continually updated.  From 5-May-2003 to 9-Aug-2005
the VLBA correlator used old predicted EOPs which could be
significantly wrong and will effect all phase referencing experiments.
Incorrect EOPs can both move the position and possibly smear the
target of a phase referencing experiment.  Self-calibration can
improve the smearing.  Even outside the above quoted period of
particularly bad EOPs, the EOPs can be off so it is recommended that
all phase-referencing experiments, particularly astrometry experiments
should have their EOPs corrected.  {\tt CLCOR} ({\tt OPCODE='EOPS'})
can do this correction.  It uses the {\tt CT} table which is only
produced by the VLBA correlator, so at the moment {\tt CLCOR} can
only correct experiments processed at the VLBA correlator.  {\tt CLCOR}
also uses a file of measured EOPs, which can be downloaded from NASA
(see {\tt EXPLAIN CLCOR} for details).  There is a procedure which is
part of {\tt VLBAUTIL}, called {\tt VLBAEOPS}, which downloads the
file automatically and runs {\tt CLCOR}\@.  To run the procedure:
\dispt{RUN \tndx{VLBAUTIL} \CR}{to acquire the procedures; this should
           be done only once since they will be remembered.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
             input file.}
\dispt{INFILE\qs '\qs' \CR}{to automatically download file.}
\dispt{INP\qs VLBAEOPS \CR}{to review the inputs.}
\dispt{\Tndx{VLBAEOPS} \CR}{to run the procedure.}
\dispe{The procedure will correct the highest {\tt CL} version while
copying it to a version one higher.\Iodx{VLBI}}

If multiple days have been concatenated, you should run {\tt CLCOR}
manually.  Download the file using the instructions in {\tt CLCOR}'s
explain file.  Sample inputs are as follows:
\dispt{TASK\qs 'CLCOR' ; INP \CR}{to review the inputs.}
\dispt{INDISK {\it n1\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
               input file.}
\dispt{OPCODE\qs  'EOPS' \CR}{to select correction of the EOPs.}
\dispt{GAINVER\qs {\it clin\/} \CR}{{\tt CL} table to read, new
               default is the current highest version.}
\dispt{GAINUSE\qs 0 \CR}{{\tt CL} table to write; version highest$+1$
               is written unless {\tt GAINUSE = GAINVER}.}
\dispt{INFILE\qs 'FITS:usno\_finals.erp \CR}{to specify file with
               correct EOPs --- note missing close quote to retain
               lower case letters.}
\dispt{CLCORPRM(2)\qs {\it dd} \CR}{to use {\it dd} days worth of data
               following the start date from the USNO file.  Set
               {\tt dd} to about 4 days more than your last day of
               data.}
\dispt{GO \CR}{to run the program.}
\dispe{In case the automatic download fails, {\tt VLBAEOPS} can use
the file which you have downloaded manually.}

\Subsubsections{Preparing the {\tt OB} table for SVLBI data}{svlbOB}

The spacecraft orbit table ({\tt OB}) as produced by {\tt FITLD}
contains the spacecraft position $(x,y,z)$ and velocity
$(v_x,v_y,v_z)$ as calculated to high accuracy from the JPL
reconstructed orbit using the SPICE package (developed at JPL).  These
quantities are calculated by the correlator on-line software and are
passed directly through to \AIPS\ via {\tt FITLD} by the \Indx{VLBA}
correlator.  The orbit table is indexed on time and can include
information such as the angle between the spacecraft pointing
direction and the Sun, the time since the start and end of the last
eclipse, and the spacecraft parallactic angle. The latter quantities
are not available to the correlator on-line software and, if desired,
need to be computed separately for later use in \AIPS\ by task {\tt
\Tndx{OBTAB}}.  Additionally {\tt OBTAB} stores orbital elements in
the {\tt AN} table; these are essential for later use in plotting or
inspecting spacecraft orbit information.  Sample inputs for {\tt
OBTAB}, are as follows:
\dispt{TASK\qs 'OBTAB' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
           input file.}
\dispt{INVERS\qs 1 \CR}{to process {\tt OB} table 1.}
\dispt{SUBARRAY\qs 1 \CR}{to select subarray number.}
\dispt{APARM 1, 0 \CR}{to update orbital elements in {\tt AN} table}
\dispt{GO \CR}{to run the program.}
\dispe{Note that {\tt APARM(8)} can be used to directly specify which
antenna is the orbiting antenna (this task assumes there is only one
orbiting antenna).\iodx{SVLBI}}

Task {\tt OBTAB} determines mean orbital elements from the {\tt OB}
table using the spacecraft positions and velocities and updates the
{\tt AN} table under control of {\tt APARM(1)}\@.  The orbital
elements can be examined by using {\tt PRTAB} to review the updated
{\tt AN} table.  The mean elements are used to compute \uv\
coordinates for the spacecraft so that model amplitudes AND closure
phases and amplitudes can be plotted (by tasks {\tt VPLOT}, {\tt
CLPLT}, and {\tt CAPLT})\@.  The orbit table can be plotted using task
{\tt \tndx{OBPLT}}\@.  Alternatively, the task {\tt \tndx{TAPLT}} can
be used to display individual columns.  Use {\tt PRTAB} to determine
the names of the columns you wish plotted.

\Subsubsections{Loading the time corrections file for SVLBI
data}{svlbtcorr}

The round-trip residual delay measurements determined by the tracking
stations are supplied to the correlator in FITS format. These
so-called delta-T tables are not passed to \AIPS\ by the correlator
but can be loaded indirectly.  This table might be used, for example,
to plot the time correction as a function of time.  Such information
could be useful if a user suspects a loss of coherence due to a poor
predicted orbit or a clock jump at the tracking station.  The table
contains no internal time stamps, so the row number must be used to
determine the approximate time of a given entry (there are typically
10 rows per second).

The delta-T tables can be loaded at present using {\tt FITLD} and
attached to a null \uv\ data file, using input parameters as follows:
\dispt{TASK\qs 'FITLD' ; INP \CR}{to review the inputs.}
\dispt{OUTDISK {\it n\/} \CR}{to specify a separate output file.}
\dispt{OUTNAM\qs 'DUMMY', OUTCLA\qs 'DT'}{}
\dispt{DATAIN\qs 'FITS:3551708.kct.a \CR}{to specify the external FITS
             file.}
\dispt{GO \CR}{to run the program.}
\dispe{The other {\tt FITLD} adverbs are not relevant in this
instance. Note that lower case letters can be used in the {\tt DATAIN}
adverb if the trailing quotation mark is omitted.  {\tt FITLD} will
load the external FITS file successfully but will print an error
message complaining that no array geometry table was found. This
message can be ignored in this case.  The delta-T table will appear as
an unknown table of type {\tt UK}, and can be plotted using task {\tt
\tndx{TAPLT}}}\Iodx{VLBI}

%\vfill\eject
\Sects{Tools for data examination}{vlbexam}

Before proceeding further it is important to examine the data, to make
sure they are all loaded, and (especially if this is the first time
you have reduced \Indx{VLBI} data) to familiarize yourself with the
data structure.  As processing continues it is also important to
inspect the data periodically to check on the progress of the
calibration.  Use the verb {\tt IMHEAD} regularly to check the
\uv-data header, particularly the list of tables (as seen in
\Sec{fitld}).

Some tasks that can be used to examine the data and the associated
tables are {\tt LISTR}, {\tt DTSUM}, {\tt POSSM}, {\tt VPLOT}, {\tt
CLPLT}, {\tt CAPLT}, {\tt EDITR}, {\tt TVFLG}, {\tt SPFLG}, {\tt
SNEDT}, {\tt SNPLT}, {\tt PRTAB}, {\tt FRPLT}, {\tt PRTAN}, {\tt
COHER}, {\tt OBPLT}, and {\tt SHOUV}\@.  Some of these tasks are
described in the next few pages.

\subsections {Textual displays}

As a first step, use the procedure {\tt \Tndx{VLBASUMM}} to print out
the essential contents of your data set:
\dispt{RUN \tndx{VLBAUTIL} \CR}{to acquire the procedures; this should
           be done only once since they will be remembered.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
             input file.}
\dispt{DOCRT\qs -1 \CR}{to direct the output to the line printer.}
\dispt{INP\qs VLBASUMM \CR}{to review the inputs.}
\dispt{\Tndx{VLBASUMM} \CR}{to run the procedure.}
\dispe{This will make a listing of the scans, sources, frequency
structure, and antennas found in your data set.  You should run this
procedure after ``fixing'' the data with {\tt VLBAMCAL}, {\tt
VLBAFQS}, {\tt VLBASUBS}, and {\tt VLBAFPOL}, but you may also find
it useful on the initial dataset.}

{\tt VLBASUMM} runs the task {\tt \tndx{LISTR}} to give a listing of
the scans, with source names, time ranges, frequency ID's and total
number of visibilities per scan for each of your output files.  It is
often useful to print out a paper copy of this to facilitate later
data plotting/editing.  If you did not do {\tt VLBASUMM},
use:
\dispt{TASK\qs 'LISTR' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
              input file.}
\dispt{OPTYP\qs 'SCAN' \CR}{to request printing of scan summaries.}
\dispt{DOCRT\qs -1 \CR}{to direct the output to a printer.}
\dispt{OUTPRINT\qs '  ' ; \CR}{to have the output printed
              immediately.}
\dispt{GO \CR}{to run the program.}
\dispe{Note that at the end of the above {\tt LISTR} output is useful
information about the frequency structure of your data set.  In {\tt
31DEC23}, {\tt \tndx{LISUN}} produces a similar listing plus the angle
of each scan to the Sun with fewer adverbs to consider.  {\tt LISUN}
also prints a summary of the antennas used.  {\tt LISTR} with {\tt OPTYP
= 'LIST'} and {\tt DPARM(1) = 1} is also a good way to look for phase
coherence.  If {\tt LISTR} fails at this point, you may have forgotten
to run {\tt INDXR} and/or {\tt MSORT} (see \Sec{vlbINDXR}
and \Sec{vlbsort}).}

Other verbs/tasks for inspecting your data include;
\xben
\Item {\tt \tndx{IMHEAD}} lists the file header including
    information on the number of frequency channels and Stokes
    parameters in the data and gives a list of all the extension
    tables.
\Item {\tt \tndx{PRTAB}} can be used to print the contents of any of
    these extension tables, for instance the {\tt SU} or Source table
    contains information about each of the sources observed.  Some
    tables have very many columns. You can use input parameter
    {\tt BOX} to select the list of the columns you want to print.
\Item {\tt \tndx{PRTAN}}, run by {\tt VLBASUMM}, provides a listing of
    the antenna names and their associated antenna numbers.  This is
    useful because antennas are generally specified by their antenna
    numbers.  (Procedure {\tt \tndx{ANTNUM}} in the {\tt VLBAUTIL} set
    allows you to translate station names into numbers.)
\Item {\tt \tndx{DTSUM}} produces a matrix showing the number
    of visibilities on each baseline for each scan allowing a check to
    be made that all baselines have been loaded.  It also tells you
    the data integration time.  {\tt DTSUM} also has a mode (triggered
    by setting {\tt APARM(1) = 1}) that will produce a useful matrix
    summary of your whole data set.  {\tt DTSUM} does not properly
    report the integration times when there are multiple integration
    times in the data set.  Verb {\tt \Tndx{GETITIME}} returns the
    integration time as {\tt INTTIME} but has the same problem with
    multiple integration times.
\xeen

%\vfill\eject
\Subsections{Spectral displays: {\tt POSSM}}{possm}

\todx{POSSM}
Your data file will probably contain a number of IFs, observed at
different frequencies, corresponding to the separate ``IF channels''
used during the observations.  Use {\tt IMHEAD} to find the number of
IF channels and the number of spectral channels per IF channel, or
examine the {\tt LISTR} or {\tt LISUN} output.  The reason that the data
must be stored in narrow spectral channels, even for continuum
applications, is that, in \Indx{VLBI}, the geometrical and propagation
errors affecting the data can be large enough to cause significant phase
changes across an IF channel bandwidth, preventing a coherent
integration over the full bandwidth.

The frequency structure of the data can be inspected using {\tt
\tndx{POSSM}}, which provides a plot of visibility data as a function
of frequency as integrated over a specified time interval.  Optionally,
data from up to nine baselines can be plotted on a single plot page.
Initially it may be interesting to view the frequency structure of
data on a bright calibrator source, as in the example below.  Because,
prior to calibration, the phases in each IF channel are likely to vary
rapidly with time, it is important to average data coherently only
over a short time interval.  In general, you will see phase slopes and
offsets affecting the data; these phase errors must be determined and
removed before the data can be averaged in frequency and/or time.  See
\Sec{phasecal} for more information and a sample plot.  There is a
procedure simplifying the use of {\tt POSSM}:
\dispt{RUN \tndx{VLBAUTIL} \CR}{to acquire the procedures; this should
           be done only once since they will be remembered.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
           input file.}
\dispt{SOURCES\qs '\qs' \CR}{to plot all sources.}
\dispt{TIMERANG\qs 0 \CR}{to plot all times.}
\dispt{SUBARRAY\qs 0 \CR}{to plot all subarrays.}
\dispt{REFANT\qs {\it n\/} \CR}{to plot the cross-power spectrum for
           baselines with antenna {\it n\/}.}
\dispt{STOKES\qs 'I' \CR}{to plot Stokes I\@.}
\dispt{GAINUSE\qs {\it CLin\/} \CR}{to apply {\tt CL} table {\it CLin}
           to the data before plotting.}
\dispt{DOTV\qs 1\CR}{to plot the data on the TV; -1 to make a plot
            file.}
\dispt{\Tndx{VLBACRPL} \CR}{to plot the data.}
\pd

To use {\tt POSSM} directly to display the visibility spectrum of a
source on the TV, use:\Iodx{VLBI}
\dispt{TASK\qs 'POSSM' ; INP \CR}{to review the inputs.}
\dispt{INDISK {\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
           input file.}
\dispt{SOURCES\qs 'OQ208', ' ' \CR} {to specify a single source name.}
\dispt{TIMER\qs 1 2 15 0 1 2 15 30 \CR} {to define a time range.}
\dispt{ANTENNAS\qs 8 ; BASELINE\qs 0 \CR} {to plot all baselines to
           antenna 8.}
\dispt{DOCAL\qs -1 \CR}{to plot the data without calibration.}
\dispt{BIF\qs 0 ; EIF\qs 0 ; BCHAN\qs 0 ; ECHAN\qs 0 \CR}{to include
           all IFs and spectral channels.}
\dispt{STOKES\qs 'HALF' \CR}{To plot RR and LL separately.}
\dispt{CODETYPE\qs' ' ; POLPLOT\qs ' ' \CR}{to plot amplitude and
           phase.}
\dispt{SOLINT\qs 0 \CR}{to average over the full time range.}
\displ{APARM\qs 1 , 1 , 0 , 0 , -180 , 180 , 0 , 0 , 3 , 0 \CR} {to
           control the plot: {\tt APARM(1)=1} to use vector averaging,
           {\tt APARM(2)=1} to use fixed scale plots, {\tt APARM(5)}
           and {\tt APARM(6)} to set phase range, {\tt APARM(9)=3} to
           plot all IFs and polarizations together in one diagram.}
\dispt{NPLOTS\qs 9 ; BPARM\qs 0 ; OUTTEXT\qs ' ' \CR} {to have 9 plots
           per page without division by ``channel 0'' and without
           writing the spectrum to a file.}
\dispt{DOTV\qs 1 \CR}{to plot on the TV, else create plot extension.}
\dispt{BADDISK 0 \CR}{to use all disks for scratch.}
\dispt{GO \CR}{to run the program.}
\dispe{Note that the amplitudes are totally uncalibrated at this stage
and are in units of ``correlation coefficients''; these will generally
appear on plots mislabeled as {\tt mJy} (representing multiples of
$10^{-3}$ in correlation coefficient).  {\tt POSSM} can produce text
output into the file given by {\tt OUTTEXT}\@.}

Sample {\tt POSSM} displays are given in \Rfig{VLBuncal},
\Rfig{VLBbeforeafter}, and \Rfig{sdPOSSM}\@.

Task {\tt \tndx{SHOUV}} with {\tt OPTYPE 'SPEC'} will display the data
from a number of channels on the printer with optional time averaging.

\Subsections{Time displays: {\tt VPLOT}, {\tt CLPLT}, and {\tt CAPLT}}{vplot}

The task {\tt \Tndx{VPLOT}} can be used to view the visibility data as
a function of time (or other variables).  Again, data from several
baselines can appear on one plot page.  Plots of amplitudes and phases
and several other quantities can be made, although, to view closure
phase and amplitude, you must use tasks {\tt \tndx{CLPLT}} and {\tt
\tndx{CAPLT}}\@.  Note that {\tt VPLOT} can average spectral channels
or plot them individually under control of {\tt AVGCHAN} and can plot
spectral channels and IFs in separate panels or all together under
control of {\tt CROWDED}\@.  Data points are plotted with a
user-selected {\tt SYMBOL} and may be connected by lines under control
of {\tt FACTOR}\@.  Calibration can be applied to the data before they
are plotted.  The data can be averaged in time and the max/min within
the interval plotted along with the average.  Also, if desired, a
model can be plotted against the data.  The model can either be
displayed at the times of the data samples or, with somewhat less
accuracy, continuously, even at times for which there are no
associated data or recorded \uv\ coordinate values.\Iodx{VLBI}

The following parameters will display uncalibrated amplitudes and
phases from a single spectral channel of a single IF channel for a
short scan on a bright calibrator:
\dispt{TASK\qs '\Tndx{VPLOT}' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs {\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
              input file.}
\dispt{CLR2NAME \CR}{to ensure no model is plotted.}
\dispt{SOURCES 'OQ208' ' \CR} {to specify the source name.}
\dispt{BIF\qs 4 \CR}{to give first included IF channel.}
\dispt{EIF\qs 4 \CR}{to give last included IF channel;, if {\tt EIF}
              $>$ {\tt BIF} then IFs are averaged.}
\dispt{BCHAN\qs 8 \CR}{to set the lowest spectral channel to include
              in average prior to plotting.}
\dispt{ECHAN\qs 8 \CR}{to set the highest spectral  channel to
              include in average prior to plotting; no averaging in
              this case.}
\dispt{TIMER 1 2 15 0 1 2 25 00 \CR}{to define a 10-minute time
              range.}
\dispt{DOCAL\qs -1 ; DOBAND\qs -1  \CR}{to apply no calibration
              tables or bandpass tables to data.}
\dispt{OPTYP\qs ' '}{to display cross-correlations; {\tt 'AUTO'}
              to get auto-correlations.}
\dispt{SOLINT \qs 0} {to do no time averaging of the data before
              plotting.}
\dispt{XINC\qs 1 \CR}{to plot every record.}
\dispt{BPARM\qs 0 , -1 \CR}{to set $x$-axis type ({\tt BPARM(1) = 0}
              plots time (Hrs, min, sec)), $y$-axis type ({\tt
              BPARM(2)= -1} plots both amplitude and phase), and to
              use self-scaling.  See {\us EXPLAIN VPLOT \CR} for
              other options.}
\dispt{NPLOT\qs 4 \CR}{to plot 4 baselines/page.}
\dispt{GO \CR}{to run the program.}
\dispe{An example {\tt VPLOT} output appears as \Rfig{VLBuncal}.  It
may be useful to make a plot of data ``weight'' versus time on the
autocorrelation data from each antenna (set {\tt BPARM(2)=16} and {\tt
OPTYP = 'AUTO'})\@.  The weight depends on the number of valid bits
correlated and is a good indication of tape playback quality.}

\subsections{{\tt EDITR}}

Another task which can display data as a function of time is {\tt
\tndx{EDITR}}\@.  This program is used primarily to edit data
interactively (see \Sec{editr}), but its interactive aspects (\ie\
allowing the user to ``zoom'' in on certain time periods) make it
useful for pure data inspection.  {\tt EDITR} now offers options
reminiscent of {\tt difmap}, the VLBI data reduction package from
CalTech.  In particular, the {\tt CROWDED} adverb allows displays of all
IFs and/or all polarizations at the same time (and color may be used to
separate them visually) and the {\tt FLAG QUICKLY} run-time option
allows fast sample deletion with only quick mouse clicks.  The new {\tt
CLIP EVERYTHING} option is paricularly efficient in deleting high
values.  The new coherence parameter (scalar average divided by vector
average minus one) offers interesting possibilities as well.  It is well
worth exploring the abilities of this powerful program.  Tasks {\tt
TVFLG} (\Sec{tvflg}), {\tt SPFLG} (\Sec{spflg}), and {\tt WIPER} are
also useful in this way.\iodx{editing}\iodx{flagging}

\subsections{{\tt SNPLT}}

Supplied with your \Indx{VLBI} data will be a number of important
tables used for calibration, and many more are generated as calibration
proceeds.  \Sec{vlbtables} summarizes the contents of each of these
\indx{tables}.  Two of the most important tables are the calibration
or {\tt CL} tables and the solution or {\tt SN} tables.

The task {\tt \tndx{SNPLT}} should be used periodically to inspect the
contents of the latest {\tt CL} and {\tt SN} tables.  There is a simplified
 procedure for making these plots:
\dispt{RUN \tndx{VLBAUTIL} \CR}{to acquire the procedures; this should
           be done only once since they will be remembered.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
           input file.}
\dispt{INEXT\qs 'CL' \CR}{to plot a {\tt CL} table.}
\dispt{INVERS\qs 0 \CR}{to plot the highest version.}
\dispt{SOURCES\qs '\qs' \CR}{to plot all sources.}
\dispt{TIMERANG\qs 0 \CR}{to plot all times.}
\dispt{STOKES\qs  '\qs' \CR}{to plot both R and L solutions.}
\dispt{SUBARRAY\qs 0 \CR}{to plot all subarrays.}
\dispt{OPTYPE\qs 'AMP' \CR}{to look at amplitudes; {\tt 'PHAS'}, {\tt
            'DELA'}, and {\tt 'RATE'} are other useful choices.}
\dispt{DOTV\qs 1\CR}{to plot the data on the TV; -1 to make a plot
            file.}
\dispt{VLBASNPL \CR}{to plot the data.}
\pd

Using {\tt SNPLT} directly, the example below plots the antenna-based
amplitude corrections stored in {\tt CL} table {\it m\/}.
\dispt{TASK\qs 'SNPLT' ; INP \CR}{to review the inputs.}
\dispt{INDISK {\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
            input file.}
\dispt{OPTYPE\qs 'AMP' \CR}{to plot amplitudes.}
\dispt{OPCODE\qs 'ALST' \CR}{to plot both polarizations in each plot;
            selected IFs are plotted separately.}
\dispt{INEXT\qs 'CL' ; INVER\qs {\it m\/}\CR}{to choose {\tt CL} table
            version.}
\dispt{DOBLANK 1 ; DOTV 1 \CR} {to plot on the TV screen including
            failed solutions; otherwise, create plot extension files.}
\dispt{NPLOTS\qs 5 \CR}{to plot 5 antennas/IFs per page.}
\dispt{DO3COL\qs 2 \CR}{to separate the calibration sources by color.}
\dispt{GO \CR}{to run the program.}
\dispe{{\tt SNPLT} can also be used to plot quantities from other
tables generated by the calibration process including the contents of
 {\tt TY} (``system temperature''), and {\tt PC} (``phase-cal'')
tables.  {\tt OPTYPE = 'MULT'} allows you to compare values of two or
more parameters, plotting them at the same time in separate panels.
Task {\tt SNIFS} is similar and may be used to compare values
across IFs.  {\tt \tndx{SNBPL}} is similar to {\tt SNPLT}, but plots
calibartion parameters on a baseline basis.  Unstable phases may be
stable on some baselines, but not others.  The antenna-based plots of
{\tt SNPLT} may not differentiate these adequately.}

\Subsections{{\tt COHER}}{coher}

The task {\tt \Tndx{COHER}} can be used to determine the coherence
time in a \uv\ data set broken down both in time and by antenna and
baseline. The coherence time is estimated by comparing vector and
scalar averaged amplitudes over increasing time averaging intervals.
Averaging is not performed over source scan boundaries. The coherence
time is defined as the averaging interval over which the ratio of
vector and scalar amplitudes falls below a pre-assigned level. This
can be set under user control. In addition, data that fall below a
specified signal-to-noise ratio can be excluded from the coherence
time estimates. Provision is made for selection by source name, time
range, IF channel, antenna and frequency ID, and the ability to
average over a subset of individual frequency channels. The input
parameters to task {\tt COHER} take the form:
\dispt{TASK\qs 'COHER' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
              \uv\ input file.}
\dispt{APARM\qs 0 \CR}{SNR cutoff 5; vector to scalar cutoff 0.8.}
\dispt{TIMERANG\qs 0, 10, 5, 0, 0, 10, 15, 0 \CR}{time range
              selection.}
\dispt{BIF\qs 5 ; BCHAN\qs 1 ; ECHAN\qs 8 \CR}{IF and channel
               selection.}
\dispt{SOURCES\qs 'DA193' , '\qs ' \CR}{source selection.}
\dispt{FREQID\qs 1 \CR}{Frequency ID selection.}
\dispt{GO \CR}{to run the program.}
\dispe{Be warned that {\tt COHER} can take quite a long time to run.
A simpler, though less rigorously correct method for determining
coherence intervals is to examine the data on different baselines
using {\tt EDITR}\@.\Iodx{VLBI}}

\Subsections{{\tt FRPLT}}{frplt}

A preliminary examination of the coherence of individual scans or time
segments in the data can also be performed using task {\tt
\Tndx{FRPLT}}, which allows time series or fringe-rate spectra to be
plotted for one or more baselines and time intervals. This task allows
data to be selected by the usual criteria, including time range,
source name, and frequency parameters, amongst others, and will then
plot the individual time series in amplitude and phase or the
associated fringe-rate spectrum.  Provision is made for averaging over
frequency channels within each IF, for varying degrees of padding in
the FFT, and for division by the pseudo-continuum average ``channel
zero'' before plotting. Typical input parameters to {\tt FRPLT} are:
\dispt{TASK\qs '\Tndx{FRPLT}' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
         input file.}
\dispt{SRCNAME\qs 'DA193' \CR}{to select a source.}
\dispt{TIMERANG\qs 0, 10, 5, 0, 0, 10, 15, 0 \CR}{to select a time
         range, strongly recommended.}
\dispt{SOLINT\qs 2 \CR}{to plot fringe-rate spectra for every 2-minute
         interval in {\tt TIMERANG.}}
\dispt{NPLOTS\qs 6 \CR}{to do 6 plots per page.}
\dispt{STOKES\qs 'LL' \CR}{to select a single Stokes.}
\dispt{BIF\qs 1 ; EIF\qs 0 \CR}{to select the IFs included.}
\dispt{BCHAN\qs 3 ; ECHAN\qs 12 \CR}{to select the range of frequency
         channels averaged within each IF.}
\dispt{ANTENNAS\qs 3, 4 \CR}{to select baseline 3-4, 3-5, and 4-5.}
\dispt{BASELINE\qs 4, 5 \CR}{to select baseline(s) plotted in the
         familiar way.}
\dispt{DOCAL\qs -1 ; DOPOL\qs -1 \CR}{to apply no continuum
         calibration.}
\dispt{DOBAND\qs -1 \CR}{to do no bandpass calibration.}
\dispt{APARM(1)\qs 1 ; APARM(2)\qs 0 \CR}{integration time 1 sec;
               self-scale the plots.}
\dispt{APARM(7)\qs 0 \CR}{plot fringe-rate spectra with no
               padding.}
\dispt{BPARM\qs 0 \CR}{to do no division by ``channel zero.''}
\dispt{DOTV\qs 1 \CR}{to plot directly on the TV device.}
\dispt{GO \CR}{to run the program.}
\dispe{The underlying time series in amplitude and phase can be
plotted by setting {\tt APARM(7)=1}; otherwise the fringe-rate spectrum
is plotted.  Note that the baseline(s) shown are selected with {\tt
ANTENNAS} and {\tt BASELINE} in the usual way and a time
range must be selected with {\tt TIMERANG}\@.  {\tt APARM(1)} sets the
integration time to be used before doing the FFT over the selected
time range.  {\tt SOLINT} may be used to break the time range into
intervals.  Separate plots are produced for each IF, baseline, and
time interval.}

%\vfill\eject
\Sects{Calibration strategy}{vlbcalib}

If you have multiple frequency IDs in your data, you may want to
separate the data for different {\tt FREQID} before performing any
calibration.  Use {\tt UVCOP} to do this and take advantage of the
opportunity to delete data flagged by the correlator with {\tt
FLAGVER=1}\@.  You no longer need to re-run {\tt INDXR} on the
output files.  Again there is a procedure to do this for you:
\dispt{RUN \tndx{VLBAUTIL} \CR}{to acquire the procedures; this should
           be done only once since they will be remembered.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
             input file.}
\dispt{CLINT\qs $\triangle t$ \CR}{to set the {\tt CL} table interval
           to $\triangle t$ minutes (see discussion above in
           \Sec{clint})\@.}
\dispt{INP\qs VLBAFIX \CR}{to review the inputs.}
\dispt{\Tndx{VLBAFIX} \CR}{to run the procedure.}
\dispe{{\tt VLBAFIX} will normally be run after loading the data.}

We can now begin the process of calibrating \Indx{VLBI} data.  As the
\indx{calibration} process proceeds, both amplitude and phase
corrections are incorporated into the {\tt CL} tables. VLBI correlator
output is in terms of dimensionless ``correlation coefficients.''  To
convert to Janskys, large amplitude correction factors have to be
entered into the {\tt CL} tables.  In addition, phase correction
factors must be entered into the {\tt CL} table to correct for phase
offsets and ramps as functions of frequency and time.  These
corrections must be made so that the data can be averaged over
frequency and time without loss of coherence.  The process of
determining the phase corrections is known as ``{\it
fringe-fitting\/}'' in VLBI; see \Sec{phasecal}.

In order to calibrate the absolute phase of their data, VLBI users
use either ``phase-referencing'' or ``self-calibration''.  If the
self-calibration route is chosen, then the phase derivatives
with respect to time and frequency are calibrated and the absolute
phases are normally left uncalibrated.  Then self-calibration
methods are then used to generate images (see \Sec{vlbimag}).  For
phase-referencing, an absolute-phase calibration is done using an
external calibrator.  Phase-referencing in VLBI is similar to, but
slightly more complicated than, phase calibration on the VLA\@.  In
general terms, phase-referencing VLBI data is accomplished by
similar methods as used for VLA data in \AIPS; be sure to read
\Sec{vlbpref} and \Sec{phaseref} for details on how to calibrate
phase-referenced observations.

For astrometric data reduction methods in \AIPS\, the reader is
referred to the guide to \AIPS\ astrometric data reduction available
from within \AIPS\ by typing {\tt HELP ASTROMET}\@.

Optimum fringe-fitting results are obtained if amplitudes are
calibrated first, since, in this case, the data will be weighted
appropriately (the \AIPS\ task {\tt FIXWT} may be used to adjust the
weights in the data to reflect the scatter of the actual data).  We
therefore describe the process of amplitude calibration first in
\Sec{vlbcamp}.  Then, in \Sec{phasecal}, we describe the calibration
of residual phase using ``fringe-fitting'' techniques.  Note however,
that for observations of strong sources or observations using only
VLBA antennas (where, particularly at centimeter wavelengths, the
sensitivities on all baselines are roughly the same), the order of the
two calibration steps may be reversed.

\subsections{Incremental calibration philosophy}

The general strategy adopted by \AIPS\ for \indx{calibration} is,
starting with the lowest version of the {\tt CL} table, to incorporate
step-by-step amplitude and phase corrections for a number of different
effects.  At each stage either an existing {\tt CL} table is modified
or a new version is created from a lower version by a task which
applies a certain type of calibration.  Note that the actual
visibilities are not changed until you are satisfied that you have the
best possible calibration file; at this point the task {\tt SPLIT} can
be used to apply the calibration information of the best {\tt CL}
table to the data.  However at each point along the way the effect of
a particular {\tt CL} table on the data can be viewed using {\tt
\tndx{POSSM}} or {\tt \tndx{VPLOT}} by setting {\tt DOCAL=1} and {\tt
GAINUSE} equal to the chosen {\tt CL} table.  Since many {\tt CL}
tables may be produced in the course of calibrating a \Indx{VLBI} data
set it is important to keep a note of which effects are included in
each one.  Ideally one should delete {\tt CL} tables which are judged
incorrect and ensure that the accumulated corrections lie in the
highest numbered {\tt CL} table. It is suggested that version 1 of
the {\tt CL} table, as produced by {\tt FITLD}, be copied to {\tt
CL} version 2 using {\tt TACOP} before any calibration is begun, and
that {\tt CL} version 2 be used as the starting point in the
calibration sequence. An effort is made within \AIPS\ to insure that
{\tt CL} version 1 is not deleted inadvertently. If this does occur
however it can be re-generated using task {\tt INDXR} (described in
\Sec{vlbINDXR}).  (Note that {\tt INDXR} cannot re-generate some types
of information, \eg\ the phase-cals inserted by the MKIII correlator
so that it is important to try to preserve the first {\tt CL} table.)
The task {\tt \tndx{TASAV}} can be used to back up your tables by
copying all of them to a dummy file containing no data.  This can be
used to save a ``snapshot'' of the tables at various points in your
data processing for insurance purposes.  The tables can be copied back
into your data file if necessary using {\tt TACOP}\@.

You can also use the verb {\tt HINOTE} to add comments into the
history file.  This can be very useful for check-pointing progress
during calibration.

When you are ready to apply the calibrations, you run either {\tt
SPLIT} or {\tt SPLAT}.  Both tasks can average data in the spectral
domain if appropriate.  {\tt SPLAT} can also time-average the data and
produces multi-source data sets on output if requested.

\Subsubsections{Smoothing and applying corrections in {\tt SN} and
    {\tt CL} tables}{vlbapply}
\todx{CLCAL}

The various stages of calibration described below produce {\tt SN}
tables which are then used to create {\tt CL} tables using {\tt
CLCAL}\@.  The ancillary tasks {\tt SNCOR}, {\tt SNSMO}, {\tt SNEDT},
and {\tt CLCOR} can be used to modify the {\tt SN} and {\tt CL} tables
directly.  It is important to choose the proper methods of
interpolation in these tasks.

{\tt SN} tables can be smoothed using tasks {\tt \tndx{SNEDT}} and
{\tt \tndx{SNSMO}} before being used to update {\tt CL} tables using
{\tt CLCAL}\@.\iodx{calibration}  {\tt SNSMO} uses superior smoothing
methods to those available in {\tt CLCAL} and should always be used to
do any smoothing of VLBI data, \ie\ data with non-zero delays and
rates.  The adverb {\tt DOBLANK} now controls which data are actually
altered by the smoothing; use it carefully.

Typical inputs for {\tt SNSMO} would be:
\dispt{TASK\qs 'SNSMO ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs {\it n\/} ; GETN {\it ctn\/} \CR}{to specify the
             input file.}
\dispt{SOURCES\qs ' ' \CR}{to modify the solutions for all sources.}
\dispt{SELBAND\qs -1; SELFREQ\qs -1; FREQID\qs 0\CR}{to do all
             frequency IDs.}
\dispt{BIF\qs 0; EIF\qs 0\CR}{to include all IFs.}
\dispt{TIMERANG\qs 0; ANTENNAS\qs 0\CR}{to include all times and
             antennas.}
\dispt{SUBARRAY\qs 0\CR}{to select the first subarray; NB, {\tt SNSMO}
             works only on one subarray at a time.}
\dispt{SAMPTYPE\qs 'MWF'\CR}{to use the median window filter method.}
\dispt{SMOTYPE\qs 'AMPL'\CR}{to smooth amplitudes only.}
\dispt{BPARM\qs 0.5,0 \CR}{to use a 30-minute filter time for amplitude.}
\dispt{DOBLANK\qs 1 \CR}{to replace blanked values with interpolated
             values {\it only}.}
\dispt{CPARM\qs 0.5, 0, 0, 0, 0, 0.02, 0\CR}{to set ranges of allowed values.}
\dispt{INVER\qs {\it snin\/} ; OUTVER\qs {\it snout\/}\CR}{to read in the
             {\tt SN} table version {\it snin\/} and to write {\tt SN}
             table version {\it snout\/} (which should be a new table).}
\dispt{REFANT\qs 0 ; BADDISK\qs 0 \CR}{to keep the current reference
             antenna and to allow all disks to be used for scratch
             files.}
\dispt{INP \CR}{to check the inputs.}
\dispt{GO \CR}{to run the task.}
\pd

Typical inputs for {\tt CLCAL} would be:\Iodx{VLBI}
\dispt{TASK\qs 'CLCAL' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs {\it n\/} ; GETN {\it ctn\/} \CR}{to specify the
              input file.}
\dispt{CALSOUR\qs ' ' \CR}{to use all corrections in the SN table.}
\dispt{SOURCE\qs  ' ' \CR}{to apply corrections to all sources.}
\dispt{OPCODE  'CALP' \CR}{to apply {\tt SN} tables to a {\tt CL}
               table.}
\dispt{INTERPOL \qs' ' \CR}{to use linear vector interpolation ({\tt
               '2PT'})\@.}
\dispt{SAMPTYPE\qs '\qs'\CR}{to do no further smoothing of the merged
               {\tt SN} tables..}
\dispt{SNVER\qs {\it snin\/} ; INVERS\qs 0\CR}{to select the one {\tt
              SN} table containing solutions to be interpolated.}
\dispt{GAINVER\qs {\it clin\/} \CR}{to select the {\tt CL} version to
               which solutions are to be applied.}
\dispt{GAINUSE\qs {\it clout\/} \CR}{to select the output {\tt CL} version,
               containing updated \indx{calibration} information.}
\dispt{REFANT\qs 0 ; BADDISK\qs 0 \CR}{to try to use use a single
               reference antenna if possible during all steps of
               calibration.}
\dispt{INP \CR}{to check the inputs.}
\dispt{GO \CR}{to run the task.}
\dispe{Note well that {\tt SNVER=0} means here to combine the
solutions from all {\tt SN} tables, {\tt GAINVER=0} means to apply the
solutions to the highest numbered {\tt CL} table and {\tt GAINUSE=0}
means to write a new {\tt CL} table.  If two {\tt SN} tables contain
two similar attempts at finding corrections and {\tt SNVER=0} then,
effectively, {\tt CLCAL} will be inconsistent in applying the
solutions from these two tables.  Basically, {\tt CLCAL} simply
concatenates all {\tt SN} tables and then merges
apparently identical records (same time and antenna) to eliminate
blanked solutions and to complain about otherwise non-identical
solutions.}

The parameters {\tt INTERPOL} and {\tt SAMPTYPE} allow the user to
choose between several different methods of smoothing the {\tt SN}
files followed by interpolation to the times in the {\tt CL} table.
Use {\us EXPLAIN CLCAL \CR}  to view all the options.  The default
interpolation option is {\tt INTERPOL = '2PT'}, in which the {\tt SN}
table is linearly interpolated between the measurements in the {\tt SN}
table.  Using {\tt SAMPTYPE = 'BOX'} causes the {\tt SN} table to be
smoothed with a boxcar function before being interpolated onto the
{\tt CL} table.  The smoothing times for delay, rate etc.~are
specified in parameter {\tt BPARM}\@.  {\tt DOBLANK} controls how
both failed and good solutions are handled when smoothing.  {\tt
DOBLANK} $\ge 0$ replaces failed solutions with smoothed ones, while
{\tt DOBLANK} $\le 0$ replaces good solutions with smoothed ones.
However it is recommended that {\tt SN} smoothing be done prior to
{\tt CLCAL} using task {\tt \tndx{SNSMO}}\@.  When smoothing delays,
use the new {\tt SMOTYPE = 'VLDE'} method whenever the IFs have been
grouped to find single solutions ({\tt APARM(5)}$ > 0$ in {\tt FRING})
across multiple IFs.  Be sure to set {\tt NPIECE} to indicate how many
groups of IFs were used in {\tt FRING}, \eg\ 1 for a multi-band delay,
2 for a delay for IFs 1 --- $Nif / 2$ amd a delay for IFs $Nif/2+1$
--- $Nif$.

With good quality data, the {\tt INTERPOL = 'AMBG'} option should work
well.  Note, however, that this option uses the {\tt SN} solutions
immediately before and after a {\tt CL} entry to make the
interpolation and it uses any {\tt SN} solution found for any source
specified in {\tt CALSOUR}\@.  Therefore, if {\tt CALSOUR} is left
blank (allowing all sources) and delay and rate solutions were
significantly different for different sources, then inappropriate
solutions may be applied for a few minutes before or after a source
change.

One way of avoiding this problem is to run {\tt CLCAL} with {\tt
INTERPOL = 'AMBG'} several times, once for each source, setting both
{\tt SOURCES} and {\tt CALSOUR} to the name of the desired source with
all other inputs remaining unchanged.  Another way of avoiding the
problem is to use {\tt INTERPOL = 'SELF'}\@.  In this option, only
solutions found on a given source are used to calibrate that source
and the {\tt SN} table entries closest in time for that source are
used with interpolation.  This is not as good as doing multiple
runs with the {\tt INTERPOL = 'AMBG'} option because there can be
jumps in phase at points equidistant from two {\tt SN} table
entries.\Iodx{VLBI}

If there are bad {\tt SN} solutions, {\tt INTERPOL = 'POLY'} is used
to fit a polynomial to the rate solutions and then integrate this
polynomial to determine the phase corrections to be entered into the
{\tt CL} table.

A final note on {\tt \tndx{CLCAL}}.  It is sometimes the case that
{\it a priori\/} information is not available for all antennas in a
single format.  For example, you may have system temperature
information for VLBA antennas in your {\tt SN} version 2 table and for
non-VLBA antennas in {\tt SN} version 3.  You can merge this
information by running {\tt CLCAL} twice with the same {\tt GAINVER}
and {\tt GAINUSE}; each time you should explicitly set the {\tt SN}
version number and list the antennas to be processed using the {\tt
ANTENNAS} adverb.  If you leave the {\tt ANTENNAS} adverb blank,  the
final {\tt CL} table will contain information only for antennas
present in the last {\tt SN} table processed.  Note that you must use
{\tt OPCODE = 'CALI'} when building up a {\tt CL} table in pieces.
\iodx{calibration}

\Subsubsections{Running {\tt CLCAL} for phase referencing
observations}{vlbpref}

In particular, this example illustrates how to set the inputs for {\tt
CLCAL} for the specific case when phase corrections determined for the
cal source 'J1636-16' are to be transferred to the target source
'P1643-12' in a \indx{phase referencing} experiment:
\dispt{TASK\qs 'CLCAL' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs {\it n\/} ; GETN {\it ctn\/} \CR}{to specify the
             input file.}
\dispt{CALSOUR\qs 'J1636-16', ' ' \CR}{to use the corrections
             determined for the cal source.}
\dispt{SOURCES\qs  'J1636-16', 'P1643-12', ' ' \CR}{to apply
             corrections to both the cal source and the target
             source.}
\dispt{OPCODE  'CALP' \CR}{to apply {\tt SN} tables to a {\tt CL}
             table passing all data.}
\dispt{INTERPOL \qs'AMBG' \CR}{to use linear vector interpolation with
             no {\tt SN} table smoothing and simple phase ambiguity
             removal.  See above for more discussion of {\tt
             INTERPOL}\@.}
\dispt{SAMPTYPE \qs ' '; BPARM \qs 0 \CR}{to clear smoothing
             parameters.}
\dispt{SNVER\qs {\it snin\/} \CR}{to select the {\tt SN} table
             containing solutions to be interpolated.}
\dispt{GAINVER\qs {\it clin\/} \CR}{to select the {\tt CL} version to
             which solutions are to be applied.}
\dispt{GAINUSE\qs {\it clout\/} \CR}{to select the output {\tt CL}
             version, containing updated \indx{calibration} information.}
\dispt{REFANT\qs 5 ; BADDISK\qs 0 \CR}{Use a single reference antenna
              if at all possible during all steps of calibration.}
\dispt{INP \CR}{to check the inputs.}
\dispt{GO \CR}{to run the task.}
\dispe{It's a good idea to always apply the calibration information to both
the cal and target sources when running {\tt CLCAL} for
phase-referencing observations.  This allows you to monitor the cal
source data to check the progress of the phase calibration procedure.}
\pd

\Subsections{Processing observing log and calibration
information}{vlblogs}

As of 1 April 1999, the VLBA correlator provides calibration transfer
information, as described in \Sec{caltransfer} for VLBA antennas.
Experiments correlated after November 2003 also have full calibration
transfer for the VLA, the GBT, Arecibo and the Bonn 100m.
Consequently, {\bf you can skip \Sec{vlblogs} entirely} unless you
have data from non-VLBA telescopes (\eg\ the VLA before November 2003,
Space, other European telescope) or other correlators or you wish to
process the log files manually for other reasons.\Iodx{VLBI}

This section describes the processing of external calibration
information, as supplied in ASCII log files.  The information that may
be used by \AIPS\ includes \Tsys\ or related total power measurements,
edit flags as written by the tracking stations or on-line monitor
control system, weather information, and pulse-calibration data. These
external data can be read into \AIPS\ by tasks {\tt ANTAB}, {\tt
UVFLG}, {\tt APCAL}, and {\tt PCLOD} respectively, as described in
\Sec{antabformat}, \Sec{vlbedit}, \Sec{vlbcamp} and \Sec{pccor}\@.

You should have received information about where to obtain your
calibration data.  VLBA calibration log files may be obtained by ftp
as described below.  Similar calibration files for other participating
antennas and VSOP should be obtained from the appropriate sites.

\Subsubsections{Automatic formatting of VLBA and VLBA-like log
files}{vlbvlog}

For \Indx{VLBA} antennas, the external calibration file for a given
experiment can be downloaded from\\
\centerline{{\tt https://www.vlba.nrao.edu/astro/VOBS/astronomy/{\it
       mmmyy\/}/{\it xxxxx\/}cal.vlba.gz}}\\
where {\it mmmyy} is the month and year (\eg\ {\tt aug03}) and {\it
xxxxx} is the project code (\eg\ {\tt bz199}).  The calibration file
is named as above and is in GNU-zipped format.  Gain curve information
can be obtained from the same web site in the {\tt astronomy}
directory (\ie\ two directories up from the project directory).  The
gain curve should be concatenated to the external calibration file.
\Iodx{VLBI}

The external \indx{calibration} file, if suitably close to the
standard \Indx{VLBA} format, concatenated with the gain curve file,
can be automatically subdivided and re-formatted to comply with \AIPS\
requirements using task {\tt \tndx{VLOG}}\@.  Typical inputs would be:
\dispt{TASK\qs 'VLOG' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
            {\tt FITLD} output file.}
\dispt{SUBARRAY\qs 1 \CR}{to select the required subarray.}
\dispt{CALIN\qs 'FITS:bz199cal.vlba \CR}{to specify the input
            external calibration file.}
\dispt{OUTFILE\qs 'FITS:BZ199' \CR}{to define the directory and prefix
            for the output files.}
\dispt{FQTOL\qs 1000 \CR}{to set the tolerance for frequency match in
            kHz; one channel width is recommended.}
\dispt{PRTLEV\qs 0 \CR}{to limit output; in particular to avoid
            echoing the calibration file to the screen.}
\dispt{GO \CR}{to run the program.}
\pd

A sequence of output text files will be created in the specified ({\tt
\$FITS} here) directory named {\tt BZ199.*} with suffixes:

\xben
\Item {\tt .TSYS:} \Tsys\ calibration data, including gain
curves, suitable for direct use by {\tt ANTAB}\@.  An {\tt INDEX}
record is constructed for each frequency ID if possible. If no match
can be made to the FQ data, a warning message is printed and the {\tt
INDEX} keyword is omitted; the {\tt INDEX} keyword must then be
inserted by hand (see the HELP file for {\tt ANTAB}).  Gain curve
entries for the frequency and time range in the \uv\ data are copied
to this output file.  It is recommended to insert \Tsys\ values
at the end of scans immediately before source changes to avoid
interpolation problems for sources of greatly differing flux density
or use {\tt INTERPOL = 'SELF'} in {\tt CLCAL}\@.  Occasionally
spurious data from previous observing runs or system start-up files
will end up in the {\tt .TSYS} file and must be edited out by hand.

\Item {\tt .FLAG:} Flag data, suitable for direct use by {\tt
UVFLG}\@. In the older format ``antennas=vlba\_xx'' the appropriate
antenna and day numbers are inserted.

\Item {\tt .WX:} Weather data, as used by {\tt APCAL} if performing an
opacity solution. This file is altered to conform with {\tt APCAL}
requirements (\eg\ {\tt WEATHER} keyword) and lines with bad entries
(*) are commented out.

\Item {\tt .PCAL:} Pulse-calibration data, for input to {\tt
PCLOD}\@. No editing is performed.
\xeen

Files with suffixes {\tt .SCAN} and {\tt .MKIII} contain scan
summaries and MkIII information and are for information purposes only.

\subsubsections{Manual formatting of log files}

Partitioning of the \indx{calibration} file can and must be done by
hand if the calibration file format is sufficiently distinct from the
standard \Indx{VLBA} format or, possibly, if it contains multiple
frequency bands.  If your observation used non-VLBA antennas, you will
need to edit the calibration text file manually to add any log
information supplied for these antennas.  The necessary steps are as
follows:

Extract the flagging and \Tsys\  information from the
calibration text file.  You will also need to append gain curves to
the \Tsys\ file.  Try {\tt EXPLAIN ANTAB} to see an example
file in the proper format.  The parameter {\tt TIMEOFF} should be set
to zero for each station since both flag information and data are
stored with UTC times.  The keyword {\tt DTIMRANG} is also supported
which pads each flagged time interval to insure that even very short
flag intervals are applied.

While older VLBA format \indx{calibration} files were supplied with
the {\tt ANTENNA} keyword, newer VLBA format calibration files are
supplied with the {\tt ANT\_NAME} keyword.  In the former case, the
file should be edited to insert the antenna numbers as listed in the
{\tt AN} table (use {\tt PRTAN} on your \AIPS\ file to find these) and
the absolute day numbers must be replaced by relative day numbers with
respect to the \AIPS\ reference date.  In the latter case, no
adjustments to either day numbers or antenna numbers are necessary.

\Subsubsections{Loading calibration log information}{antabformat}

The \indx{calibration} information in the external text files such as
\Tsys\ and gain curve measurements are read into {\tt TY} and
{\tt GC} tables using {\tt \tndx{ANTAB}}\@.  These tables are then
used by {\tt APCAL} to generate an amplitude solution ({\tt SN})
table, allowing an optional solution for atmospheric opacity.  The
user is advised to read the {\tt ANTAB} help file closely and check
the syntax of the text file carefully.

The {\tt INDEX} keyword is used to assign the tabulated \Tsys\
data to individual \AIPS\ IF channels and polarizations. Up-to-date
information on the usage of the {\tt INDEX} keyword may be found by
typing {\tt EXPLAIN ANTAB}\@.  Be careful to match up the proper
polarization labels for the tabulated \Tsys\ information. The
frequency and polarization association for each IF channel in the
\AIPS\ file can be compared (use {\tt LISTR} with {\tt OPTYPE =
'SCAN'} or {\tt LISUN}) with that at the head of the calibration text
file.

The {\tt CONTROL} group at the head of the calibration file is used
only to specify a default index mapping.  If the IF channel orders in
the calibration file and the $uv$ file are identical it is not
required.\Iodx{VLBI}

Source flux densities are not specified in the {\tt ANTAB} input file.
If source flux densities are required by {\tt APCAL}, the source ({\tt
SU}) table will be searched.  Use {\tt SETJY} to insert flux densities
if necessary.

The parameter {\tt TIMEOFF} in the input file adds a time offset to
the all entries. Non-VLBA stations sometimes measure the system
temperature between, rather than during, scans causing {\tt ANTAB} to
be unable to match the measurements with the source and frequency
ID\@.  The {\tt ANTAB} input parameter {\tt OFFSET} serves the same
purpose, but is more successful since the scan times are expanded at
both ends.

{\tt ANTAB} permits specification of IF-dependent and tabulated gains;
the format description may be found by typing {\tt EXPLAIN ANTAB}\@.

{\tt ANTAB} can be run multiple times to append to the same {\tt TY}
and {\tt GC} tables. Also, calibration files from separate antennas
(\eg\ VLA) which have \Tsys\ data tabulated in a different
format can be concatenated and processed in one run. In this case the
{\tt INDEX} keyword must be specified for each antenna to fix the data
format.

Note that {\tt ANTAB} will (usually) ignore calibration data for which
there are no corresponding $uv$ data (see the help file for {\tt
ANTAB})\@.  There is one exception however: calibration data for an
antenna that does not appear in the {\tt AN} table will cause {\tt
ANTAB} to fail.  If {\tt ANTAB} quits under such circumstances, you
have two choices.  You can edit the calibration text file, removing
all reference to the missing antennas; or you can use the input adverb
{\tt SPARM} to specify explicitly the names of antennas for which
there are calibration data, but which do not appear in the {\tt AN}
table.

{\it *** The use of {\tt SPARM} is no substitute for careful
inspection of the calibration text files. ***}

Having created the input text file, typical inputs for {\tt
\Tndx{ANTAB}} would be:
\dispt{TASK\qs 'ANTAB' ; INP \CR}{to review the inputs.}
\dispt{INDISK {\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
           input file.}
\dispt{CALIN\qs 'MYVLB:BC25CAL.VLBA' \CR}{to specify the text file.}
\dispt{SUBARRAY\qs 1 \CR}{to select subarray one.}
\dispt{TYVER\qs 0 ; GCVER\qs 0 \CR}{to create new {\tt TY} and {\tt
           GC} tables.}
\dispt{BLVER\qs 0 \CR}{to create new {\tt BL} table for any specified
           baseline factors.}
\dispt{PRTLEV\qs 1 \CR}{to select print level.}
\dispt{GO \CR}{to run the program.}
\dispe{{\tt PRTLEV = 2} will echo the \indx{calibration} file as it is
processed, which can be useful in locating format errors.}

\Subsubsections{Generating VLA amplitude calibration with {\tt VLAMP}}{vlamp}

Before February 2013, the \indx{VLA}'s {\it a priori} calibration was
done with calibration files, named {\tt{\it xxxxx\/}cal.y.gz} (stored
in gzipped format).  These were obtained from the same server and disk
directory as for VLBA files.  This VLA file started with an
explanatory preamble, including minor editing instructions.  See
\Sec{vlba+vla} for more detailed instructions.

After February 2013 and the advent of the phased-EVLA, either an {\tt
ANTAB} style file was provided to the observer or the calibration
information is in the data file.  This calibration information is
generated using the EVLA switched power ({\tt SY} table, see
\Sec{tyapl}), the known gain curve ({\tt GC} table), and the first
{\tt CL} table using the task {\tt \Tndx{VLAMP}}\@.  Sometimes there
are problems with the values in the {\tt SY}, {\tt GC}, and/or {\tt
CL} tables and the observer might want to recreate the amplitude
calibration of the phased-EVLA after editing one or more of them.  To
do this the phased-EVLA only data (not the VLBI data) must be loaded
into \AIPS\ with {\tt BDF2AIPS}, see \Sec{BDF2aips}.  Then the {\tt
SY} and/or {\tt GC} tables can be edited.  For instructions on how to
edit or smooth the {\tt SY} table see \Sec{tyapl}.  Then run {\tt
VLAMP}, which will create an output text file that can be loaded into
the VLBI data with {\tt ANTAB}\@.  Typical inputs for {\tt
\Tndx{VLAMP}} would be:
\dispt{TASK\qs 'VLAMP' ; INP \CR}{to review the inputs.}
\dispt{INDISK {\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
          input file.}
\dispt{FLAGVER\qs 1 \CR}{to apply flags to the input tables.}
\dispt{INVER\qs 1 \CR}{to specify the SY table.}
\dispt{GAINVER\qs 1 \CR}{to specify the CL table.}
\dispt{IN2VERS\qs 1 \CR}{to specify the GC table. }
\dispt{VPARM\qs 5 6 11 12 \CR}{to select the EVLA spectral windows
          used by the VLBA.}
\dispt{OUTTEXT\qs '{\it filename\/}' \CR}{to specify the name of the
          output text {\it filename\/}.}
\dispt{GO \CR}{to run the program.\Iodx{VLBI}}

The {\tt RUN} file and procedure named {\tt DOVLAMP} can be used to
run the full process, reading the data into \AIPS\ with {\tt
BDF2AIPS}, smoothing and applying the {\tt SY} tables with {\tt TYSMO}
and {\tt TYAPL}, correcting standard calibration source amplitudes
with special usage of {\tt CALIB} and {\tt CLCAL}, and finally running
{\tt VLAMP} to produce the needed file for {\tt ANTAB}\@.

\Subsections{Data editing}{vlbedit}

Before proceeding to calibrate, you should first flag any obviously
bad data.  In summary, initial editing is based on the flagging
information supplied by the on-line antenna monitor systems, which is
applied using {\tt UVFLG}\@.  This information may be extracted to a
{\tt .FLAG} file as outlined in the previous section or subsequent
editing based on the station report logs, or elevation limits can also
be performed using {\tt UVFLG}\@.  Finally, graphical editing tasks
such as {\tt EDITR} and {\tt IBLED} may be used for interactive
baseline-based \indx{editing}.  In both single- and multi-source data
formats, \indx{flagging} information is stored in the {\tt FG} table
instead of being used to discard data directly.  One may also undo a
flag operation using {\tt OPCODE}s {\tt 'UFLG'}, {\tt 'REAS'}, and
{\tt 'WILD'} in {\tt UVFLG}\@.  Note that this operation works {\it
only} when the operation being undone is in the current flag table.
(Note that many tasks delete fully flagged data when copying a data
set.)
\Iodx{VLBI}

To edit \uv\ data by reading a text file listing periods of known
errors (\eg\ the {\tt .FLAG} text file created by {\tt VLOG}) run
{\tt UVFLG} with the following inputs:
\dispt{TASK\qs 'UVFLG' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
              input file.}
\dispt{SOURCES\qs '' \CR}{to flag all sources, which is usually
              desired.}
\dispt{SUBARRAY\qs 0 \CR}{to select the required subarray, all in this
              case.}
\dispt{FREQID\qs -1 \CR}{to flag all frequency IDs.}
\dispt{OUTFGVER\qs 2 \CR}{to specify the output flag table; use 2 {\it
              only\/} if you copied {\tt FLAGVER} 1 to 2 as suggested
              in \Sec{caltransfer}.}
\dispt{INTEXT\qs 'MYVLB:BC25CAL.FLAG' \CR}{to specify the input text
              file.}
\dispt{GO \CR}{to run the program.}
\dispe{This will generate a {\tt FG} table with entries read from {\tt
\$MYVLB:BC25CAL.FLAG}\@.}

To edit \uv\ data based on elevation limits, {\tt UVFLG} can be used
with input parameters:
\dispt{TASK\qs 'UVFLG' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
              input file.}
\dispt{SOURCES\qs 'DA913' , ' ' \CR}{to select one source.}
\dispt{SUBARRAY\qs 1 \CR}{to select subarray one.}
\dispt{ANTENNAS\qs 3, 4, 5, 8 \CR}{to flag only certain antennas.}
\dispt{APARM\qs 0, 0, 0, 0, 10 \CR}{to flag data between elevations 0
               and 10 degrees ({\tt APARM(4)} to  {\tt APARM(5)}),
               with no flagging on amplitude or weight.}
\dispt{OUTFGVER\qs 2 \CR}{to specify the output flag table.}
\dispt{GO \CR}{to run the program.}
\dispe{This will generate {\tt FG} table flagging time ranges that
fall between the specified elevation limits.}

Note that in both of these examples, the flagging information is
incorporated into a {\tt FG} table instead of ``irrevocably'' deleting
your data.  In order to apply these flags, you must set {\tt FLAGVER}
to the appropriate {\tt FG} table version.

Another \indx{editing} task which may be useful is {\tt \tndx{QUACK}},
which can edit the selected portion of the scan at its beginning
and/or end.  This might be needed because (at non-VLBA antennas) the
telescopes were still slewing or system temperature measurements were
being made.  The first 20 seconds or so of a scan, for baselines to
the VLA, are often unusable while the VLA correlator phases up at the
new source position.  The first second or so after a scan may also
need to be flagged ({\tt OPCODE 'TAIL'}) since some antennas may not
leave the previous source promptly, leaving bad data marked good.
{\tt QUACK} can be used to flag specific antennas for these and other
reasons.

Tasks {\tt \tndx{EDITA}} and {\tt \tndx{EDITR}} can be used to inspect
and edit the data interactively.  {\tt IBLED} is no longer of much use
since {\tt EDITR} now can edit on a coherence parameter.  These tasks
are similar in many respects to {\tt TVFLG}, but are more suited to
interferometers with small numbers of baselines. It is also possible to
use {\tt TVFLG} to perform your editing although the TV display is
somewhat confusing on sparse arrays of data, especially if there is
significant source structure.  Read \Sec{caledit} through \Sec{edita}
and \Sec{editing} for more details on the editing of data.  Also
{\tt \tndx{VPLOT}} may be used to edit data which deviates excessively
from the mean amplitude over a specified averaging interval; see {\us
HELP VPLOT \CR} for details.  Task {\tt WIPER} is a dangerous but
powerful editing tool as well.
\iodx{flagging}\iodx{editing}\Iodx{VLBI}

The task {\tt \tndx{DEFLG}} generates a flag table to delete data having
coherence less than a user-specified limit.  It must be run only on sources
that should be strongly coherent although it may be used to flag data from
other sources in between the strong-source scans.  The task {\tt
\tndx{SNFLG}} is also used to flag data whenever the phase jumps in an
{\tt SN} or {\tt CL} table are excessive on a baseline-by-baseline
basis.

The VLBA correlator may produce a lot of samples which it knows to be
bad and which are flagged by the transferred flag table.  For this
reason alone, or if you also flag a noticeable fraction of the data
set, you may wish to run {\tt \tndx{UVCOP}} to discard the flagged
data to conserve disk space and processing time.

%\vfill\eject
\Subsections{Amplitude and instrumental delay calibration}{vlbapriori}
\Todx{APCAL}

We now advocate a new amplitude calibration strategy base on VLBA
Scientific memo \#37 (Walker 2015).  This strategy interleaves classic
{\it a priori} calibration with instrumental delay and bandpass
calibration to improve the amplitude calibration of data from the new
Roach Digital Backend (RDBE) on the VLBA (see the VLBA Observations
Status Summary for a description
of the RDBE and VLBA Scientific Memo \#37 for a discussion of amplitude
problems with the RDBE).  With data from before the RDBE you can use either
the old or new strategy.


\Subsubsections{Parallactic angle correction} {vlbCLCOR}

The RCP and LCP feeds on each antenna will rotate in position angle
with respect to the source during the course of the observation for
alt-az antennas (which probably constitute a majority of the antennas
in your observation).  Since this rotation is a simple geometric
effect, it can be corrected by adjusting the phases without looking at
the data.  This correction must be performed before any phase
calibration which actually examines the data is executed.  This
correction is important for \indx{polarization} and phase-referencing
observations, so it should probably be applied to all cases..  Task
{\tt CLCOR} is used for this purpose; see \Sec{vlbCLCOR}.\Iodx{VLBI}

There is a procedure which assists you in running {\tt CLCOR} to
correct phases for parallactic angle:
\dispt{RUN \tndx{VLBAUTIL} \CR}{to acquire the procedures; this should
           be done only once since they will be remembered.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
             input file.}
\dispt{SUBAR\qs {\it ss\/} \CR}{to select the subarray number --- only
             one per execution.}
\dispt{INP\qs VLBAPANG \CR}{to review the inputs.}
\dispt{\Tndx{VLBAPANG} \CR}{to run the procedure.}
\dispe{{\tt VLBAPANG} should be run before applying any other phase
corrections.}

\Subsubsections{Digital sampler bias corrections for VLBA correlator
data}{accor}

The voltage threshold levels in the digital samplers at the antennas
may differ from their optimum theoretical values and this may vary
from antenna to antenna and from polarization to polarization.  This
sampler bias, which is usually significant only in two-bit
quantization, introduces an antenna/polarization-based amplitude
offset.  In full polarization observations this appears as an
amplitude offset between {\tt RR} and {\tt LL}\@.  The
cross-correlation amplitudes may be corrected if the auto-correlation
spectra have been measured.  See VLBA Scientific Memo No.~9 (1995,
``Effect of digitizers errors on the cross and auto correlation
response of an FX correlator'', by L. Kogan).  Task {\tt \tndx{ACCOR}}
can be used to remove these digital sampler biases from VLBA
correlator data, if {\tt FITLD} was run with {\tt DIGICOR = 0, 1,} or
{\tt 2}.   {\tt ACCOR} corrects these offsets by examining the
autocorrelation spectra.  You can check your autocorrelation data with
task {\tt \Tndx{ACIMG}} which makes an image cube with axes of
frequency, time, and antenna number.  Use the image display options
describe in Chapter 6 to inspect the image.  There may be data that
needs flagging.   Since {\tt ACCOR} computes the necessary correction
by examining the total-power spectra, it must be run immediately after
{\tt FITLD} in the sense that nothing else should be run that actually
modifies the total-power spectra directly.  Although {\tt ACCOR}
ignores any {\tt SN} or {\tt CL} tables that are present, it is
essential to correct for the sampler biases before performing any {\it
a posteriori\/} calibration, \eg\ fringe-fitting or self-calibration.
If the {\tt ACCOR} gain factors deviate from unity, there may be overall
scaling or {\it b\/}-factor errors.  For 2-bit quantization, however,
the amplitude offsets for the VLBA correlator are typically of order
$5-10\%$, but values as high as $20\%$ have been observed.

For one-bit quantization, no significant sampler bias correction is
expected.  Nonetheless, it is recommended that {\tt ACCOR} be run on
one-bit data as a consistency check.  {\tt VLBACCOR}  is a procedure
which runs {\tt \tndx{ACCOR}}, smooths the results with {\tt SNSMO},
and applies the solutions using {\tt CLCAL}\@.  Typical inputs would be:
\dispt{RUN \tndx{VLBAUTIL} \CR}{to acquire the procedures; this should
           be done only once since they will be remembered.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
             input file.}
\dispt{FREQID\qs {\it ff\/} ; SUBAR\qs {\it ss\/} \CR}{to select the
           frequency ID and subarray numbers --- only one of each per
           execution.}
\dispt{INP\qs VLBACCOR \CR}{to review the inputs.}
\dispt{\Tndx{VLBACCOR} \CR}{to run the procedure.}
\dispe{{\tt VLBACCOR} will normally be run after ``fixing'' the
the data with {\tt VLBAFIX} (if needed).  Use this procedure only
on data from the VLBA correlator.\iodx{calibration}}

If you do not want to use {\tt VLBACCOR},  typical inputs to {\tt ACCOR}
for this correction would be:
\dispt{TASK\qs 'ACCOR' ; INP \CR}{to review the inputs.}
\dispt{INDISK {\it n\/}; GETN {\it ctn\/} \CR}{to specify the input
            file.}
\dispt{TIMERANG 0\CR}{to select data from all times.}
\dispt{SOLINT \qs 2\CR}{to set the solution interval for sampler
            corrections (min).}
\dispt{GO \CR}{to run the program.}
\dispe{The correction factors were expected to be fairly stable over
time, but they have been found to vary over times less than an hour.
With a solution interval of a few minutes, such as the two minutes
indicated here, it is well to examine the solution ({\tt SN}) table
generated by {\tt \tndx{ACCOR}} using {\tt \tndx{SNPLT}} for any bad
points or inconsistent values.  One approach is to inspect the {\tt
SN} table and then run {\tt SNSMO} with clipping to get rid of
discrepant points.  Alternatively, the interactive table editing task
{\tt SNEDT} can be used.}

\Subsubsections{Instrumental phase corrections}{pccor}

If you run {\tt POSSM} on a short ($\approx 1$ minute) section of data
on a strong calibrator using the inputs described in \Sec{possm} and
set {\us DOCAL = -1 \CR}, you will see that each individual IF channel
has its own independent phase offset and its own phase gradient
against frequency.  These phase offsets and instrumental ``single-band
delays'' are caused by passage of the signal through the electronics
of the VLBA baseband converters (or MkIII/MkIV video converter units).
The VLBA system can inject narrow band signals (``phase-cals'') into
the data recorded at each antenna from which the IF channel phase
offsets, and the instrumental single-band delays, can be
determined.\iodx{fringe-fitting}

For those antennas for which phase-cal measurements are available,
task {\tt PCCOR} can be used to incorporate the phase-cals into an
{\tt SN} table. (see \Sec{pccor}).  If you have other antennas for
which phase-cal measurements are not available, you can run {\tt
CLCAL} using the {\tt OPCODE='CALP'} option to incorporate the
incomplete {\tt SN} table information loaded by {\tt PCCOR} without
throwing away data for the antennas with missing phase-cal
information.

If external phase-\indx{calibration} data (pulse cals) are not
available then directly fringe-fitting a short scan of data to measure
the phase and single-band delay offsets may be applicable under
limited circumstances (see \Sec{PCCORhand}).  Even when
phase-calibration information is available, performing a manual
phase-cal can be a good idea to confirm that the IF-dependent delays
and phases have been successfully estimated and removed.  One good
check is to inspect the data using {\tt POSSM} at times different from
the time used to determine the manual phase calibration.  Note that
time-dependent delays may still be seen because of low elevation and
ionospheric effects.

As of 1 April 1999, the \Indx{VLBA} correlator is capable of
transferring phase-cal information directly to a {\tt PC} table for
some antennas. For other antennas, the phase-cal information may be
read into the {\tt PC} table using the task {\tt\tndx{PCLOD}}\@. Type
{\tt EXPLAIN PCLOD} for further information.  If you are unsure
whether your \Indx{VLBI} data has phase-cal information, use {\tt
IMHEAD} to list the extension tables and look for a {\tt PC}
extension.

Phase-calibration data in a {\tt PC} table can be used by task {\tt
\tndx{PCCOR}} to generate an {\tt SN} table which corrects for the
single-band instrumental phase and delay offsets (note that {\tt
PCCOR} uses two phase-cals in each IF)\@.  A short calibrator scan
must be specified to be used by {\tt \tndx{PCCOR}} to resolve any
$2\pi$ phase ambiguities in the phase-\indx{calibration} data.  The
specified time range must include at least one {\tt PC} table entry
for each antenna appearing in the {\tt PC} table.  Having resolved the
$2\pi$  phase ambiguities, {\tt PCCOR} uses the whole {\tt PC} table
to calculate entries in an {\tt SN} table for all times (not just the
{\tt TIMERANG} used to resolve the ambiguities).  The procedure
{\tt \Tndx{VLBAPCOR}} runs {\tt PCCOR}, {\tt FRING} (if needed because
of missing pulse-cals for some antennas), and {\tt CLCAL} for you.
Inputs are:
\dispt{RUN \tndx{VLBAUTIL} \CR}{to acquire the procedures; this should
           be done only once since they will be remembered.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
           input file.}
\dispt{TIMERANG\qs {\it d1 h1 m1 s1 d2 h2 m2 s2\/} \CR}{to specify a
           short scan on a calibrator.  There is no default.}
\dispt{REFANT\qs {\it m}\CR}{to select a particular reference antenna.}
\dispt{SUBARRAY\qs 0}{to do all subarrays.}
\dispt{CALSOUR\qs '{\it cal1\/}', '\qs'}{to specify the calibrator
           source name.}
\dispt{GAINUSE\qs {\it CLin\/} \CR}{to indicate the {\tt CL} table
           with all calibration up to this point.}
\dispt{OPCODE\qs 'CALP' \CR}{to indicate that there are antennas
           with no usable pulse cals; use {\tt OPCODE\qs'\qs'} if all
           antennas have pulse cals.}
\dispt{ANTENNAS\qs {\it a1 a2 a3\/} \CR}{to solve for antennas {\it
           a1, a2, a3\/} ``manually'' (using {\tt FRING}).}
\dispt{VLBAPCOR \CR}{to run the procedure.}
\dispe{This should be done after the sampler correction ({\tt VLBACCOR})
and before the complex bandpass, The {\tt CALP} option requires the data
in the specified {\tt TIMERANG} to include strong fringes for those
antennas lacking phase-cal data.\Iodx{VLBI}}

Running the tasks individually, typical inputs to {\tt PCCOR} are:
\dispt{TASK\qs 'PCCOR' ; INP \CR}{to review the inputs.}
\dispt{INDISK {\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
           input file.}
\dispt{TIMERANG\qs 1 2 15 0 1 2 20 0 \CR}{to isolate a short scan on a
           calibrator; {\it no default\/}.}
\dispt{SNVER\qs 0 \CR}{to create a new {\tt SN} table.}
\dispt{INVER\qs 1 \CR}{to specify the input {\tt PC} table version.}
\dispt{REFANT\qs 5 \CR}{to specify reference antenna.}
\dispt{SUBARRAY\qs 1 ; FREQID\qs 1 \CR}{to set subarray and freqid.}
\dispt{CALSOUR\qs '3C345',' ' \CR}{to set calibrator source name.}
\dispt{GO \CR}{to run the program.}
\dispe{\todx{PCCOR} The resulting solution table is applied using {\tt
CLCAL}\@.  If you are missing phase-cal information for some antennas,
you must use the {\tt 'CALP'} mode of {\tt CLCAL}; this mode allows
calibration information for some antennas to be incorporated into the
{\tt CL} table while passing other antennas through without
modification.  Examine the corrected data using {\tt POSSM} to
determine if the instrumental phase and delay offsets between the IF
channels have been removed correctly.}

To check that the applied phase-cals are valid, run {\tt POSSM} on a
short section of data containing a strong source setting {\tt DOCAL =
1}, {\tt GAINUSE} to the version number of the {\tt CL} table
containing the phase-cal \indx{calibration}, and {\tt APARM(9) = 1} to
place all IFs on the same plot.  The phase as a function of frequency
on each baseline should be smoothly varying, with no sharp jumps
between different IF channels.  There may be an overall linear
gradient with frequency due to residual delay errors.  Unless these
conditions hold for all baselines, you should proceed to
\Sec{PCCORhand}.

The DiFX correlator has the capability of writing a large number (1 per
MHz typically) of pulse cals into each IF\@.  \AIPS\ can handle this
with new tasks {\tt \tndx{PCFLG}} (flags {\tt PC} data with a {\tt
SPFLG}-like TV display), {\tt \tndx{PCEDT}} (flags {\tt PC} data with a
{\tt BPEDT}-like TV graphical display), {\tt \tndx{PCPLT}} (plots {\tt
PC} table data all antennas with one time per page or all times with one
antenna per page), {\tt \tndx{PCASS}} (finds {\it amplitude} bandpass),
and {\tt \tndx{PCFIT}} (fits delays and phases to {\tt PC} data, writing
an {\tt SN} table of the changes in these as a function of time).
{\tt \tndx{PCLOD}} can now read {\tt PCAL} files written by DiFX\@.
Other tasks include {\tt \tndx{PCAVG}} to average pulse-cal tables in
time and {\tt \Tndx{PCRMS}} to edit pulse-cal tables automatically from
internal statistics.  {\tt POSSM} can also now plot {\tt PC} table data
({\tt APARM(8) = 9}.  This package of routines remains experimental, but
it has been shown do good things with the data.  It is now documented in
\AIPS\ Memo 123.\footnote{Greisen, E. W. 2025 (revised), ``New Pulse-cal
Capabilities for VLBI in \AIPS'' \AIPS\ Memo 123,\\  {\tt
https://www.aips.nrao.edu/aipsdoc.html}}  New tasks in {\tt 31DEC21}
include {\tt \tndx{VLBSY}} to read VLBA total power files, {\tt
\tndx{VLBCD}} to read noise tube values from a VLBA cal file, {\tt
\tndx{PCABL}} to copy cable cal values from the old {\tt PC} table to
ones created by {\tt PCLOD}, and {\tt \tndx{PCDIV}} to scale pulse-cal
amplitudes by the system temperatures.

%\vfill\eject
\Subsubsections{``Manual'' instrumental phase corrections}{PCCORhand}
\Todx{FRING}\iodx{calibration}

     If your file does not have phase-cal information, or if these
phase-cals do not successfully remove frequency phase offsets, you can
use observations of a bright calibrator source and the task {\tt
FRING} to correct for these effects.  If you attempted phase-cal
calibration, it is best to avoid possible confusion by first deleting
any partial or erroneous phase-cal information that already exists.
Using {\tt \tndx{CLCOR}}:
\dispt{TASK\qs 'CLCOR' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs {\it n\/} ; GETN {\it ctn\/} \CR}{to specify the
             input file.}
\dispt{GAINVER\qs {\it clin\/} ; GAINUSE\qs 0 \CR}{to specify which
             {\tt CL} table to modify after copying it to a new
             table.}
\dispt{OPCODE\qs 'PCAL' ; CLCORPRM 0 \CR}{to set phase-cals to zero.}
\dispt{INP \CR}{to check the inputs.}
\dispt{GO \CR}{to run the task.}
\dispe{If you have large known delay offsets you may also wish to run
{\tt CLCOR} using {\tt OPCODE='SBDL'} to shift the center of the
fringe search window.}

If you have a known clock offset, as may be common for an SVLBI data
set, you may wish to run {\tt CLCOR} with {\tt OPCODE = 'CLOC'} and
{\tt CLCORPRM = 0, {\it offset\/}, 0, 0, 0, 0, 1, 0}.

Now you can determine the manual phase correction for one or two
strong calibrator scans for which all the antennas are present using
{\tt \Tndx{VLBAMPCL}}\@.  Task {\tt \tndx{BSCAN}} may be used to
select the scan(s) to be used at this stage.  {\tt VLBAMPCL} runs {\tt
FRING} and {\tt CLCAL} once or twice, depending on whether one or two
scans are used.  Choose a scan with strong fringes to all antennas; if
none exists, find a second scan that has strong fringes to the
antennas missing from the first.  Note that if you use 2 scans the
{\tt REFANT} must have good fringes in both scans.  Typical inputs
are:\Iodx{VLBI}
\dispt{RUN \tndx{VLBAUTIL} \CR}{to acquire the procedures; this should
           be done only once since they will be remembered.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
           input file.}
\dispt{TIMERANG\qs {\it d1 h1 m1 s1 d2 h2 m2 s2\/} \CR}{to specify a
           short scan on a calibrator.  There is no default.}
\dispt{REFANT\qs {\it m}\CR}{to select a particular reference antenna.}
\dispt{SUBARRAY\qs 0}{to do all subarrays.}
\dispt{CALSOUR\qs '{\it cal1\/}', '\qs'}{to specify the calibrator
           source name.}
\dispt{GAINUSE\qs {\it CLin\/} \CR}{to indicate the {\tt CL} table
           with all calibration up to this point.}
\dispt{OPCODE\qs 'CALP' \CR}{to indicate that there are antennas
           with no fringes for the scan in {\tt TIMERANG}; use
           {\tt OPCODE\qs'\qs'} if all antennas will be corrected by
           the first scan.}
\dispt{TIME2\qs {\it d1 h1 m1 s1 d2 h2 m2 s2\/} \CR}{to specify a
           short second scan on a calibrator.}
\dispt{CALSOUR\qs '{\it cal2\/}', '\qs'}{to specify the calibrator
           source name for the second scan.}
\dispt{ANTENNAS\qs {\it a1 a2 a3\/} \CR}{to solve for antennas {\it
           a1, a2, a3\/}.}
\dispt{\Tndx{VLBAMPCL} \CR}{to run the procedure.}
\pd

If you wish to run {\tt FRING} separately, you can determine the phase
offsets/single band delays by running {\tt FRING} on a short section
of calibrator data where all or most of the antennas are present.
Suitable inputs for {\tt FRING} for this purpose are shown below; for
more details of some of the {\tt FRING} input parameters see
\Sec{fring}\@.  Note that it is simplest to choose a single short
section of data within a single scan using {\tt TIMERANG} and to set
{\tt SOLINT} equal to the scan length so that a single solution is
achieved.  The interval chosen must be less than than an atmospheric
coherence time, but long enough that high signal-to-noise is achieved.
At centimeter wavelengths with Jansky-level calibrators, solution
intervals of a few minutes will work well.  For
example:\iodx{fringe-fitting}
\dispt{TASK\qs 'FRING' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs {\it n\/} ; GETN {\it ctn\/} \CR}{to specify the
            input file.}
\dispt{CALSOUR\qs '0954+658 ' , ' ' \CR}{to select a strong calibrator
            source.}
\dispt{TIMERANG\qs 0, 16, 0, 0, 0, 16, 2, 0 \CR} {to select a single
            short scan.}
\dispt{DOCALIB\qs 1 ; GAINUSE\qs 2\CR}{to apply the amplitude
            calibration from {\tt CL} table 2 to the weights as well
            as the visibilities.}
\dispt{FLAGVER\qs 0 \CR}{to apply the most recent flag table.}
\dispt{SMODEL\qs 0 \CR}{to use the null (point-source at the origin)
            source model.}
\dispt{REFANT\qs 5 \CR}{to specify a reference antenna that will give
            fringes to most other antennas.}
\dispt{SOLINT\qs 0 \CR}{to set the solution interval in minutes; do
            not exceed the atmospheric coherence time.}
\dispt{APARM 0; DPARM 0\CR}{to initialize {\tt FRING} options to
            defaults.}
\dispt{APARM(1)=2\CR}{to require at least 2 antennas.}
\dispt{APARM(6)=1\CR}{to solve for the rate, single-band delay and
            phase of each IF separately.}
\dispt{DPARM(1)=1\CR}{to use only 1 baseline in the initial
            (coarse) fringe search.}
\dispt{DPARM(9)=1\CR}{to suppress fitting of rates; rates will be 0 in
            the {\tt SN} table.}
\dispt{SNVER\qs 0 \CR}{to create a new {\tt SN} table.}
\dispt{ANTWT\qs 0 \CR}{to apply no additional weights to the antennas
            before doing the solutions.}
\dispt{INP \CR}{to check the inputs.}
\dispt{GO \CR}{to do the fit.}
\dispe{If there was no single scan where all the antennas were
present, you can run {\tt FRING} again for another scan setting {\tt
REFANT} to be one of the antennas found in the first run (the same
{\tt REFANT} would be best) and {\tt ANTENNAS} to this antenna plus
all of the antennas {\it not\/} found in the first run.  {\tt FRING}
will generate a new {\tt SN} table each time; be careful to keep track
of which {\tt SN} tables you wish to use.}

The phase solutions in the {\tt SN} table(s) are interpolated onto a
\indx{calibration} or {\tt CL} table using task {\tt CLCAL} as
described in \Sec{vlbapply}.  To apply the calibrator solutions to the
other sources in the data file, set {\tt CALSOUR} to the calibrator
source used when running {\tt FRING} (in the example above, {\tt
CALSOUR \ '0954+658'}) and set {\tt SOURCES = ' '} for all sources.
Also, set {\tt REFANT} to whatever was used when running {\tt
FRING}\@.  If multiple runs of {\tt FRING} were required, you can set
{\tt SNVER=0} so that all {\tt SN} tables are combined before being
applied ; if you do this, you must first be careful to delete all {\tt
SN} tables except those generated by {\tt \Tndx{FRING}}\@.  Or you can
run {\tt CLCAL} multiple times specifying each {\tt SN} table in turn,
with the specific antenna numbers, while keeping the same {\tt CL}
table versions.\iodx{fringe-fitting}\Iodx{VLBI}

     To check the output {\tt CL} table, run {\tt POSSM} for the scan
used for the {\tt FRING} solution with {\tt DOCAL = 1} and {\tt
GAINUSE = 3} (\ie\ the output {\tt CL} table from the {\tt CLCAL}
above).  The phase should be flat as a function of frequency on all
baselines, although it may not be centered on zero.   Run {\tt POSSM}
on another scan containing a strong calibrator to check that the
assumption of constant IF phase offset holds.


\Subsubsections{Bandpass calibration}{vlbBPcal}

Full \indx{bandpass} response \indx{calibration} should be performed
for all observations.  It is suggested that integrating over a variable
bandpass function is one of the most significant sources of non-closing
errors in continuum VLBI data. By calibrating the bandpass before averaging
over frequency, these effects can be avoided.  In VLBA test observations,
a dynamic range of 28,000:1 was achieved on the source DA193 (Briggs
{\it et al.\/} 1994, VLBA Memo No 697A, ``High Dynamic Range Imaging
with the VLBA'') after applying bandpass calibration.

Bandpass calibration is carried out using the task {\tt \tndx{BPASS}}
using either the auto- or cross-correlation data. The output is a {\tt
BP} or bandpass table.  For this amplitude calibration scheme the
cross-correlation (complex) bandpass must be used.  The derived
bandpass solutions can be plotted using {\tt \tndx{POSSM}} by setting
{\tt APARM(8)=2}.  The effect of applying these bandpass solutions to
your data can also be viewed using {\tt POSSM} by setting {\tt
DOBAND=1} and {\tt BPVER}\@.  An example of the inputs to produce
bandpass spectra from the cross-correlation data would be:
\dispt{TASK\qs '\tndx{BPASS}' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs {\it n1\/} ; GETN\qs {\it ctn1\/} \CR}{to select the
          multi-source visibility data as the input file.}
\dispt{CALSOUR\qs 'BLLAC' , 'DA193' \CR}{to specify the continuum
          source(s) which were observed for the purpose of
          \tndx{bandpass} calibration.}
\dispt{DOCALIB\qs 1 \CR}{to apply calibration.}
\dispt{SOLINT\qs 0 \CR}{to average data over whole scans before
          determining the bandpass.}
\dispt{BPASSPRM\qs 0 \CR}{to use the cross-spectra.}
\dispt{BPASSPRM(5)\qs 1\CR}{to not divide by ``channel 0.''}
\dispt{BPASSPRM(9)\qs 1 \CR}{to interpolate over flagged channels.}
\dispt{BPASSPRM(10)\qs 6 \CR}{to normalize the amplitude solutions
          using the {\it power} solutions rather than the actual
          solutions which are voltages.}
\dispt{ICHANSEL\qs $chan_{beg}$, $chan_{end}$, 1, $IF_{num}$, ... \CR}
         {to set channels for entire bandwidth for normalization, if
          this left 0 then the inner 75\% is used and can cause up to
          15\% error in the amplitude, so unfortunately {\tt ICHANSEL}
          must be explicitly set to all the channels in the IF, for
          every IF.}
\dispt{GO \CR}{to run the program.}
\dispe{Be careful with the adverb {\tt SMOOTH}\@.  If you smooth, or
do not smooth, the data while finding a bandpass solution, then you
must apply the same {\tt SMOOTH} adverb values whenever you apply that
bandpass solution to the data.  The only exception is that you may
smooth the data after applying the bandpass solution with {\tt
SMOOTH(1)} values 5 through 8 when you did no smoothing in {\tt
BPASS}}\@.

This will produce a {\tt BP} table containing the antenna-based
bandpass functions to be applied to the data.  You should check your
results very carefully.  The {\tt BP} tables can be plotted with {\tt
\tndx{POSSM}} or printed with {\tt PRTAB}\@.  Note that this task merely
creates a {\tt BP} table.  To use this {\tt BP} table, set {\tt BPVER}
and {\tt DOBAND} as described in \Sec{BPASSit} when running any later
\AIPS\ tasks.

Note, if your bandpass calibrator is not stable or strong enough
during the observation (your bandpass calibrator data should have
a better S/N than the data you're trying to correct with the
bandpass), you could consider using the phase reference source (if
there is one) and use {\tt SOLINT = -1} (include all scans to make one
bandpass solution).  If the bandpass calibrator is strong enough, but
the average phase varies through the scan, then divide each record by
``channel 0'' by setting {\tt BPASSPRM(5) = -1} to adjust phase only.
You should select a range of channels that have similar phases to be
averaged as channel 0 using adverb {\tt ICHANSEL}\@

The normalization of the bandpass correction can be checked by running
{\tt \Tndx{ACSCL}} after {\tt BPASS}\@.  This task is a version of
{\tt ACCOR} which applies the current calibration tables to the data
before forcing the autocorrelations to unity.  Be sure to set {\tt
DOBAND} to apply the bandpass by your preferred method.  {\tt ACSCL}
will write an {\tt SN} table with amplitude corrections which should
be very close to one.  Apply that table with {\tt CLCAL}\@.  However
if you run {\tt VLBAAMP}, {\tt ACSCL} and {\tt CLCAL} will be run
for you, see \Sec{vlbcamp}\@.

The interactive data editing task {\tt \Tndx{BPEDT}} lets one flag
visibility data based on bad bandpass solutions.  It can edit the {\tt
BP} table instead and even interpolate over the flagged values.  It is a
graphical editor much like {\tt EDITR} and {\tt EDITA} except that it
displays bandpass solutions as a function of spectral channel.  It is a
quick way to check your bandpass table and, if necessary, to flag bad
channels in your calibration source.  If you do generate new data flags,
you should run {\tt BPASS} over again to generate a corrected {\tt BP}
table.  Set {\tt BPASSPRM(9) = 1} to interpolate over any fully flagged
channels.  For really large {\tt BP} tables, you may wish to use {\tt
\Tndx{BPFLG}} instead after determining clip levels with {\tt BPEDT}
although {\tt BPEDT} has been made much faster for such {\tt BP}
tables.


\Subsubsections{Continuum amplitude calibration}{vlbcamp}
\Todx{APCAL}\iodx{calibration}

After bandpass calibration is determined, the auto-correlations can be
slightly offset from unity.  To correct this offset {\tt ACSCL} can be run,
applying all the previous amplitude and bandpass calibration.  Described
below is a procedure that is part of {\tt VLBAUTIL} called {\tt VLBAAMP}
that runs {\tt ACSCL} as well as the final amplitude calibration steps.

The {\tt TY} table can be examined using {\tt SNPLT} with {\tt
OPTYPE='TSYS'} or {\tt 'TANT'} or {\tt LISTR} with {\tt
OPTYPE='GAIN'}; the {\tt GC} table is examined with {\tt PRTAB}\@.
{\tt \tndx{SNEDT}} may also be used to inspect the {\tt TY} table and
even used to delete or smooth some of the measurements.  {\tt
\tndx{SNRMS}} may be used to examine statistics of the {\tt TY} table.
{\tt \tndx{TYSMO}} can be used to delete discrepant system temperatures
and replace the bad and/or good values with time-smoothed values.  Note,
however, that anomalously high system temperatures may indicate possible
bad data (\eg\ due to weather) rather than bad measurements of the
system temperature.  On occasion, RFI in some IFs can render the values
for those IFs in the {\tt TY} table unusable.  Task {\tt \tndx{TYCOP}}
will copy {\tt TY} data between IFs and polarizations in a variety of
ways in an attempt to replace the bad data with something reasonable
even if not exactly correct for that antenna and IF.  Note that flagging
bad \uv\ data will not change the appearance of the {\tt TY} table since
no flags are applied in plotting this table.  {\tt EDITA} may also be
used to examine the {\tt TY} data interactively and, if bad system
temperatures are found, to flag the associated \uv\ data.  (This task
does flag displayed $T_{\rm sys}$ when the data are flagged.)  Tasks
{\tt UVCOP} and {\tt SPLAT} will apply a flag table not only to the $uv$
data, but also to the {\tt TY} and {\tt SN} tables.  {\tt APCAL} can
then be used to derive an amplitude calibration ({\tt SN})
table.\Iodx{VLBI}

Atmospheric opacity becomes significant at high frequencies ($\ge15$
GHz).   {\tt \Tndx{APCAL}} can fit for an opacity correction, if
needed, using weather information and system temperature.  The weather
information can be taken from the {\tt WX} table by setting {\tt
INVERS} (after October 7, 2003) or loaded from disk by setting {\tt
CALIN}\@.  In order to have {\tt APCAL} fit for opacity set {\tt
OPCODE} to {\tt 'GRID'}, {\tt 'OPAC'} or {\tt 'LESQ'} and {\tt DOFIT}
to 1 (both of these are necessary for an opacity fit).  {\tt OPCODE
'GRID'} and {\tt 'OPAC'} need an initial guess for the receiver
temperature ({\tt TRECVR} and zenith opacity ({\tt TAU0})\@.  {\tt
APCAL} will estimate the initial guesses from the data if {\tt TRECVR}
and/or {\tt TAU0} are 0.  If {\tt OPCODE} is set to {\tt 'GRID'}, {\tt
'OPAC'} or {\tt 'LESQ'} and {\tt DOFIT} $\leq 0$ then the opacity
correction is applied using the provided {\tt TRECVR}\@.  This is a good
option if you have a reliable measurement of the receiver temperature.
In {\tt 31DEC20}, use {\tt OPCODE 'PLOT'} to plot the data against the
solution you wish to apply to make sure it is reasonable.  The fits are
fairly robust, but the plots that {\tt APCAL} makes should be examined.
Note: a large number of bad Tsys values can make the fits unreliable.
{\tt APCAL} will warn you if fits appear to be incorrect.  The procedure
{\tt VLBAAMP} runs {\tt \tndx{ACSCL}}, smooths the results with {\tt
SNSMO}, runs {\tt \tndx{APCAL}}, and applies the solutions using {\tt
CLCAL}\@.:
\dispt{RUN \tndx{VLBAUTIL} \CR}{to acquire the procedures; this should
           be done only once since they will be remembered.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
             input file.}
\dispt{FREQID\qs {\it ff\/} ; SUBAR\qs {\it ss\/} \CR}{to select the
           frequency ID and subarray numbers --- only one of each per
           execution.}
\dispt{INP\qs VLBAAMP \CR}{to review the inputs.}
\dispt{DOFIT\qs 1 \CR}{to enable the opacity correction; $\le 0$
           disables it.}
\dispt{\Tndx{VLBAAMP} \CR}{to run the procedure.}
\dispe{{\tt VLBAAMP} will normally be run after correcting the
bandpass and loading any
gain curves or system temperature data for non-VLBA antennas using
{\tt ANTAB}\@.\iodx{calibration}}

If you have not used {\tt VLBAAMP} and do not want to correct for
atmospheric opacity,  typical inputs to {\tt APCAL} are:
\dispt{TASK\qs 'APCAL' ; INP \CR}{to review the inputs.}
\dispt{INDISK {\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
               input file.}
\dispt{ANTENNAS\qs 0 ; SUBARRAY\qs 0 \CR}{to select all antennas and
               subarrays.}
\dispt{SOURCES\qs ' ' ; STOKES\qs ' ' \CR}{to select all sources and
               Stokes.}
\dispt{BIF\qs 1 ; EIF\qs 0 ; FREQID\qs 1 \CR}{to select all IFs of
               frequency ID 1.}
\dispt{TIMERANG\qs 0 ; OPCODE\qs ' ' \CR}{to select all times and use
               no opacity solutions.}
\dispt{TYVER\qs 0 ; GCVER\qs 0 \CR}{to use the latest {\tt TY} and
               {\tt GC} tables.}
\dispt{SNVER\qs 0 \CR}{to create a new {\tt SN} table.}
\dispt{GO \CR}{to run the program.}
\dispe{If atmospheric opacity correction is desired, set the following
inputs as well as the above:}
\dispt{OPCODE\qs 'GRID' \CR}{do a grid search.}
\dispt{DOFIT\qs 1 \CR}{to fit the opacities.}
\dispt{INVERS\qs 1 \CR}{to use {\tt WX} table 1.}
\dispt{TAU0\qs 0 ; TRECVR\qs 0 \CR}{to let {\tt APCAL} estimate
                initial values.}
\dispt{GO \CR}{to run the program.}
\dispe{The resulting solution ({\tt SN}) table can be smoothed and
clipped using {\tt SNSMO} and applied using {\tt CLCAL} as described
in \Sec{vlbapply}).  Substantial smoothing of the {\tt TY} table (task
{\tt TYSMO}), especially for VLBA-only observations, is not generally
recommended since variations of the system temperature often reflect a
real response to the weather.  Note, however, that {\tt TYSMO} is very
useful for removing bad system temperatures before they are applied.
Smoothing can be useful for data from the phased-VLA, when the amplitude
calibration information reflects low signal-to-noise.  For non-VLBA
antennas, it is important to check with {\tt \tndx{SNEDT}} that the
{\tt TY} information is associated with the correct source and {\tt
SNEDT} can be used to delete occasional bad system temperature
measurements before they are applied to the data.  When opacities are
fit, {\tt APCAL} generates plots of the receiver temperature versus
zenith angle and the opacity versus time.  {\tt APCAL} will warn you
about bad fits, but the plots should be checked for problems with the
data or the fits.\Todx{APCAL}}

On occasion, it has been noted that plots of system temperature show
unreasonable variation between IFs.  This suggests that the ${\rm
T}_{\rm cal}$ values may have systematic errors as a function of
frequency.  {\tt APCAL} has an option to bring the ${\rm T}_{\rm sys}$
values into better agreement with either their average or with a
user-chosen IF, thought to be probably accurate.  {\tt APARM(6)} $> 0$
selects this function while {\tt APARM(7)} may be used to specify a
specific IF to calibrate the others.  Note that a single value is used
for each antenna/IF over all times.

The DiFX correlator in now capable of correlating multiple
phase-stopping positions within a single antenna beam (pointing
position).  There is task called {\tt \tndx{CLVLB}} designed to apply
corrections to a {\tt CL} table (writing a new one) for the offset of
phase-stopping and pointing position.  The task has internal tables for
the beam shape and squint of the VLBA antennas and can take user input
for these parameters for other antennas.  This is a new task and should
be used with caution --- early results with it were less than satisfying
--- although the corrections it applies are certainly in the right
direction.

\Subsections{Spectral-line Doppler correction}{cvel}

Normally, when observing, you will have kept the frequency constant
throughout the run for ease of observing.
Therefore, although your data will have the same frequency, the center
\indx{velocity} of your spectrum will change with time and the
\indx{spectral-line} signals will wander backwards and forwards
through the spectrum.  To ensure that the velocity is constant
throughout the data you should run {\tt SETJY} and then {\tt CVEL}\@.
The \indx{VLBA} correlator compensates for the revolution of the
antennas relative to the center of the Earth. In this case, the only
movement which {\tt CVEL} should compensate is the rotation of the
antennas together with the Earth around the Sun.  This movement should
be the same for all antennas and gives a smaller effect than the
rotation relative to the center of the Earth.  Nonetheless, {\tt CVEL}
is required for the \indx{VLBA} correlator at least to be able to
compare observations made at different times.  Without {\tt CVEL} such
comparisons will show the velocity shift of the Earth's orbit about
the Sun.\iodx{calibration}\Iodx{VLBI}

     {\tt \tndx{SETJY}} will insert the velocity information required
in the {\tt SU table}:
\dispt{TASK\qs 'SETJY' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs {\it n1\/} ; GETN\qs {\it ctn1\/} \CR}{to select the
          data.}
\dispt{SOURCE\qs 'OH127.8' , '\qs ' \CR}{to specify the line source
          whose velocity is to be specified.}
\dispt{OPTYPE\qs ' ' \CR}{to switch off flux modification.}
\dispt{SYSVEL\qs -66.0 \CR}{to specify the velocity of the ``center''
          of the band in km/s.}
\dispt{APARM\qs 65, 0 \CR}{to specify which spectral pixel is the
          ``center'' of the band, actually the pixel to which {\tt
          SYSVEL} refers.}
\dispt{RESTFREQ\qs 1612e6, 231.09e3 \CR}{to give the rest-frequency in
          Hz, \eg\ that of the OH transition.  Note that the two
          single-precision adverb numbers are summed in double
          precision inside {\tt SETJY}\@.}
\dispt{VELTYP\qs 'LSR' \CR}{to select the rest frame of the velocity.}
\dispt{VELDEF\qs 'OPTICAL' \CR}{to define velocities by the optical
          convention.}
\dispt{GO \CR}{to run the program.}
\pd

     Then run {\tt \tndx{CVEL}}:
\dispt{TASK\qs 'CVEL' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs {\it n\/} ; GETN\qs {\it ctn\/} \CR}{to select the
          data.}
\dispt{OUTDISK 3 ; OUTCLASS 'CVEL' \CR}{to specify the output file.}
\dispt{SOURCE\qs 'OH127.8' , '\qs ' \CR}{to select the source(s) to
          be shifted, all others will be passed un-shifted.}
\dispt{DOBAND\qs 1 \CR}{to apply the \indx{bandpass} correction ---
          important.}
\dispt{BPVER\qs 1 \CR}{to specify the version of {\tt BP} table to
          use.}
\dispt{GO \CR}{to run the program.}
\dispe{After applying the {\tt BP} table, {\tt \tndx{CVEL}} will not
copy it to the output file to protect you from applying it twice.
Although {\tt CVEL} allows you to select which sources are to be
shifted, the {\tt BP} table, if {\tt DOBAND} is set appropriately,
will be applied to all sources found.}

\Subsections{Spectral-line amplitude calibration}{acfit}

The \indx{calibration} strategy suggested in \AIPS\ for spectral-line
\Indx{VLBI} data utilizes the total-power spectra method described in
Lecture 12 of {\it VLBI, Techniques and Applications\/}, eds.~Felli
and Spencer, published by Kluwer Academic Publisher, 1988.  The
continuum method using \Tsys\ values (see \Sec{vlbcamp}) can also be
used.  The first step is to generate a so-called template spectrum.
This is a high quality spectrum from the most sensitive antenna in the
array that has been corrected for the effects of the bandpass filter.
For example:
\dispt{TASK\qs '\tndx{SPLIT}' ; INP \CR}{to review the inputs.}
\dispt{INDISK {\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
           input file.}
\dispt{SOURCE\qs 'OH127.8', '\qs ' \CR}{to write the program source.}
\dispt{BCHAN\qs 0 ; ECHAN\qs 0 \CR}{to write all spectral channels.}
\dispt{DOCALIB\qs -1 \CR}{to avoid applying any calibration.}
\dispt{DOBAND\qs -1 \CR}{to skip the bandpass correction since the
           data will have been corrected already in {\tt CVEL}\@.}
\dispt{TIMERANG\qs 0 22 0 0 0 22 30 0 \CR}{to select the data from a
           range of times when the antenna elevation was high and the
           source spectrum of high quality.}
\dispt{APARM\qs 0, 0, 0, 0, 1 \CR}{to pass only self-spectra.}
\dispt{GO \CR}{to run the program.}
\pd

You should then run {\tt \tndx{ACFIT}} to do a least-squares fit of
the template total-power spectrum to the total-power spectra of all
other antennas and to write the resulting time-dependent amplitude
gain correction factors into an {\tt SN} table.
\iodx{calibration}\iodx{spectral-line}
\dispt{TASK\qs 'ACFIT' ; INP \CR}{to review the inputs.}
\dispt{INDISK {\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
          input file.}
\dispt{IN2DISK {\it n\/} ; GET2N\qs {\it ctn\/} \CR}{to specify the
          template file.}
\dispt{CALSOUR\qs 'OH127.8 ' \CR}{to select the source to use for
          calibration.}
\dispt{DOCALIB\qs -1 \CR}{to avoid applying any previous calibration.}
\dispt{DOBAND\qs -1 \CR}{to skip the bandpass correction since it was
          done when {\tt CVEL} was run.}
\dispt{SOLINT\qs $n$ \CR}{to average the self-spectra over $n$
          minutes (\eg\ 10) before doing the least-squares fit.}
\dispt{REFANT\qs 1 \CR}{to select the desired reference antenna from
          the template file.}
\dispt{BCHAN\qs 50 ; ECHAN\qs 70 \CR}{to set the range of spectral
          channels over which the fit is performed.}
\dispt{BPARM\qs 80, 120 \CR}{to set up to 5 pairs of start and stop
          channels to use in determining the baseline polynomial to be
          removed from the source spectra. The order of the
          polynomial is specified in {\tt APARM(1)}.}
\dispt{CPARM\qs 80, 120 \CR}{to set up to 5 pairs of start and stop
          channels to use in determining the baseline polynomial to be
          removed from the template spectra. The order of the
          polynomial is specified in {\tt APARM(2)}.}
\dispt{XPARM\qs 45.1, 48.0, 50.1, 49.5 \CR}{to specify \Tsys\ values
          in the first polarization for each IF for the template scan
          of the reference antenna. {\tt YPARM} provides an equivalent
          list for the data, if any, from a second polarization.}
\dispt{APARM\qs 0, 0, 50, 0, 0.72 \CR}{program control: {\tt
          APARM(1)}  and {\tt APARM(2)} specify the orders of the
          polynomial spectral baseline to remove from the source and
          template spectra; {\tt APARM(3)} and {\tt APARM(4)} specify
          the sensitivity of the template antenna (in Jy/deg) in the
          first and second (if needed) polarizations; {\tt APARM(5)}
          and {\tt APARM(6)} specify the minimum and maximum relative
          antenna gains allowed, with defaults to allow all positive
          values; {\tt APARM(7)} specifies the maximum allowed gain
          error, with 0 meaning all; {\tt APARM(8)} specifies the
          print level, with 0 providing minimal information, 1
          providing useful information on the gains determined for
          each antenna and solution interval and 2 giving the gory
          details for each fit; {\tt APARM(9)} specifies that the fits
          are done after subtracting a spectral baseline (0) or
          without a baseline (1); and {\tt APARM(10)} controls whether
          baseline-subtracted spectra are written to an output file.}
\dispt{SNVER\qs 0 \CR}{to create a new {\tt SN} table into which the
          solutions are to be written.}
\dispt{GO \CR}{to run the program.}
\dispe{{\tt \tndx{ACFIT}} will generate an {\tt SN} table, which has
to be applied to the {\tt CL} table.  If needed, run {\tt
\tndx{SNSMO}} to smooth the amplitude correction factors determined by
{\tt ACFIT} before running {\tt CLCAL}\@.  A 30-minute smoothing
interval for {\tt SNSMO} (set using {\tt CPARM 0.5,0}) should be
sufficient.\iodx{calibration}\iodx{spectral-line}\Iodx{VLBI}}

%\vfill\eject
\Subsections{Phase calibration}{phasecal}

After carrying out amplitude calibration, the remaining calibration
steps involve correcting the phase between the different integration periods.
This will allow averaging of the data over both frequency and time
without loss of coherence.  The phase offsets may be corrected using
{\it a priori\/} `phase-cal' measurements if available and/or by
directly fitting to the data.

After removing instrumental phase offsets from each IF, the data
will in general still contain frequency and time dependent phase
variations.  The purpose of ``fringe-fitting'' is to determine these
phase errors and then remove them from the data.

The primary \AIPS\ task for \indx{fringe-fitting} is {\tt
\tndx{FRING}}\@.  This task estimates time variable station-based
delays (phase derivatives wrt frequency) and rates (phase derivatives
wrt time) using a self-calibration-like algorithm.  Once these delays
and rates are determined, the task {\tt CLCAL} is used to produce the
phase correction that should be applied to each integration period and
spectral channel to correct for delay and rate effects.  This use of
{\tt FRING} and {\tt CLCAL} is discussed in detail in \Sec{fring}\@.
Two alternatives to {\tt FRING} are the tasks {\tt BLING} and {\tt
BLAPP} and the experimental version of {\tt FRING} named {\tt
KRING}\@.  {\tt BLING} and {\tt BLAPP} are discussed briefly in
\Sec{bling}\@.  {\tt KRING} provides a superset of the functionality
in {\tt FRING} with numerous enhancements such as: the use of
extremely small scratch files, a parsimonious use of memory, possible
solution extrapolation both backwards and forwards in time and a
rationalized definition of SNR\@.  For more information about {\tt
KRING}, type {\tt HELP KRING} from within {\tt AIPS}\@.  When
fringe-fitting to many small scans, {\tt KRING} can be substantially
slower than {\tt FRING}\@.  When fringe-fitting data sets with large
numbers of spectral channels and long solution intervals, {\tt KRING}
can be substantially faster than {\tt FRING}\@.

The process of fringe-fitting, and then interpolating the solutions
using {\tt CLCAL}, can be a very time consuming process.  For this
reason it is probably wise to run through the fringe-fitting procedure
described in \Sec{fring} on a small amount of data first (say 30
minutes' worth) before attempting to process the whole data set.  This
is especially true if this is your first time processing multi-IF,
multi-channel \Indx{VLBI} data.  It is probably simplest to use {\tt
UVCOP} to copy out a short time range of data from your main file and to
work only on this initially.  Doing so also avoids the possible
confusion of having many versions of extension tables.  Note that, if
your spectral channels are narrow, the use of the {\tt CHINC} parameter
can speed up {\tt FRING}\@.

\subsubsections{Special considerations: SVLBI}
\iodx{SVLBI}

The existing \indx{fringe-fitting} tasks within \AIPS\ have been
enhanced to improve their performance when dealing with SVLBI data. In
addition, several new tasks have been written to address problems
specific to SVLBI fringe-fitting.  The primary SVLBI fringe-fitting
tasks in \AIPS\ are {\tt BLING} and {\tt FRING} and are discussed in
\Sec{fring}--\Sec{gphas}\@.  The tasks {\tt COHER} and {\tt FRPLT},
described in \Sec{coher} and \Sec{frplt}, may be of particular
interest when reducing SVLBI data.\iodx{calibration}

There may be delay discontinuities in the recorded data for a variety
of reasons such as tracking station handoffs, clock glitches, etc.
The recommended method for dealing with such discontinuities is to
force scan boundaries at such events.  The task {\tt INDXR} can be
used to generate a new {\tt NX} table with scan boundaries at desired
locations using an input text file.  In practice, either {\tt INDXR}
will do the right thing by design, or your P.I. information letter
should have contained instructions on how to construct a text file in
the proper format for {\tt INDXR}\@.

A new task, {\tt \tndx{OBEDT}}, is available which allows selection of
specific orbital parameter ranges, through the creation of an output
flag ({\tt FG}) table.  This can be used to constrain initial fringe
searching.

SVLBI data often contain tracking passes three or four hours in
length, for which fringes are mostly (or wholly) not apparent.
Typically, the space-ground baselines will have the highest
correlation coefficients near perigee, when those baselines are
shortest.  However, the imperfectly known orbit will cause high fringe
rates and short coherence times.  Near apogee, the coherence time is
longer, and may be limited by the atmosphere above the ground
telescopes, but the correlated flux also is much lower.  Sometimes, it
may be possible to find fringes for only 15 or 20 minutes, but that's
better than nothing.

If no fringes are seen anywhere during a tracking pass, a useful trick
is to set {\tt APARM(7) = 0.01} to let through the highest SNR for
each solution interval, and set {\tt DPARM(5) = 1} to turn off the
least squares solution.  Then run {\tt \tndx{FRING}} for an entire
tracking pass, and use {\tt SNPLT} with {\tt OPTYP = 'DELA'} and {\tt
OPTYP = 'RATE'} to look for repeating values (usually easier to see in
delay than in rate).  Also, make plots with {\tt OPTYP = 'SNR'} to see
if slightly higher SNRs are found at a time when there seems to be
some consistency in delay values.  It may be necessary to try this
process with several values of {\tt SOLINT} in order to arrive at a
guess for the fringe location.  Use {\tt VPLOT} to plot \uv\ distance
versus time for the space-ground baselines, then search using the
{\tt TIMERANG} and {\tt REFANT} that provide the shortest projected
baselines.  Another possibility is to set {\tt REFANT = ANTNUM('MK')},
since the atmospheric coherence time should be longest at Mauna Kea,
and increase {\tt SOLINT} to a fairly large value in hopes something
will show up.  (Note, however, that a large {\tt SOLINT} with a
wide-open search window in delay and rate may require a large-memory
computer or great inefficiency due to page faulting.)

If fringes are found somewhere, use {\tt CLCOR} to center the fringes
(see \Sec{PCCORhand}), then run {\tt FRING} again with small delay and
rate windows (\eg\ {\tt DPARM(2) = 200} to 400 and {\tt DPARM(3) = 40}
to 80 at 1.6 GHz, or $\sim 200$ at 5 GHz).  Set low SNR thresholds
with {\tt APARM(7) = 3.5}, and turn the least-squares solutions back
on with DPARM(5)=0.  Usually, it's best to turn on the exhaustive
antenna search with {\tt APARM(9) = 1}, since only a few space-ground
baselines may show fringes.  It can be helpful to use {\tt SEARCH} to
order the search from shortest to longest space-ground baselines.

It generally doesn't work well to use one tracking station to predict
the results of another, because clock initialization offsets are
typically relatively large and have unrelated errors, and fringe-rate
errors also may be unrelated.

\subsubsections{Special considerations: spectral-line}

Delay and fringe-rate \indx{calibration} of \indx{spectral-line}
\Indx{VLBI} data must be handled differently.  The residual delay
cannot be estimated from the source itself because, due to the very
nature of the source, the delay is a rapidly varying function of
frequency.  The continuum calibrator, observed for this purpose, is
first used to determine residual delays and fringe-rates which are
then applied to the spectral-line source.  A suitable channel or range
of spectral-line channels ``on-source'' is then used to determine the
residual fringe-rates.  It is very important to note that in some
situations, the residual fringe-rates determined from the calibrator
may not be applicable to the line source because the fringe-rate
residuals towards the two sources may be quite distinct.  In such
situations, the residual fringe-rates determined from the continuum
source should not be applied to the line source.  See \Sec{lineFRING}
for more details.

\subsubsections{Special considerations: polarization}

In addition to phase calibrating the LL and RR data separately, for
\indx{polarization} data the R-L phase and delay offsets must also be
determined.  This is outlined in \Sec{vlbPCAL}\@.  After
\indx{fringe-fitting}, all parallel-hand fringe solutions need to be
re-referenced to the same antenna.

\vfill\eject
\Subsubsections{Special considerations: phase-referencing}{phaseref}
\iodx{calibration}

The process of \Indx{phase referencing} for \Indx{VLBI} data is
conceptually very simple.  Unfortunately, the technical difficulties
in conducting a successful phase-referencing observation are primarily
in setting up the schedule.  So by the time you get around to reading
this section, your project is either guaranteed to succeed or
guaranteed to fail, depending upon how well your observations were
designed.  See the lecture by A. Beasley and J. Conway in ``VLBI and
the VLBA'', 1995, (ASP), and VLBA Scientific Memo No.~24 (2000, by J.
Wrobel, C. Walker, J. Benson, and A. Beasley) for more details on how
to design phase-referencing observations.

In ``phase referencing,'' the phase calibration for your target source
is derived from a calibrator, or phase referencing, source observed
for that purpose.  First, you apply any available {\it a priori\/}
phase-cals to both the target and cal source.  Next, you fringe-fit,
self-calibrate, and/or hybrid-map the cal source --- whatever is
needed to complete the phase calibration for that source. Finally, you
apply the phase corrections so determined to the target source.  In
practice this is done by specifying the target as well as the cal
source in the {\tt SOURCES} adverb list whenever an {\tt SN} table
containing phase corrections for the cal source is applied using {\tt
CLCAL}\@.  See \Sec{vlbpref} for a specific example of how to run {\tt
CLCAL} to transfer phase corrections determined using a cal source to
a target source.

Certain ``instrumental'' corrections such as those for unmodeled
zenith delay may have subtle but significant effects on phase
referencing.  See \Sec{delzn} for a discussion.

You can perform a ``hybrid'' form of phase referencing in some
instances.  It may be that your target source is too weak for initial
fringe-fitting.  In this case, you can fringe-fit the cal source data
to determine the phase corrections to be applied to the target source
data.  Then, after averaging in frequency, the target source data may
have adequate signal-to-noise to allow rate corrections to be
determined for it by \indx{fringe-fitting}.  In this mode, you may or
may not wish to zero the rate corrections determined on the cal
source.  If the cal source is ``far'' from the target source, the rate
corrections may do more harm than good for the target source and
should be zero'ed.  On the other hand, your target source may be
entirely too weak to fringe-fit on at all.  In this case, you must
rely on determining the phase corrections solely using your cal
source.

If you are attempting phase-referenced astrometry, you may have a
target source that is brighter than your cal source(s).  In this case,
you simply fringe-fit on the target source and transfer the solutions
to the cal source(s).  Be careful, if your goal is to extract absolute
positional information, not to independently self-calibrate the cal
and target sources.

\Subsubsections{Correcting for atmospheric delays}{delzn}

VLBI correlators remove some estimate of the non-dispersive
atmospheric delay at the elevation and frequency of the observation
from the data.  These a priori models are usually fairly good, but
careful observations can improve upon them.
\AIPS\ offers a number of options to deal with this
problem.  {\tt \Tndx{DELZN}} uses \indx{multi-band delay} (see
\Sec{mbd}) in an {\tt SN} table to fit for the zenith tropospheric
delay and  the clocks as a function of time. It works best if the
observations include data on a variety of calibrators well distributed
around the sky.  {\tt DELZN} applies a correction to a {\tt CL} table
or writes a file to disk with zenith atmospheric delays and possibly
clock offsets that can be used by {\tt CLCOR, OPCODE='ATMO'} to
correct a CL table.  The second option is for the situation where the
data used by {\tt DELZN} is in a different file from the data that
needs to be corrected.

To correct an attached {\tt CL} table, the typical inputs for {\tt
\Tndx{DELZN}} would be:
\dispt{TASK\qs 'DELZN' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs {\it n\/} ; GETN {\it ctn\/} \CR}{to specify the
           input file.}
\dispt{SNVER\qs {\it snin\/} \CR}{to select the {\tt SN} table
             containing multi-band delays.}
\dispt{GAINVER\qs {\it clin\/} \CR}{to select the {\tt CL} version to
             which solutions are to be applied.}
\dispt{APARM(4)\qs 1 \CR}{to create a new CL table.}
\dispt{APARM(5)\qs 1 \CR}{to solve for atmosphere and clocks}
\dispt{SOURCES\qs 'DA913' , ' ' \CR}{to specify the sources to be
             corrected.}
\dispt{CALSOUR\qs '0103+337', '0140+412', '0150-334', '0159+418',
'0202+319', '0244-297', '0358+210', '0425+174', '0641+392' \CR}
{to specify the calibrator sources observed at a large variety of elevations}
\dispt{OPTYPE\qs 'MDEL' \CR}{to use multi-band delay}
\dispt{DOTV\qs -1 \CR}{to make {\tt PL} files}
\dispt{GO \CR}{to run the program.}
\dispe{\iodx{calibration}\Todx{DELZN}
This will generate a {\tt CL} table and several {\tt PL} files
that show the data and the fitted model.  You are {\bf strongly
encouraged} to examine these.}

To create an output file rather than correct a {\tt CL} table use
the same inputs as above except:
\dispt{APARM(4)\qs 0 \CR}{to create no {\tt CL} table.}
\dispt{SOURCES\qs ' ' \CR}{to correct no sources}
\dispt{CALSOUR\qs '*' \CR}{to use all calibrator sources.}
\dispt{OUTFILE\qs 'MYVLB:BZ199.DELZN' \CR}{output file name}
\dispe{Again, you are advised to examine the resulting plot files
which show both the data and the fitted model.  The output file can be
read in with {\tt CLCOR (OPCODE='ATMO'; INFILE='MYVLB:BZ199.DELZN')}
to correct a {\tt CL} table.\Iodx{VLBI}}

There is another task designed to deal with the effects of
zenith delay in phase-referencing observations.  Phases for the
target source in phase referencing are corrected by the phases at the
calibrator which usually is at a different elevation.  Task {\tt
DFCOR} is a special version of {\tt CLCOR} which applies the {\tt
'ATMO'} operation to correct the {\tt CL} table for the difference in
elevation between the target source and adjacent calibration sources
without applying the full atmospheric delay correction.

If the {\tt SN} table contains dispersions as well as multi-band
delays, {\tt DELZN} may also be run to fit a zenith angle model to the
dispersions ({\tt OPTYPE = 'DISP'})\@.  Like the {\tt 'MDEL'}
operation, the zenith and time function found by {\tt DELZN} can be
applied to a {\tt CL} table or written to a text file for later
application by {\tt CLCOR} with {\tt OPCODE = 'DISP'}\@.

\Subsubsections{Finding multi-band delays}{mbd}

For astrometric and geodetic experiments and to use {\tt DELZN}
(see \Sec{delzn}\@), the \Indx{multi-band delay} must be determined.
The multi-band delay is the delay caused by errors in the station
positions and the difference between the correlator model and reality
for clocks and the troposphere.  The multi-band delay is best
determined over {\tt IF}s which are widely spaced in the frequency
band.  After the instrumental phases have been corrected
(\Sec{pccor}--\Sec{PCCORhand}), the multi-band delay can be determined
in one of two ways. For strong sources do a global fringe fit as
described in \Sec{fring} setting {\tt APARM(5)=0}\@, and then run {\tt
MBDLY} on the resulting {\tt SN} table.

Typical inputs for {\tt \Tndx{MBDLY}} would be:
\dispt{TASK\qs 'MBDLY' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs {\it n\/} ; GETN {\it ctn\/} \CR}{to specify the
           input file.}
\dispt{INVERS\qs {\it {\tt SN} table from {\it FRING}}}{to select
           input {\tt SN} table}
\dispt{OUTVERS\qs 0\CR}{make new {\tt SN} table}
\dispt{BIF\qs 0; EIF\qs 0\CR}{to select all IFs.}
\dispt{SUBARRAY\qs 0\CR}{to select all subarrays.}
\dispt{APARM\qs 0\CR}{the defaults are generally O.K.}
\dispt{GO \CR}{to run the program.}
\dispe{\iodx{calibration}\iodx{fringe-fitting}\Todx{MBDLY}
This will produce a new {\tt SN} table with the {\tt MBDELAY} columns
filled in.}

For weak sources, use {\tt APARM= 2 0 0 1 1} in {\tt FRING}\@.  This
averages each {\tt IF} and fits a multi-band delay across them.  Note
that this {\it does not} solve for single-band delays, unlike the
previous method.  This will also produce a new {\tt SN} table with the
{\tt MBDELAY} columns filled in.

Note that {\tt MBDLY} can fit the single-band delays for a multi-band
delay plus a dispersion (phase varies with wavelength rather than
frequency) with {\tt OPTYPE = 'DISP'}\@.  {\tt FRING} can do a very
similar fit, after finding the single-band delays, if you set {\tt
APARM(10) = 1}\@.  Wide bandwidth observations at low frequencies may
benefit from this.

%\vfill\eject
\Subsubsections{Antenna-based fringe-fitting}{fring}

\Todx{FRING}
To see an example of the residual phase errors in your data, use {\tt
POSSM} to view the phase on a short calibrator scan (at some time
other than that used to solve for the phase-offsets in
\Sec{PCCORhand}).  In general, there will be a gradient in phase
between the IFs (due to the ``multi-band'' delay) and also small
gradients within each IF (caused by small residual ``single-band''
delays).  These time-variable phase gradients are mainly due to
inaccuracies in the geometrical time delays that the correlator
assumed for the time of arrival of the wavefront at each antenna.
These inaccuracies arise from propagation effects through the
troposphere and ionosphere, inaccurate Earth geometry,  etc.~and give
{\it phase\/} errors which are proportional to frequency.  Such phase
errors prevent integration of the data over frequency (or cause a loss
of coherence if you do).  Similarly, {\tt \tndx{VPLOT}} will show, on
any single IF and spectral channel, phases which change rapidly with
{\it time\/}.   Again, these are due to unavoidable inaccuracies in the
correlator model; such large ``phase rates'' prevent integration over
time.  Both of these points are illustrated in \Rfig{VLBuncal}.
\iodx{fringe-fitting}\Iodx{VLBI}

You will want to run {\tt FRING} to correct for these residual rates.
You can help these tasks by making sure that the reference pixel in
frequency is in the center of the band (Nchan/2+1 is best).  Use task
{\tt \tndx{CENTR}} or any of the tasks with the {\tt \tndx{FQCENTER}}
adverb to fix data sets for which this is not true.

{\tt FRING} and {\tt KRING} use a global fringe-fitting algorithm
described by Schwab and Cotton, 1983, {\it Astron. J.\/}, {\bf 88},
688.  Unfortunately, these are large and complicated tasks.
The procedure {\tt VLBAFRNG} is available
to simplify access to {\tt FRING} and {\tt VLBAKRNG} access to {\tt
KRING}\@.  Versions of these procedures for phase-referencing
experiments are called {\tt VLBAFRGP} and {\tt VLBAKRGP}\@.
For all these procedures, if the {\tt SOURCES} adverb is set, then
{\tt CLCAL} is run once to apply the results of {\tt FRING} (or {\tt
KRING}) for each source in {\tt SOURCES}\@.  For the
phase-referencing procedures ({\tt VLBAFRGP} and {\tt VLBAKRGP}), any
source that is in the {\tt SOURCES} list that is {\it not\/} in the
{\tt CALSOUR} list will be phase referenced to the {\it first} source
in the {\tt CALSOUR} list.  Note that, if every source in the {\tt
SOURCES} list occurs in the {\tt CALSOUR} list, {\tt VLBAFRNG} and
{\tt VLBAKRNG} will run identically to {\tt VLBAFRGP} and {\tt
VLBAKRGP}, respectively. If the {\tt SOURCES} list is empty, {\tt
VLBAFRNG} and {\tt VLBAKRNG} will run {\tt CLCAL} once over all
sources, while {\tt VLBAFRGP} and {\tt VLBAKRGP} will run {\tt CLCAL}
once referencing all the sources to the first source in {\tt CALSOUR}.
These procedures will produce new (highest numbered) {\tt SN} and {\tt
CL} tables.\iodx{fringe-fitting}\iodx{calibration}
\iodx{phase referencing}

Sample inputs for procedure {\tt VLBAKRNG} are:
\dispt{RUN \tndx{VLBAUTIL} \CR}{to acquire the procedures; this should
           be done only once since they will be remembered.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
           input file.}
\dispt{TIMERANG\qs 0}{to include all times.}
\dispt{BCHAN\qs 0 ; ECHAN\qs 0 \CR}{to use all frequency channels.}
\dispt{GAINUSE\qs {\it CLin\/} \CR}{to use the {\tt CL} table with all
           the calibration up to this point.}
\dispt{REFANT\qs {\it n} \CR}{to specify an antenna that is present
           most of the time as the reference antenna.}
\dispt{SUBARRAY\qs 0 \CR}{to use all subarrays.}
\dispt{SEARCH\qs 0 \CR}{to try all antennas as a reference antenna if
           fringes cannot be found using {\tt REFANT}\@.  {\it This is
           different from {\tt FRING}; in {\tt FRING} this must be set
           to try other reference antennas\/}.}
\dispt{OPCODE\qs '\qs' \CR}{to leave all solutions in the output {\tt
           SN} table.}
\dispt{CPARM\qs 0 \CR}{to use defaults for {\tt KRING} steering
           parameters; this is okay for strong sources.}
\dispt{CPARM(1)\qs {\it x\/} \CR}{to specify the minimum integration
           time in seconds.}
\dispt{CPARM(8)\qs 1 \CR}{to avoid re-referencing solutions; do this
           {\it only} for polarization experiments.}
\dispt{CALSOUR\qs '{\it src1\/}', '{\it src2\/}' \CR}{to specify the
           sources to fringe fit using {\tt KRING}.}
\dispt{SOURCES\qs '{\it src1\/}', '{\it src2\/}' \CR}{to have {\tt
           CLCAL} run for each source using the interpolation method
           given below.}
\dispt{INTERPOL\qs 'AMBG' \CR}{to use the ``{\tt AMBG}'' interpolation
           method (linear phase connection using rates to resolve
           phase ambiguities).}
\dispt{BADDISK\qs 0 \CR}{to use all disks for scratch files.}
\dispt{VLBAKRNG \CR}{to run the procedure.}
\pd

Procedure {\tt VLBAKRGP} sets the same adverbs as {\tt VLBAKRNG} {\it
except\/}\Iodx{VLBI}
\dispt{SOURCES\qs '{\it src1\/}', '{\it src2\/}', '{\it src3\/}'
         \CR}{to have {\tt CLCAL} run for each source using the
         interpolation method given by {\tt INTERPOL}\@. Any source
         here that is not in the {\tt CALSOUR} list will be phase
         referenced to the first source in the {\tt CALSOUR} list.  In
         this example, {\it src3\/} is phase referenced to {\it
         src1\/}.}
\dispt{VLBAKRGP \CR}{to run the procedure.}
\pd

{\tt VLBAFRNG} and {\tt VLBAFRGP} are identical except there is no
{\tt OPCODE} (it is equivalent to {\tt DPARM(8)}) and {\tt DPARM(4)}
and {\tt DPARM(7)} in {\tt FRING} are the same as {\tt CPARM(1)} and
{\tt CPARM(8)} in {\tt KRING}, respectively.  Also note the different
use of {\tt SEARCH} in {\tt FRING} and {\tt KRING}\@.

Suitable inputs for the fringe-fitting task {\tt FRING} are, in
detail:
\dispt{TASK\qs 'FRING' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs {\it n\/} ; GETN {\it ctn\/} \CR}{to specify the
                 input file.}
\dispt{CALSOUR\qs ' ' \CR}{to find solutions for all sources.}
\dispt{TIMER\qs 0 \CR}{to find solutions for all times.}

\begin{figure}[t]
\centering
%\resizebox{!}{3.8in}{\gname{cook9a}\hspace{0.8cm}\gname{cook9b}}
\resizebox{!}{3.8in}{\gbb{489,649}{cook9a}\hspace{0.8cm}\gbb{527,546}{cook9b}}
\caption[{\tt POSSM} and {\tt VPLOT} displays of uncalibrated VLBI
data]{{\it left:\/} A {\tt \tndx{POSSM}} plot of the 43-GHz spectrum
of the quasar NRAO150 on the Los Alamos to Kitt Peak baseline. The
plot shows that the observation was performed with 4 IFs, with 256
spectral channels within each IF\@.  The upper frame shows the phase
variation with frequency; within each IF, the small phase slope is
caused by a residual delay error.  The phase offsets between the IFs
can be clearly seen as well.  Both the residual delay error and the
phase offsets must be determined and removed before the data can be
spectrally averaged (see \Sec{phasecal}).  {\it right:\/} A {\tt
\tndx{VPLOT}} plot of the uncalibrated amplitude (upper frame) and
phase (lower frame) as a function of time for the source NRAO150 at 43
GHz on the baseline Kitt Peak to Mauna Kea. Note how the phase varies
as a function of time; this variation is equivalent to a residual
fringe rate of 8.3 mHz.  Unless the fringe rate is determined and
removed (see \Sec{phasecal}), the data cannot be averaged in time.}
\iodx{calibration}\iodx{fringe-fitting}\Iodx{VLBI}
\label{fig:VLBuncal}
\end{figure}
\dispt{DOCALIB\qs 1 \CR}{to apply the most complete calibration file
        including amplitude calibration and IF and channel phase
        offsets to both the visibilities and the weights.}
\dispt{GAINUSE\qs 3 \CR}{to use {\tt CL} table 3.}
\dispt{SNVER\qs 2 \CR}{to write solutions into {\tt SN} table 2.}
\dispt{BCHAN\qs 0; ECHAN\qs 0 ; CHINC\qs 1\CR}{to use all spectral
        channels within each IF channel.}
\dispt{FLAGVER\qs 0 \CR}{to apply the most recent flag table.}
\dispt{SMODEL\qs 0 ; CLR2NAME\CR}{to use a point-source at the origin
        model for the sources, rather than a Clean-component model.}
\dispt{SOLINT\qs 3 \CR}{to set the solution interval in minutes; do
        not exceed the atmospheric coherence time (see below).
        Setting {\tt SOLINT} to 0 sets solution intervals equal to
        scan lengths.}
\dispt{SEARCH\qs {\it ref2\/}, {\it ref3\/}, ...\CR}{to specify the
        order over which antennas are searched for fringes when the
        exhaustive search is requested.  If {\tt APARM(9)} is set, all
        antennas will be searched for fringes with {\tt SEARCH}
        controlling the order of the search.  Note, {\tt REFANT} should
        be {\tt SEARCH(1)}\@.  The use of {\tt APARM(9)} and {\tt
        SEARCH} makes {\tt FRING} much more likely to find fringes to
        weak antennas and is highly recommended.}
\dispt{APARM(1)\qs 2 \CR}{to accept solutions when only 2 antennas are
        present; default is 6.}
\dispt{APARM(2)\qs 0 \CR}{to have the data divided by the model before
        fitting fringes; {\tt APARM(2) > 0} tells {\tt FRING} that
        the data have already been divided by a model.}
\dispt{APARM(3)\qs 0 \CR}{to treat polarizations separately; {\tt
        APARM(3) > 0} averages RR and LL\@.}
\dispt{APARM(4)\qs 0 \CR}{to use the frequencies individually within
        each IF; {\tt APARM(4) > 0} causes the frequencies within
        each IF to be averaged before the solution.}
\dispt{APARM(6)\qs 1 \CR}{to get some useful, but limited, messages,
        including the SNR\@.}
\dispt{APARM(7)\qs 9 \CR}{to avoid false detections by setting a
        moderately high minimum for the SNR accepted.  You may wish to
        use a lower threshold (especially for SVLBI) although {\tt
        APARM(7)} less than about 3 is probably not useful.}
\dispt{APARM(8)\qs 0 \CR}{to set the maximum number of antennas (if no
       {\tt AN} table).}
\dispt{APARM(9)\qs 1 \CR}{to enable the exhaustive search mode.}
\dispt{APARM(5)\qs 0 \CR}{to do least-squares fits in each IF\@.  {\tt
        APARM(5)} $\leq$ 0 means to solve separately for the rate,
        single band delay and phase of each IF\@.  $1.5>$ {\tt
        APARM(5)} $>0$ means to solve for one single rate and
        multi-band delay affecting all IFs.  If $2.5 >$ {\tt APARM(5)}
        $>1.5$, the task additionally solves for the difference
        between the multi-band delay and single-band delay, \ie\ it
        allows for a different gradient of phase versus frequency
        within an IF than between IFs.  Note, however, that unlike
        {\tt APARM(5)=0}, this option assumes that the single-band
        delay is the same in each IF; it therefore solves for a single
        value for the difference between multi-band and single-band
        delay affecting all IFs.  Normally users should use {\tt
        APARM(5)=0} for multi-IF data.  Primarily for the VLA, a
        fourth option, {\tt APARM(5) = {\it M}} has been added, with
        $M > 2$.  It divides the IFs into $M - 1$ groups and solves
        for one delay per group.\Todx{FRING}\Iodx{VLBI}}
\dispt{REFANT\qs 5 \CR}{to choose an antenna that will give fringes
        for most of the scans.  This is important: {\tt FRING}
        will \iodx{calibration}\iodx{fringe-fitting} search
        for fringes to this antenna first.  If it fails for some
        reason, it will select another reference antenna, based on the
        {\tt ANTWT} data, and, if it still fails, give up (see however
        the discussion of the new {\tt SEARCH} adverb above).  In this
        case, you should look for scans with no fringes or a bad
        reference antenna may be causing the problem.  A big,
        sensitive antenna is often used as {\tt REFANT} (\eg\
        Effelsberg).  Occasionally, it may be helpful to split your
        data set up into 2 or 3 sections, which are fringe-fitted with
        different {\tt REFANT} (\eg\ a ``European'' and a ``US'' part
        of the observations).  Changes in reference antenna should, in
        general, not cause problems.}
\dispt{ANTWT\qs 0 \CR}{to apply no additional weights to the antennas
        before doing the solutions.  If the amplitude calibration was
        incorrect, you can use this option to force antenna weights up
        or down to control the weight {\tt FRING} gives to data to
        each station when making the global solutions.  Unless the
        {\tt SEARCH} option described above is chosen, {\tt ANTWT}
        also controls the order in which antennas are tried as
        secondary reference antennas after failing to find fringes on
        the {\tt REFANT}\@.  Give higher weight to antennas you want
        to see used as secondary references.\Iodx{VLBI}}
\dispt{ANTENNAS\qs 0; DOFIT\qs 0\CR}{to allow all antennas to be fit.
        Only baselines between antennas listed in the {\tt ANTENNAS}
        adverb are used in the fringe search.  If any antennas are
        specified in {\tt DOFIT} however, a solution is made only for
        those antennas; all other selected antennas are assumed to be
        already calibrated and are passed through with no additional
        corrections.  See the {\tt HELP} file for {\tt FRING} under
        {\tt DOFIT}\@.  {\bf {\tt DOFIT} is only active if {\tt
        APARM(9)} is set.}\iodx{calibration}\iodx{fringe-fitting}}
\dispt{DPARM(1)\qs 1 \CR}{to use one baseline combination in the
        initial coarse (FFT) fringe search.  This provides a starting
        guess for the least-squares solution.  If you are searching
        for weak fringes you should consider using two and three
        baseline combinations in the search; this can improve
        sensitivity in the initial fringe search.  See Lecture 19 in
        {\it \jndx{Synthesis Imaging in Radio Astronomy}\/}, edited by R.
        Perley, F. Schwab, and A. Bridle, for an explanation
        of how this global multi-baseline searching works.  Note that
        if your source structure is complex and you have not divided
        the data by an accurate source model, then setting this
        parameter to one is safest. {\tt DPARM(1)>1} works even when
        the integration times are not equal.}
\dispt{DPARM(2)\qs 0 \CR}{to set the full width of the delay window in
        nsec, centered around 0, to search; the default, chosen here,
        is to use the full Nyquist range defined by the frequency
        spacing.  A smaller search window can permit a lower SNR
        threshold to be set, but can also result in lost data due to
        failed fringe searches. For the VLBA, a {\tt DPARM(2) = 1000}
        window is usually adequate. }
\dispt{DPARM(3)\qs 0 \CR}{to set the full width of the fringe-rate
        window in mHz, centered around 0; the default, chosen here, is
        to use the full Nyquist range defined by the integration time.
        A smaller search window can permit a lower SNR threshold to be
        set, but can also result in lost data due to failed fringe
        searches.  For the VLBA, a {\tt DPARM(3) = 200} window is
        usually adequate.}
\dispt{DPARM(4)\qs 2 \CR}{to specify the correlator integration time
        in seconds; use {\tt \Tndx{GETITIME}} or {\tt DTSUM} to find
        the correct value.  For data from the VLBA correlator, {\tt
        DPARM(4)=0} will cause {\tt FRING} to determine the correct
        integration time by examining the data file directly.}
\dispt{DPARM(5)\qs 0 \CR}{to do both the coarse and the least squares
        solutions; set to 1 if you require only FFT solutions.}
\dispt{DPARM(6)\qs 1 \CR}{to keep, for single-source files,
        frequencies separated in the output file; the default is to
        average frequencies within IFs. This parameter does not affect
        multi-source files.}
\dispt{DPARM(7)\qs 0 \CR}{to re-reference solutions to a common
        reference antenna;  when processing polarization data, set
        this to 1 to avoid the re-referencing.}
\dispt{DPARM(8)\qs 0\CR}{to disable the zero'ing options --- see
        the {\tt HELP} file.  {\it WARNING, {\tt DPARM(8) > 0} will
        discard parts of the final solution.  Be sure to use this
        option with extreme care}.}
\dispt{DPARM(9)\qs 0\CR}{to allow fitting for rate.  {\tt DPARM(9)}$ >
        0$, causes the task to suppress rate fitting entirely rather
        than zeroing it after the fact as in {\tt DPARM(8)}\@.}
\dispt{INP \CR}{to check the inputs.}
\dispt{GO \CR}{to do the fit --- finally.}
\dispe{Note that {\tt \Tndx{FRING}} finds solutions in two steps.
First approximate solutions are found in the FFT step using
combinations of one, two, or three baselines (see {\tt DPARM(1)}
above).  Then, as long as {\tt DPARM(5) < 1}, a least-squares
algorithm uses these approximate values as a starting point for
refining the solutions.  Especially for weak sources, the least-square
solution may wander outside narrow constraints set by {\tt DPARM(2)}
and {\tt DPARM(3)}.}
\iodx{calibration}\iodx{fringe-fitting}\Iodx{VLBI}

Note that the {\tt \tndx{SOLINT}} interval should be selected with
consideration of the atmospheric coherence time, but must be long
enough that high signal-to-noise-ratio solutions are achieved.
For observations between 1.6 and 15 GHz, solution intervals of 3--6
minutes (and often longer) should be fine.  At other frequencies
shorter solution intervals may be required.  In these cases,
experiment with different length solution intervals on short sections
of data.  Note that solution intervals greater than the scan length
will never be used; the scan lengths are listed in the {\tt NX} table
and may be examined using {\tt PRTAB} or {\tt LISTR} with {\tt
OPTYPE='SCAN'}, or {\tt LISUN}\@.

If the source is complex, and especially if the visibility phase of
the source changes during {\tt SOLINT}, it is useful to divide the
data by a Clean model derived from previous observations or from an
earlier attempt at processing the data.  This Clean model can be
specified by filling in {\tt IN2NAME} {\it et al}.  Situations where
this is useful include observations of equal doubles (where there are
zeros in the amplitude and, hence, rapidly changing phases) or very
large sources (of order arcseconds).  If you are using multi-baseline
searching (\ie\ {\tt DPARM(1) > 1}), then solutions may be more
sensitive to source structure and an input model may be useful if the
structure phases are larger than one radian on many baselines.  When
using a model, convergence may be improved by weighting the data by
$1/\sigma$ rather than $1/\sigma^2$; set {\tt WEIGHTIT = 1}\@.

You should check the SNRs found by {\tt FRING} carefully; they are
printed if {\tt APARM(6) > 0}.  The SNRs estimated during the FFT
search are used to determine if the SNR of a solution is $\ge$ the
threshold set in {\tt APARM(7)}\@.  If they are not, then that
solution is flagged before being passed to the more accurate
least-squares routine.  Users should check that the SNRs found in the
LSQ routine match those expected.  If the detected SNRs are too low,
{\tt SOLINT} may be too long or too short or other parameters may be
set wrongly.

Be warned that proper scaling of the SNRs by {\tt FRING} depends upon
whether or not the data weights have been properly calibrated.  Task
{\tt FIXWT} may be used to calibrate the weights, but changing the SNR
threshold for {\tt \Tndx{FRING}} directly ({\tt APARM(7)}) usually
produces satisfactory results.

The final delay and rate solutions and their SNRs should be inspected
using {\tt \tndx{LISTR}}:
\dispt{TASK\qs 'LISTR' ; INP \CR}{to review the inputs.}
\dispt{INDISK {\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
          input file.}
\dispt{OPTYPE\qs 'GAIN' \CR}{to list gain solutions.}
\dispt{INEXT\qs 'SN' ; INVER\qs 2 \CR}{to list {\tt SN} table 2 (as
          above).}
\dispt{DPARM\qs 6, 0 \CR}{to list delay; use 7 for rate, 1 for phase,
          and 8 for SNR\@.}
\dispt{GO \CR}{to run the program.}
\dispe{Alternatively, the solutions can be plotted against time to
make sure they are sensible.  Use {\tt SNPLT}:}
\dispt{TASK\qs '\tndx{SNPLT}' ; INP \CR}{to review the inputs.}
\dispt{INDISK {\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
            input file.}
\dispt{OPTYPE\qs 'RATE'\qs ; DOBLANK\qs 1\qs\CR}{to plot rate
           solutions including failed ones, {\tt OPTYPE 'DELA'} for
           delay solutions.}
\dispt{OPCODE\qs ' ' \CR}{to plot each polarization and IF in separate
           plots.}
\dispt{NPLOTS\qs 5 \CR}{to plot five antennas/IFs/polarizations per
           page.}
\dispt{INEXT\qs 'SN' ; INVER\qs 2 \CR}{to plot {\tt SN} table 2 (as
          above).}
\dispt{GO \CR}{to run the program.}
\pd
\iodx{calibration}\iodx{fringe-fitting}\Iodx{VLBI}

It is a good idea to plot the solutions for {\tt OPTYP 'RATE'} and
{\tt 'DELA'} (single-band delay) as well as the associated {\tt
'SNR'}s.  They should be smoothly varying functions.  Delays and rates
should be found only within your specified windows.  Check for
suspicious detections at the limits of the search windows --- for
instance, they could be detections of side lobes of the main fringe.
If you used windows smaller than Nyquist, you may want to check your
detections using bigger windows.  Gaps in detections with time can
occur if, \eg\ tapes were bad, antennas were off source, the source
visibility is in a minimum, or the reference antenna choice was bad.
It pays to investigate such problems at this point before proceeding.

Discrepant {\tt SN} solutions can be removed using the interactive
task {\tt \tndx{SNEDT}} or the non-interactive task {\tt
\tndx{SNSMO}}\@.  If, in the latter, the {\tt CPARM} values are set,
then the {\tt SN} solutions will be clipped if they differ from the
running mean by amounts which you can specify.  If the {\tt BPARM}
values are set, the solutions are then smoothed and clipped entries
can be replaced with mean values based on a boxcar- or
median-window-filter average.  See the explain file for details.
Although {\tt SNSMO} allows the option of modifying the input {\tt SN}
table, it is safest to have it create a new one.  If you have a lot of
discrepant {\tt SN} values, you should also consider using option {\tt
INTERPOL = 'POLY'} in task {\tt CLCAL} (see below).

If there isn't enough disk space to run {\tt FRING} on all the data at
once (because of the large scratch file that {\tt FRING} insists on
creating), you can run {\tt FRING} multiple times specifying time
ranges and explicitly setting {\tt SNVER} to the same {\tt SN} table.
Judicious use of {\tt CHINC} when your spectral channels are narrow
($< 0.5$ MHz) may also help with disk space and compute time.

If, for some reason, you set the parameters of {\tt FRING} or
{\tt SNSMO} wrongly and the resulting {\tt SN} table is unusable, it
is wise to avoid confusion by deleting it using {\tt EXTDEST} and
starting over again.\Iodx{VLBI}

\begin{figure}
\centering
%\resizebox{!}{3.2in}{\gname{cook9c}\hspace{1cm}\gname{cook9d}}
\resizebox{!}{3.2in}{\gbb{489,641}{cook9c}\hspace{1cm}\gbb{489,641}{cook9d}}
\caption[Spectrum before and after calibration]{{\it left:\/} A {\tt
\tndx{POSSM}} plot of the uncalibrated spectrum of NRAO150 at 43 GHz
on the baseline Kitt Peak to Los Alamos. The plot shows the spectrum
for a single IF to show the effects of the residual delay error more
clearly.  The phase slope as a function of frequency is clear evidence
for a small delay error in the correlator model.  {\it right:\/} The
same data as shown on the left, but corrected for a delay error of -55
nanosec and a residual fringe-rate of -2.0 milliHz.  Note how the
phase as a function of frequency is now flat and centered around zero
degrees.  These data can now be averaged in frequency, if desired.
\iodx{calibration}\iodx{fringe-fitting}}
\label{fig:VLBbeforeafter}
\end{figure}

Once a valid {\tt SN} table has been produced, the next step is to
interpolate the solutions found onto the finer grid of entries in a
{\tt CL} table using the task {\tt CLCAL} with {\tt INTERPOL = 'AMBG'}
as described in \Sec{vlbapply}.

Once a final {\tt CL} table is generated, its effect on the data can
be viewed using tasks {\tt \tndx{VPLOT}} and {\tt POSSM} by setting
{\tt DOCAL=1} and {\tt GAINUSE} to the version number of the final
{\tt CL} table; see \Sec{vlbexam}.  Optionally, in {\tt VPLOT}, one
can average over spectral channels and/or IF channels before plotting.
Use {\tt VPLOT} to plot a time range covering a few {\tt FRING}
solution intervals on a strong source.  Phase variations should be
small with no jumps.  If this is not the case, check the inputs to
{\tt FRING} (especially {\tt SOLINT}) and {\tt CLCAL}\@.  A comparison
of before and after phases is shown in \Rfig{VLBbeforeafter}.
\iodx{calibration}

\Subsubsections{Baseline-based fringe-fitting}{bling}

Baseline-based \indx{fringe-fitting}, implemented in {\tt
\Tndx{BLING}} and {\tt BLAPP}, is an alternative to using {\tt FRING}
and {\tt CLCAL} described above.  Whereas {\tt FRING} searches and
solves for station rates and delays globally, {\tt BLING} makes
independent fits to each baseline for delays and rates, creating a
{\tt BS} table of baseline-based solutions.\Iodx{VLBI}

In most cases, the global fringe-fitting described in \Sec{fring}
should be used since {\tt FRING} should be able to fringe-fit weaker
sources more reliably.  However, there are some instances in which
baseline-based fringe-fitting is to be preferred.  Note that {\tt
FRING} may be used to do baseline-based fringe-fitting by running it
many times, each time specifying only 2 antennas.  {\tt BLING} has not
been actively maintained or used, and so may be less reliable.
Amongst the advantages of the baseline-based fringe-fitting are:
\xben
\Item {\tt BLING} may be more robust than {\tt FRING} even in the
     absence of an accurate source structure model.
\Item Fringe solutions can be found for cross-polarized fringes
     without editing the \uv\ header.
\Item As presently implemented, for a given number of IF and spectral
     channels, {\tt BLING} can  solve for longer scans than can {\tt
     FRING}\@.
\Item {\tt BLING} has the option of adjustable, non-zero centered
     fringe-search windows, which can be controlled from an external
     file.  This option may be important in fringe-fitting Space VLBI
     data.
\xeen

{\tt BLING} is distinguished from {\tt FRING} by the ability to
directly control the fringe search on each separate baseline, and by
the ability to solve for fringe acceleration if required. Separate
fringe windows in delay, rate and acceleration, and different solution
intervals can be set for each individual baseline. The fringe windows
may have non-zero offsets and can be specified using the input adverbs
or, more flexibly, by drawing up an external ASCII control file of
fringe-prediction windows and {\tt BLING} control parameters. The
latter option allows the specification of time-variable fringe-search
parameters across the observing file. The general algorithm follows
that described by Alef and Porcas, 1986, ({\it Astron. Astrophys.\/},
{\bf 168}, 365); {\tt BLING} also allows the stacking of data from
different baselines, as discussed by Schwab and Cotton, 1983, {\it
Astron. J.\/}, {\bf 88}, 688. In addition, model division is possible
before the fringe-fitting is performed and cross-polarized fringe
searches can also be conducted without editing the \uv\ header.  {\tt
BLING} writes the results to a {\tt BS} table. These baseline-based
solutions can be converted into antenna-based corrections using the
separate task {\tt \tndx{BLAPP}} and then applied to the data.

Acceleration may be solved for by conducting a coarse search in the
specified acceleration window. The results of this search are then
interpolated to estimate the final solution. Fringe acceleration
searches can considerably increase the amount of CPU time it takes to
run {\tt BLING}\@.  Therefore, you may wish to turn off the
acceleration search ({\tt DPARM(7)} to {\tt DPARM(9)}) unless you need
it for space VLBI\@.
\iodx{calibration}\iodx{fringe-fitting}\Iodx{VLBI}

Full details concerning {\tt BLING} input parameters can be found by
typing {\tt EXPLAIN BLING}\@.  This includes information concerning
the format required for the external control file.  Earlier versions
of {\tt BLING} are discussed in \AIPS\ Memo~89 (1994,
``Baseline-Oriented Fringe Searches in \AIPS'' by Chris Flatters).
Typical input parameters to {\tt BLING} are given below:
\dispt{TASK\qs 'BLING' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
        input file.}
\dispt{CALSOUR\qs 'DA193', ' ' \CR}{to specify the calibrator source.}
\dispt{STOKES\qs 'LL' \CR}{to select the Stokes.}
\dispt{TIMERANG\qs 0, 10, 5, 0, 0, 11, 0, 0 \CR}{to limit the time range.}
\dispt{ANTENNAS\qs 3 ; BASELINE\qs 0 \CR}{to select all baselines to
         antenna 3.}
\dispt{SUBARRAY\qs 1 \CR}{to use subarray 1.}
\dispt{FREQID\qs 1 ; BIF\qs 1 ; EIF\qs 0}{to use frequency ID 1 with
         all IFs.}
\dispt{BCHAN\qs 1 ; ECHAN\qs 0 \CR}{to use all spectral channels.}
\dispt{DOCAL\qs 1 ; GAINUSE\qs {\it clin\/} \CR}{to apply amplitude
          calibration before fringe fitting.}
\dispt{CLR2N ; NMAPS\qs 0 \CR}{to do no model division.}
\dispt{SOLINT\qs 0.5 \CR}{to use a 30-second fringe solution interval.}
\dispt{INFILE\qs ' ' \CR}{to use the adverbs rather than an external
           control file.}
\dispt{APARM(1)\qs 2 ; APARM(2)\qs 0\CR}{to set the integration time;
           no model division.}
\dispt{APARM(3)\qs 0\CR}{to do no stacking of baselines.}
\dispt{APARM(4)\qs 0 ; APARM(5)\qs 0\CR}{to set minimum acceptable SNR to
           5 and accept coherence of 20\%}
\dispt{DPARM\qs 0 \CR}{to use the default fringe windows and no
           acceleration search.}
\dispt{DOUVCOMP\qs 1 \CR}{to use compressed scratch files.}
\dispt{BADDISK\qs 0}{to use all disks for scratch files.}
\dispt{GO \CR}{to run the program.}
\pd

Note that baseline-stacking ({\tt APARM(3)}) is not implemented for
data sets with unequal integration times. Also, note that the
fringe-rejection criteria specified using {\tt APARM(4)} and {\tt
APARM(5)} are important parameters.  The use of compressed scratch
files is recommended and is not believed to have a significant impact
on precision. Note, if model division is required, {\tt APARM(2)}
should be set and the source should be entered explicitly.

{\tt BLING} will execute with a summary line marking the start of each
baseline processed. The resulting {\tt BS} table can be examined using
task {\tt BSPRT}, with input parameters:
\dispt{TASK\qs '\tndx{BSPRT}' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
         input file.}
\dispt{INVERS\qs {\it bsin\/} \CR}{to specify the {\tt BS} table
         version number.}
\dispt{DOCRT\qs -1 \CR}{to send output to an external file.}
\dispt{OUTPRINT\qs 'FITS:BSPRT.LIS' \CR}{to define the output file name.}
\dispt{GO \CR}{to run the program.}
\dispe{For printing to the screen, select {\tt DOCRT=1}.}
\iodx{calibration}\iodx{fringe-fitting}

The {\tt BS} table output includes the estimated fringe parameters and
their associated errors. Note that due to changes in FFT interpolation
the errors may be an overestimate. The {\tt BLING} solutions are
interpolated and factorized into antenna-based gain solutions using
{\tt BLAPP}\@.  This task either writes a solution ({\tt SN}) table
which can be applied using {\tt CLCAL}, or allows a {\tt CL} table to
be updated with the calibration information directly.  These options
are selected using {\tt OPCODE='SOLV'} or {\tt OPCODE='CAL'}
respectively. {\tt BLAPP} can interpolate solutions with unequal time
sampling and includes the acceleration term in interpolation if it is
available.  Typical inputs to {\tt \Tndx{BLAPP}} are:\Iodx{VLBI}
\dispt{TASK\qs 'BLAPP' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
           input file.}
\dispt{INVERS\qs {\it bsin\/} \CR}{to specify the input {\tt BS} table
           version number.}
\dispt{SOURCES\qs ' ' ; STOKES\qs 'LL' \CR}{to do all sources and a
           specific Stokes.}
\dispt{FREQID\qs 1 \CR}{to select frequency ID 1.}
\dispt{TIMERANG\qs 0 ; ANTENNAS 0 \CR}{to do all times and antennas.}
\dispt{SUBARRAY\qs 1 ; REFANT\qs 3 \CR}{to do subarray 1 with
           reference antenna 3.}
\dispt{ANTWT\qs 0 \CR}{to use equal antenna weights.}
\dispt{OPCODE\qs 'SOLV' \CR}{to solve for a {\tt SN} table.}
\dispt{GAINVER\qs {\tt clin} \CR}{to specify the input {\tt CL} table
           which defines the times for which solutions are desired.}
\dispt{BADDISK\qs 0 \CR}{to use all disks for scratch files.}
\dispt{GO \CR}{to run the program.}
\dispe{The resulting solution ({\tt SN}) table can be plotted using
{\tt SNPLT} in the standard fashion.  For {\tt OPCODE='CAL'} the
output {\tt CL} table also needs to be specified using {\tt
GAINUSE}\@.  If an {\tt SN} table is generated, it can be smoothed or
clipped using task {\tt SNSMO} and applied using {\tt CLCAL} as
described in \Sec{vlbapply}.
\iodx{calibration}\iodx{fringe-fitting}}

% \vfill\eject  % ??
\Subsubsections{SVLBI-specific techniques}{gphas}

An alternative approach to direct fringe detection of each individual
baseline to the orbiting antenna is to first calibrate the ground
array using conventional fringe-fitting techniques, then coherently
combine all ground antennas to improve the fringe detection
sensitivity to the spacecraft.  Several incarnations of this approach
exist within \AIPS\@.  The \AIPS\ tasks {\tt FRING}, {\tt BLING}, and
{\tt KRING} all allow baseline stacking which can be used to fringe
fit the space baseline using composite baselines.  It was shown in
VLBA Scientific Memo No.~13 (1996, ``Global ground VLBI network as a
tied array for space VLBI'', by L. Kogan) that the method of phasing a
group of ground-based antennas and the method using global fringe
fitting with baseline stacking give the same minimum detectable flux
density.  Therefore, baseline stacking with {\tt DPARM(1)=3} in {\tt
FRING} should yield the best possible sensitivity.  There are other
options which also may be explored.  The adverb {\tt DOFIT} in {\tt
\Tndx{FRING}} and {\tt KRING} can be used to solve for subsets of the
available antennas in order to find good solutions for the ground
antennas in a dual round of fringe-fitting.  The exhaustive baseline
search mode, used by default in {\tt BLING} and {\tt KRING} and
activated in {\tt FRING} by setting {\tt APARM(9)=1}, allows more
baselines to the spacecraft to be searched.\iodx{SVLBI}

\Subsubsections{Spectral-line fringe-fitting}{lineFRING}

\Todx{FRING}
The determination of the delay and fringe-rate \indx{calibration} is a
two- or three-step process for \indx{spectral-line} \Indx{VLBI} data.
First, the residual delay and fringe-rates are estimated for each
antenna from the continuum calibrators.  Then, residual fringe-rates
must be determined again for the line source using a ``strong''
channel or range of channels.  As an intermediate step, the phases of
the line source should be examined to check that the calibrator's
residual fringe-rates haven't destroyed phase coherence; if so, then
the calibrator's residual fringe-rates should not be applied to the
line source.\iodx{fringe-fitting}

If computer memory is limited, {\tt FRING} must trade off the number
of spectral channels against the length of the solution interval.  For
continuum calibrators in a spectral-line dataset, the large number of
spectral channels may force {\tt FRING} to require too short a
solution interval.  Judicious use of {\tt CHINC} in {\tt FRING} reduces
this problem for spectral channels $< 0.5$ MHz in width.  ({\tt FRING}
now allocates memory dynamically and may be able to handle large cases
so long as the computer is adequately equipped with real and swap
memory.)  This limit can be overcome by running {\tt UVCOP} to extract
the continuum calibrators into a separate data file and then running
{\tt AVSPC} with {\tt AVOPTION 'SUBS'} to average spectral channels
coherently within each IF\@. {\tt INDXR} should be run to regenerate an
{\tt NX} table. {\tt FRING} will then allow more reasonable solution
intervals.

Run {\tt FRING} as follows only on the continuum calibrators to
determine residual delays and fringe-rates:
\dispt{TASK\qs 'FRING' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs {\it n\/} ; GETN {\it ctn\/} \CR}{to specify the
            input file.}
\dispt{CALSOUR\qs 'BLLAC','DA193' \CR}{to select continuum calibrator
            sources.}
\dispt{DOCALIB\qs 1 \CR}{to apply the current calibration.}
\dispt{GAINUSE\qs {\it clin\/}}{to specify which {\tt CL} table to
            use.}
\dispt{SMODEL\qs 0 \CR}{to use the null source model (points at the
            origin).}
\dispt{FLAGVER\qs 0 \CR}{to apply the most recent flag table.}
\dispt{BCHAN\qs 10 ; ECHAN\qs 115 \CR}{to exclude the edges of the
            band; normally the data in these channels are corrupted by
            the bandpass filters.}
\dispt{REFANT\qs 5 \CR}{to select a reference antenna (see continuum
            discussion).}
\dispt{SOLINT\qs 6 \CR}{to set the solution interval in minutes.  It
            should not exceed the coherence time.}
\dispt{APARM(6)\qs 1 \CR}{to get some useful, but limited, printout;
            gives SNR\@.}
\dispt{APARM(7)\qs 7 \CR}{to avoid false detections by setting the
            minimum acceptable SNR\@.  {\it Warning:\/} solutions with
            lower SNR will be flagged as bad which will ultimately
            flag the affected data.}
\dispt{DPARM(1)\qs 1 \CR}{to use one-baseline combination in initial,
            coarse fringe search (FFT)\@.  This provides starting
            points for the least-squares solutions.}
\dispt{DPARM(2)\qs 10000 \CR}{to select a delay window in nsec,
            centered around 0(!). The default is to use the Nyquist
            range.  For a 250 kHz-bandwidth observation, setting this
            value to 10000 nsec is equivalent to setting the search
            window to 5 delay channels, which is usually sufficient.}
\dispt{DPARM(3)\qs 200 \CR}{to select a fringe-rate window in mHz.}
\dispt{DPARM(4)=\qs 1 \CR}{to tell {\tt FRING} the correlator
            integration time.}
\dispt{DPARM(5)\qs 0 \CR}{to do the least-squares solution.}
\dispt{SNVER\qs 0 \CR}{to write solutions in a new {\tt SN} table.}
\dispt{GO \CR}{to do the fit.}
\iodx{calibration}\iodx{spectral-line}\iodx{fringe-fitting}
\dispe{If the calibrators had been extracted to a separate data set,
use {\tt TACOP} to copy the resultant {\tt SN} table back to the line
data set.  {\tt \tndx{SNCOP}} may be used when the
number of IFs in the two data sets is different.  This is more likely
to arise when you use a strong line signal in one IF to solve for the
delays of a larger data set.}

Run {\tt CLCAL} to apply the delay and fringe-rate solutions to all
sources, as is described in \Sec{vlbapply}, and then carefully examine
the phase coherence of the line source in a suitable line channel (or
group of channels) using {\tt POSSM} or {\tt \tndx{COHER}} before and
after applying the new {\tt CL} table.  It may be that the fringe-rate
solutions have made the phase coherence worse.  In this case, you must
run {\tt SNCOR} using the {\tt 'ZRAT'} option to zero the fringe-rates
and then re-run {\tt CLCAL}\@.

After this point, the calibrator data is usually of little or no
interest.  But, if you do plan to use the calibrator data further,
remember to be careful to juggle the {\tt SN} and {\tt CL} tables
correctly.  Even if you decide not to apply the calibrator
fringe-rates to the line-source, they are still applicable for the
calibrator itself.  The {\tt CL} table created using the un{\tt
'ZRAT'}-ed {\tt SN} table contains the proper corrections for the
calibrator data while the {\tt CL} table created using the {\tt
'ZRAT'}-ed {\tt SN} table contains the proper corrections for the
line source.

Now re-run {\tt \Tndx{FRING}} to determine the residual fringe-rates
for the line source, this time selecting a suitable line channel or
group of channels:\Iodx{VLBI}
\dispt{TASK\qs 'FRING' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs {\it n\/} ; GETN {\it ctn\/} \CR}{to specify the
            input file.}
\dispt{CALSOUR\qs 'OH127.8' , '\qs ' \CR}{to select the spectral-line
            source.}
\dispt{DOCALIB\qs 1 \CR}{to apply the previous amplitude and
            delay/rate calibration.}
\dispt{GAINUSE\qs {\it clin\/}}{to specify which  {\tt CL} table to
            use.}
\dispt{FLAGVER\qs 0 \CR}{to apply the most recent flag table.}
\dispt{SNVER\qs 0 \CR}{to write a new solution table.}
\dispt{BCHAN\qs 72 ; ECHAN\qs 72 \CR}{to select the strongest and/or
            simplest spectral channel as a reference.}
\dispt{REFANT\qs 5 \CR}{to try to use the same reference antenna as in
            the previous run of {\tt FRING}\@.}
\dispt{SOLINT\qs 6 \CR}{to set the solution interval in minutes.  It
            should not exceed the coherence time.}
\dispt{APARM(6)\qs 1 \CR}{to get useful, but limited printout.}
\dispt{APARM(7)\qs 9 \CR}{to avoid false detections by setting the
            minimum acceptable SNR\@.  {\it Warning:\/} solutions
            with lower SNR will be flagged as bad which will
            ultimately flag the affected data.}
\dispt{DPARM(1)\qs 1 \CR}{to use one-baseline combination in initial,
            coarse fringe search (FFT).}
\dispt{DPARM(2)\qs = -1 \CR}{to prohibit a search in the delay domain
            by setting the delay window to a negative number.
            Remember setting this to 0 means to use the Nyquist
            value, which is not what we want.}
\dispt{DPARM(3)\qs 0 \CR}{to search for fringes over the full Nyquist
            fringe-rate window since we don't know where the fringes
            are.}
\dispt{DPARM(4)=\qs 0 \CR}{to let {\tt FRING} automatically determine
            the correlator integration time (if this fails, you will
            have to set the proper value here --- see {\tt DTSUM}).}
\dispt{DPARM(5)\qs 0 \CR}{to do the least-squares solution.}
\dispt{GO \CR}{to do the fit.}
\iodx{calibration}\iodx{spectral-line}
\dispe{Then run {\tt CLCAL} again to apply these solutions to the
previous calibration tables. You have then generated a full set of
calibration tables and data.  Remember that the calibration
information for the continuum and line sources are stored in different
{\tt CL} tables.}

\Subsubsections{Polarization-specific fringe-fitting}{vlbPCAL}

\todx{FRING}
The phase and delay corrections obtained using RR and LL data can only
remove R-R and L-L offsets between different antennas.  There still
may be R-L phase and multi- and single-band delay offsets. The R-L
delay corrections can be determined using the RL and LR data and a
task named {\tt RLDLY} is available for determining these effects.
This still leaves an overall R-L phase offset.

Once the cross-hand calibration has been completed, the instrumental
\Indx{polarization} (otherwise known as the feed D-terms), can be
determined.  Several different methods are available for this purpose,
implemented in the tasks {\tt PCAL} and {\tt \tndx{LPCAL}}\@.   {\tt
SPCAL} was designed for polarization \indx{calibration} of spectral-line
data sets, but {\tt PCAL} is now more capable of doing a
channel-dependent polarization solution. {\tt PCAL} is discussed briefly
below and further details for each of these tasks can be found in the
appropriate {\tt EXPLAIN} files.
\iodx{fringe-fitting}\iodx{calibration}\Iodx{VLBI}

The determination of the absolute polarization position angle is
equivalent to the determination of the absolute R-L phase difference.
For an unresolved source this can be measured in much the same way as
for VLA data (see \Sec{polcal}) using task {\tt RLDIF} to determine
the cross-polarized phase on the polarization calibrator.
Alternatively, a source with known polarization properties can be
used, \eg\ 3C286 or 3C279.  For a resolved polarization calibrator a
sum of Clean components is required to compare to the integrated
polarization position angle as measured by the VLA or single-dish
observations nearby in time. Once the R-L phase correction is known it
is applied using task {\tt CLCOR} with {\tt OPCODE='POLR'} or task
{\tt RLCOR} (see \Sec{polcal}).  See also VLBA Scientific Memo No.~26,
``Polarization Angle Calibration Using the VLA Monitoring Program,''
by G. Taylor and S. Myers, October, 2000.

After feed \indx{calibration} and the determination of the absolute
polarization position angle, the final Stokes Q and U images can be
formed directly. Note that task {\tt PCNTR}, which is used for
displaying polarization images, allows an arbitrary rotation of all
polarization vectors under control of input adverb {\tt ROTATE}\@.
This is only necessary if {\tt CLCOR} wasn't used to correct the R-L
phase; also the polarization angle specified for {\tt PCNTR} is half
the R-L phase difference.

\subsubsections{R-L delay calibration}

{\tt \Tndx{RLDLY}} is a task which replaces {\tt RUN} file procedures
{\tt VLBACPOL} and {\tt CROSSPOL}.  It determines R-L delay
differences and produces an {\tt SN} table which corrects for these
effects (after {\tt CLCAL})\@.  It is best run on a set of calibrator
data for which the source is at least moderately polarized (source
\Indx{polarization} dominates instrumental polarization).  Several
baselines should be averaged but RL or LR fringes (or both) must be
detectable on each baseline to the reference antenna.  This task
should leave a single R-L phase difference that must be determined
from a calibrator of known polarization angle.
\dispt{DEFAULT \tndx{RLDLY} ; INP \CR}{to set the task name and
             examine the inputs.}
\dispt{INDISK\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
             input file.}
\dispt{OUTDI\qs 1 \CR}{to use disk 1 for temporary files.}
\dispt{FLAGVER\qs 0 \CR}{to use the highest numbered flag table.}
\dispt{GAINUSE\qs {\it CLin\/} \CR}{to use the {\tt CL} table with all
           calibration up to this point; {\it no default\/}.}
\dispt{SUBARRAY\qs 0 \CR}{to do all subarrays.}
\dispt{ANTENNAS\qs 0 \CR}{to use all antennas.}
\dispt{REFANT\qs $A_{\rm ref}$ \CR}{to select the reference antenna;
           any antenna may be used but all baselines to it should have
           RL and LR fringes.  {\tt REFANT 0} will loop over all
           possible (not necessarily good) reference antennas,
           averaging the result.}
\dispt{APARM\qs 6, 1, 10 \CR}{to use only solutions with
           signal-to-noise ratio above 6, to not write a {\tt CL}
           table even if there is only one calibration scan, and to
           omit all solutions with rms $< 10$ from the average over
           antennas.}
\dispt{CALSOUR '{\it cal1\/}' , ' ' \CR}{to specify the calibrator
           source to use.}
\dispt{TIMERANG\qs {\it d1 h1 m1 s1 d2 h2 m2 s2\/} \CR}{to specify a
           time range with high SNR for RL and LR\@.}
\dispt{SOLINT\qs 0 \CR}{to specify the minimum integration time in
           seconds; 0 causes it to be found from the data.}
\dispt{GO \CR}{to run the task.}
\dispe{{\tt RLDLY} should be done after parallel-hand instrumental
delays are removed ({\tt VLBAPCOR})\@.  It may be done before or, with
a slight preference, after fringe fitting ({\tt VLBAFRNG}, {\tt
VLBAKRNG}, {\tt VLBAFRGP}, or {\tt VLBAKRGP})\@.  The corrections
should be checked with {\tt VLBACRPL}, by setting {\tt STOKES} to {\tt
'RL'} and/or {\tt 'LR'}\@.  The RL and LR phases should be continuous
across the bandpass on each baseline and be flat if the RR and LL
phases are flat (no residual delays).}
\iodx{fringe-fitting}\iodx{calibration}

\vfill\eject
\Subsubsections{Feed D-term calibration}{vlbDterm}

The feed D-terms, or instrumental \Indx{polarization} terms, can be
determined using {\tt PCAL}\@.  {\tt SOLTYPE}s {\tt 'ORI-'} and
{\tt 'RAPR'} are appropriate for \Indx{VLBI} data.  {\tt 'ORI-'} uses
a non-linear orientation-ellipticity feed model and is appropriate if
instrumental polarization exceeds a few percent (\eg\ EVN, or VLBA at
18 or 13 cm).  {\tt 'RAPR'} uses a linearized ``D-term'' model ---
this is faster but less accurate.

Typical inputs for {\tt \Tndx{PCAL}} would be:
\dispt{TASK\qs 'PCAL' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs {\it n\/} ; GETN {\it ctn\/} \CR}{to specify the
           input file.}
\dispt{CALSOUR\qs 'DA193' , '\qs ' \CR}{to select the source.}
\dispt{TIMERANG 0\CR}{to use all times.}
\dispt{SELBAND\qs 0; SELFREQ\qs 0; FREQID\qs -1\CR}{to select all
            frequencies.}
\dispt{BIF\qs 0; EIF\qs 0\CR}{to select all IFs.}
\dispt{ANTENNAS\qs 0; UVRANGE\qs 0 \CR}{to select all antennas and
            baselines.}
\dispt{SUBARRAY\qs 0\CR}{to select all subarrays.}
\dispt{FLAGVER\qs 0 \CR}{to apply the most recent flag table.}
\dispt{DOCALIB\qs 1 \CR}{to apply the previous amplitude and
            delay/rate calibration.}
\dispt{GAINUSE\qs {\it clin\/}}{to specify which {\tt CL} table to
            use.}
\dispt{IN2DISK\qs {\it n\/}; GET2N {\it ctn\/}\CR}{to specify Clean
            images as models for the I, Q, and U polarizations.}
\dispt{INVERS\qs 1\CR}{to select a CC table version.}
\dispt{REFANT\qs 1 \CR}{to use the same reference antenna as in
            the previous run of {\tt CALIB}\@.}
\dispt{NCOMP\qs 77; NMAPS\qs 1\CR}{to specify the number of Clean
            components to use and to explicitly set the number of
            Clean images supplied.}
\dispt{SOLINT\qs 6 \CR}{to set the solution interval in minutes.  It
            should not exceed the coherence time.}
\dispt{SOLTYPE\qs 'RAPR'\CR}{to specify the type of feed model.}
\dispt{PRTLEV\qs 0\CR}{to print minimal information}
\dispt{BPARM(1)\qs 0\CR}{to use the initial feed model if found in the
            {\tt AN} table.}
\dispt{BPARM(3)\qs 0\CR}{to not fit for R-L phase difference.}
\dispt{BPARM(4)\qs 0\CR}{to not specify the initial R-L phase.}
\dispt{BPARM(5)\qs 0\CR}{to not solve for Vpol.}
\dispt{BPARM(6)\qs 0; BPARM(7)\qs 0\CR}{to solve for the orientations
           of both polarizations of the reference antenna.}
\dispt{BPARM(8)\qs 0\CR}{to solve for all orientations.}
\dispt{BPARM(9)\qs 0\CR}{to solve for all ellipticities.}
\dispt{BPARM(10)\qs 0\CR}{to fit for the source polarization model
           parameters.}
\dispt{CPARM(1)\qs 0\CR}{to find separate solutions for each IF\@.}
\dispt{CPARM(8)\qs 0\CR}{to not limit the number of iterations.}
\dispt{CPARM(9)\qs 0\CR}{to use the default convergence tolerance.}
\dispt{CPARM(10)\qs 0\CR}{to use default convergence criterion.}
\dispt{BADDISK 0 \CR}{to specify which disks to avoid for scratch.}
\dispt{GO \CR}{to run the program.}
\pd
\iodx{calibration}\iodx{fringe-fitting}\Todx{PCAL}

The instrumental \Indx{polarization} may vary rapidly with frequency
and independent solutions may be necessary in each IF\@.  Both {\tt
'ORI-'} and {\tt 'RAPR'} model the source Q and U as scaled versions
of I which is generally only true in the limit of unresolved or
unpolarized sources.  The D-terms can be determined iteratively by
subtracting estimates of source polarization (Q, U Clean components)
in {\tt UVSUB}\@.  Note: this should be done on data for which
instrumental polarization corrections have {\it not\/} been applied.

Tasks {\tt LPCAL} and {\tt PCAL} also can be used to compute D-term
corrections for continuum and spectral-line polarization data
respectively.  Be forewarned that both of these tasks use linearized
D-term models.\Iodx{VLBI}

%\vfill\eject  % ??
\Subsections{Complex Bandpass}{ComplexBP}

For spectral line experiments and continuum observations where a high
dynamic range is required, it is be a good idea to do a complex
\indx{bandpass} at this point.  In \Sec{vlbBPcal} a scalar
bandpass was done; \ie\ only the amplitude was calibrated but not the
phase.  Now that the phases have been calibrated in time (by
fringe-fitting), a complex bandpass may be solved for.  This will take
out any dependence of the phase on frequency.  To do this, run {\tt
\tndx{BPASS}}, again applying the {\tt CL} table that includes all the
calibration.  With the inputs we recommend here, the phases {\it
must be stable in time over the entire bandpass calibrator scan(s).}
Check this with {\tt VPLOT} before proceeding.  Then
\dispt{TASK\qs '\tndx{BPASS}' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs {\it n1\/} ; GETN\qs {\it ctn1\/} \CR}{to select the
          multi-source visibility data as the input file.}
\dispt{CALSOUR\qs 'BLLAC' , 'DA193' \CR}{to specify the continuum
          source(s) which were observed for the purpose of
          \tndx{bandpass} calibration.}
\dispt{DOCALIB\qs 1 \CR}{to apply calibration.}
\dispt{GAINUSE\qs {\it CLin\/} \CR}{to indicate the {\tt CL} table
           with all calibration up to this point.}
\dispt{BPVER\qs -1 \CR}{do not apply previous bandpass table}
\dispt{SOLINT\qs 0 \CR}{to average data over whole scans before
          determining the bandpass.}
\dispt{BPASSPRM\qs 0 \CR}{to do a complex bandpass and set rest to 0.}
\dispt{BPASSPRM(5)\qs 1 \CR}{to not divide by ``channel 0.''}
\dispt{BPASSPRM(9)\qs 1 \CR}{to interpolate over flagged channels.}
\dispt{BPASSPRM(10)\qs 6 \CR}{to normalize the amplitude and phase of
          the bandpass solutions, using {\it power} rather than
          voltage for amplitudes.}
\dispt{ICHANSEL\qs $chan_{beg}$, $chan_{end}$, 1, $IF_{num}$, ... \CR}
         {to set channels for entire bandwidth for normalization, if
          this left 0 then the inner 75\% is used and can cause up to
          15\% error in the amplitude.}
\dispt{GO \CR}{to run the program.}

As recommended in \Sec{vlbBPcal}, you should look at the bandpass with
{\tt POSSM} and {\tt BPEDT}\@.  If necessary, use {\tt \tndx{BPEDT}}
to flag channels in your bandpass table or calibration data.  In the
latter case, re-make the {\tt BP} table.  This is the bandpass that
should be applied when the data is calibrated and averaged (\eg\ with
{\tt SPLIT}).

Note, if your bandpass calibrator is not stable or strong enough
during the observation (your bandpass calibrator data should have
a better S/N than the data you're trying to correct with the
bandpass), you could consider using the phase reference source (if
there is one) and use {\tt SOLINT = -1} (include all scans to make one
bandpass solution).  If the bandpass calibrator is strong enough, but
the average phase varies through the scan, then divide each record by
``channel 0'' by setting {\tt BPASSPRM(5) = -1} to adjust phase only.
You should select a range of channels that have similar phases to be
averaged as channel 0 using adverb {\tt ICHANSEL}\@.

\Subsections{Baseline-based errors}{blcal}

Baseline-based non-closing phase and amplitude errors can limit the
dynamic range of the final images.  One way to proceed is to try to
solve directly for the non-closing effects using bright, point-like
calibrator observations and the task {\tt \Tndx{BLCAL}}\@.  This
task writes a {\tt BL} table containing the estimated non-closing
baseline-based errors which can later be applied in {\tt SPLIT}, or
any of the other calibration tasks.  To use {\tt BLCAL} the noise in
the calibrator-source images should approach the theoretical limit.
Furthermore, the signal-to-noise ratio in the visibility data must be
at least 100:1 on baseline-averaged data.  {\tt BLCAL} will divide
your data by your best model and then write a {\tt BL} table
containing the baseline-based corrections.  Use this task carefully
only after reading the {\tt EXPLAIN} file thoroughly.  As an example:
\dispt{TASK\qs 'BLCAL' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs {\it n1\/} ; GETN\qs {\it ctn1\/} \CR}{to select the
           multi-source visibility data as the input file.}
\dispt{IN2DISK\qs {\it n2\/} ; GET2N\qs {\it ctn2\/} \CR}{to select
           your best image as the input model file.}
\dispt{SOURCE\qs 'DA193' \CR}{to select your calibration source.}
\dispt{DOCALIB\qs 1 ; GAINUSE\qs {\it clin\/} \CR}{to select the
               {\tt CL} table to use.}
\dispt{BLVER\qs 1 \CR}{to create {\tt BL} table version 1.}
\dispt{SOLINT\qs 1440 \CR}{to determine one complex gain correction
           per baseline for the whole observation.}
\dispt{GO \CR}{to run the program.}
\dispe{Set {\tt ICHANSEL} to select only the most desirable spectral
channels to average.  Task {\tt \Tndx{BLPLT}} may be used to plot the
{\tt BL} table.  Task {\tt \Tndx{BLCHN}} is available to compute
baseline-based errors on a channel-by-channel basis.  It writes a {\tt
BD} table which can be plotted by {\tt POSSM} and {\tt BPLOT},
but the calibration itself is not applied by the standard calibration
routines.  {\tt BLCHN} writes a calibrated output data set and {\tt
\tndx{BDAPL}} can apply the {\tt BD} table to another data set.  In
{\tt 31DEC23}, procedure {\tt \tndx{BLPOLCAL}} uses task {\tt
\tndx{BLPCL}} to carry out a similar calibration for both parallel-hand
and cross-hand polarizations.}\iodx{calibration}\Iodx{VLBI}

\sects{After initial calibration}

\Subsections{Applying calibration}{vlbSPLIT}

Having obtained your best possible calibration {\tt CL} table (and
{\tt BP} and {\tt BL} tables if bandpass or baseline-dependent errors
were found), you finally get to make a calibrated data set.  This is
done with {\tt \tndx{SPLIT}}, which applies the calibration and splits
the database into separate files, one for each source observed.
\dispt{TASK\qs 'SPLIT' ; INP \CR}{to review the inputs.}
\dispt{INDISK {\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
           input file.}
\dispt{SOURCE\qs ' ' \CR}{to write  all sources.}
\dispt{DOCALIB\qs 1 ; GAINUSE\qs {\tt clin} \CR}{to specify
                 which {\tt CL} table to use.}
\dispt{DOBAND\qs 1; BPVER 1 \CR}{to apply {\tt BP} table 1 if present.}
\dispt{BLVER\qs {\it blin\/} \CR}{to apply {\tt BL} table {\it blin\/}
                 if present.}
\dispt{APARM(1)\qs 1 ; NCHAV\qs 0 \CR}{to have all spectral channels
                 within each IF averaged: read the help file closely,
                 other useful averaging options are available.}
\dispt{APARM(2)\qs 2 \CR}{to have an amplitude correction made for the
            correlator integration time (in seconds)}
\dispt{GO \CR}{to run the program.}
\dispe{The options for {\tt SPLIT} given above will apply calibration
and then average the spectral channels within each IF, but not average
IF channels together . To average over IF channels as well, set
{\tt APARM(1) = 3} in {\tt SPLIT}\@.  (The task {\tt \tndx{AVSPC}} no
longer averages IFs although it is useful in averaging spectral
channels in calibrated data sets.)}

The task {\tt SPLAT} can be used instead of {\tt SPLIT} to do time
averaging and different options in spectral averaging.  {\tt SPLAT}
can be used also to assemble the selected sources into a multi-source
file after applying the specified calibration and averaging.  This
option allows the user to continue calibration on a smaller data set.

At this point, it is well worth spending time to examine your output
visibility data carefully.  You may plot the data against time with
{\tt VPLOT}, {\tt IBLED}, {\tt EDITR}, or {\tt UVPLT}, and list them
with {\tt LISTR}, {\tt PRTUV}, or {\tt UVPRT}\@.  {\tt POSSM} is now
no longer useful since you have averaged your data in frequency.
\iodx{calibration}\Iodx{VLBI}

\Subsections{Time averaging}{vlbUVAVG}

It is now convenient to average the data in time using {\tt
\tndx{UVAVG}} both to reduce the bulk of the data and to increase the
signal-to-noise for subsequent iterations of the
self-calibration/imaging cycle.  However, it is important to realize
that the fringe-fitting process to this point has only removed
gradients of phase over the fringe-fitting solution interval.  There
will still be stochastic atmospheric (and clock) phase errors
affecting the data on short time scales.  These phase errors can be
significant over minutes at frequencies of 22 GHz and above (and
possibly even at 15 GHz) and a reduction in amplitude can occur if
data are directly averaged.  The ionosphere can cause similar problems
at lower frequencies.  Self-calibration should remove such phase
errors.

For data at frequencies below 15 GHz (and $\approx$\ minute
integrations), it should be safe to proceed with {\tt \tndx{UVAVG}}
(see below).  For higher frequency data, it may be worth your while to
examine the phase coherence of the data first.  {\tt \tndx{VPLOT}} can
be used to examine your target or calibrator data to see directly the
level of residual phase error over your chosen averaging time.
Alternatively, the task {\tt IBLED} allows you to view the degree of
coherence of data averaged over different averaging times.  If there
are coherence problems (and the target data has enough SNR),
{\tt \tndx{CALIB}} can be run to align the  phases prior to coherent
averaging.  Try:
\dispt{TASK\qs 'CALIB' ; INP \CR}{to review the inputs.}
\dispt{INDISK {\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
              single-source input file.}
\dispt{OUTNA\qs INNA ; OUTCL\qs 'ALIGN' \CR}{to specify the output
              file.}
\dispt{CALSOUR\qs ' ' ; SMODEL\qs 1, 0 \CR}{to use the source with a
              point-source model.}
\dispt{DOCALIB\qs -1 ; GAINUSE\qs 0 \CR}{to not apply any tables to
              the input data.}
\dispt{SOLTYPE\qs ' ' \CR}{to use normal least squares.}
\dispt{SOLMODE\qs 'P' \CR}{to solve for phase.}
\dispt{SOLINT\qs (10.0/60.0) \CR}{to solve for phase in 10-second
              intervals.  This should probably be set as low as the
              strength of the source will allow.  The limit is the
              integration time that gives a SNR $> 2$ on most
              baselines.}
\dispt{ANTWT\qs 1 \CR}{to use weights from calibration with no
              additional weights applied to the antennas.  For the
              purposes of phase alignment, it is appropriate to use
              the data weights; this allows the noise in the solution
              to be distributed over the noisiest baselines.  This may
              not be the case when using {\tt CALIB} for
              self-calibration in the hybrid mapping sense (see
              \Sec{vlbimag}).}
\dispt{APARM(1)\qs 3 \CR}{to require 3 antennas present for solution.}
\dispt{APARM(6)\qs 0 \CR}{to skip diagnostic printout.}
\dispt{APARM(7)\qs 1 \CR}{to set the minimum allowed SNR\@.  This
              limit should be low since the SNR is calculated as a
              phase difference from model and this can be large.
              Start with a value $\leq 1$.}
\dispt{GO \CR}{to run the program.}
\dispe{Note that {\tt CALIB} will only give valid solutions if the
signal-to-noise over the solution interval on most baselines is
greater than 2 (and preferably much higher).  At high frequencies on
weak sources, it may not be possible to select a solution interval
long enough that the signal-to-noise satisfies this criterion, yet
short enough to follow the atmospheric phase variations.  In such
cases, it is probably best not to attempt to self-calibrate the data,
but instead to use a short averaging time and to live with any
coherence losses in the data.}
\iodx{calibration}\Iodx{VLBI}

When the data are sufficiently phase coherent, they should be averaged
over time down to a reasonable size using {\tt \tndx{UVAVG}}:
\dispt{TASK\qs 'UVAVG' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs {\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
            {\tt CALIB} output file as the {\tt UVAVG} input file.}
\dispt{OUTNA\qs INNA ; OUTCL\qs 'UVAVG' \CR}{to specify the output
            file.}
\dispt{YINC\qs 30.0 \CR}{to set the time-averaging interval to 30
            seconds.}
\dispt{OPCODE\qs ' ' \CR}{to enable the averaging operation.  There
            are several options controlling the averaging interval
            selection and reported times.}
\dispt{GO \CR}{to run {\tt UVAVG}\@.}
\pd

If {\tt SPLAT} was used to assemble the selected sources into a
multi-source file (while applying the preliminary calibration), {\tt
CALIB} will write an {\tt SN} table which must be converted to a
{\tt CL} table by {\tt CLCAL}\@.  This new {\tt CL} table can be
applied by {\tt SPLAT} with time averaging.

\Subsections{Verifying calibration}{vlbverify}

Before proceeding to image your data, it's worth checking that the
calibration performed in \Sec{vlbcalib} is sensible.  For each of your
sources, produce a plot of the correlated flux density against \uv\
distance using {\tt \tndx{UVPLT}}\@.  As well as identifying bad
data which can then be deleted with {\tt SPFLG}, {\tt EDITR}, {\tt
WIPER}, or {\tt UVFLG}, these amplitude versus distances plots
(especially those of your calibrator sources) can be used to identify
stations where the amplitudes are too high or too low.  Furthermore,
by fitting simple models to the calibrator data, constant correction
factors can be determined for each station which can be used to
correct the amplitude calibration.  It is often the case that the
amplitude calibration to a certain station (particularly non-VLBA
stations) is out by a constant factor, either due to uncertainties in
the antenna gain or in the noise calibration signal.\iodx{calibration}

     In {\tt 31DEC20}, two tasks allow you to examine selected portions
of a $uv$ data set statistically.  {\tt \Tndx{UVRMS}} averages the
selected data in {\tt SOLINT} time intervals and then can plot the
average values as a function of time and as a histogram.  A variety
of statistical parameters are computed and printed.  {\tt \Tndx{SPRMS}}
determines and plots the mean and standard deviation of the selected
data as a function of spectral channel.  Note that both tasks will
combine data from multiple sources, baselines, etc.~if so instructed.
In {\tt 31DEC21} {\tt RIRMS} computes the mean and rms of the real and
imaginary parts of the visibilities.  It prints these in a baseline
matrix and can plot them by baseline as functions of time and as
histograms.  These tasls have a full set of calibration and data
selection adverbs, so they may be run before you run {\tt SPLIT}\@.

Most VLBI calibrator sources can be adequately described by one or two
Gaussian components.  The task {\tt \tndx{UVFIT}} can be used to fit
such a model while finding constant correction factors for the antenna
gains. Note that {\tt UVFIT} can handle no more than 2,500,000
visibilities, so further averaging with {\tt UVAVG} may be required.
The following example shows how to fit antenna gains and a single
elliptical Gaussian model of known position and flux to one of the
single-source data sets produced by {\tt SPLIT} or {\tt SPLAT} (with
spectral averaging)
\dispt{TASK\qs 'UVFIT' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs {\it n\/} ; GETN\qs {\it ctn\/} \CR}{to specify the
            input \uv\ data set.}
\dispt{OPCODE\qs 'GAUS' ; NGAUS\qs 1 \CR}{to specify 1 Gaussian
            component.}
\dispt{GMAX\qs 1.2 ; DOMAX\qs FALSE \CR}{to fix the flux at 1.2 Jy.}
\dispt{GPOS\qs 0 ; DOPOS\qs FALSE \CR}{to hold the position fixed at
            the origin.}
\dispt{GWIDTH\qs 0.002 , 0.001 , 45. \CR}{to provide an initial guess
            of the Gaussian widths as $2 \times 1$ mas at a position
            angle of $45\deg$.}
\dispt{DOWIDTH\qs TRUE \CR}{to fit for size.}
\dispt{GAINERR\qs 1 \CR}{to fit for all antenna gains with initial
            guess $= 1$.}
\dispt{NITER\qs 50 \CR}{to limit the fitting to 50 iterations.}
\dispt{IMSIZE\qs 0.0005 , 0.01 \CR}{to limit sizes to be in the range
            0.5 to 10 mas.}
\dispt{DOCAT\qs TRUE ; INVER\qs 1 \CR}{to save the solution in a {\tt
            CC} file of version number 1.}
\dispt{INP \CR}{to check the inputs.}
\dispt{GO \CR}{to run {\tt UVFIT}\@.}
\dispe{{\tt UVFIT} can also be applied to the multi-source file, but
{\tt SRCNAME}, {\tt DOCAL}, {\tt GAINUSE} etc.~must then be set.  It
can handle up to 20 sources to be fit, using a channel-dependent input
text file and can write the results in a compact text file form.}

Another way to test your amplitude calibration is to use the task {\tt
\tndx{UVCRS}} for bright sources with long tracks.  This task
calculates correction factors for the amplitudes of the stations using
regions of the \uv\ plane where \uv\ tracks cross.  {\tt UVCRS} can
write the correction factors into an {\tt SN} table.\Iodx{VLBI}

Once the scale factors are determined, there are a number of options
for correcting the data.  The simplest option is to apply the
correction factors to the single-source data sets using task
{\tt \tndx{VBCAL}}\@.  Alternatively, the correction factors can be
incorporated into the highest version {\tt CL} table of the
multi-source data file and task {\tt SPLIT} run again to make new
calibrated data files.  The corrections to the {\tt CL} table are done
with {\tt CLCOR}\@.  Unlike {\tt VBCAL}, {\tt \tndx{CLCOR}} must be
run separately for each antenna whose calibration you wish to alter;
{\tt ANTENNA} must be set to the antenna number you wish to change,
{\tt OPCODE = 'GAIN'}, and {\tt CLCORPRM(1)} set to the amplitude
scale factor found in {\tt UVFIT}; note that these are {\it voltage}
gains.  All higher values in the array {\tt CLCORPRM} should be zero.
The effect of the altered calibration can be viewed using {\tt UVPLT}
with {\tt DOCAL = 1}.  If it is satisfactory, {\tt SPLIT} can be
re-applied to the data.  We recommend using {\tt CLCOR} to perform
such amplitude corrections.  It now produces a new {\tt CL} table each
time it is used unless you specify both {\tt GAINVER} and {\tt
GAINUSE} as having the same, non-zero version number.

Another way of incorporating amplitude corrections is to edit the
calibration text files used by {\tt \tndx{ANTAB}}\@.  This can be
accomplished by setting the {\tt FT} parameters for affected stations.
For instance, if the Bonn scale factor is 1.043, set the {\tt FT}
parameter on the {\tt BONN TSYS} card to {\tt FT=(1.043*1.043)}.  If
amplitude calibration was carried out {\it after\/} fringe-fitting
({\it not recommended!\/}, then it is only necessary to rerun {\tt
ANTAB}, delete the latest {\tt CL} table containing amplitude
calibration and rerun {\tt APCAL} using the highest {\tt CL} table
produced in the fringe-fitting step.  If however, as we have described
in this chapter, the amplitude calibration was done prior to
fringe-fitting, then correcting the amplitudes is more involved.  It
is probably best to delete all {\tt CL} tables except the first one
and start again at \Sec{vlbcalib}.  However, it may not be necessary
to carry out the time consuming {\tt FRING} solutions again.  If the
amplitude changes are small, the phase, rate and delay solutions will
be essentially unchanged.  Therefore, with care, the existing {\tt SN}
tables can be used in lieu of re-running {\tt FRING}\@.
\iodx{calibration}

\Sects{Self-calibration, imaging, and model-fitting}{vlbimag}

We are now in a position to make images.  As with VLA data, we do this
by iteratively self-calibrating the data and deconvolving using
Clean, MEM {\it et al}.  We describe below a typical self-calibration
and imaging sequence for VLBI data.  The tasks used are described in
more detail in \Rchap{image}.

\xben
\Item {\tt \tndx{CALIB}} self-calibrates the \uv\ data.
\Item {\tt \tndx{IMAGR}} images and Cleans. {\tt IMAGR} is now
     the preferred task for imaging {\tt VLBI} data in \AIPS\@.
\Item {\tt SCMAP} images, Cleans, and self-calibrates.
     {\tt \tndx{SCMAP}} is meant to provide the functionality of the
     popular VLBI data analysis package {\tt difmap}.  {\tt
     \tndx{SCIMG}} is a multi-field version of {\tt SCMAP}\@.
\xeen
\dispe{The main difference between the processing of VLBI and VLA
data is that, unless phase-referencing is used, absolute phases of
VLBI data are un-calibrated.  Therefore, many more iterations
around the imaging loop are required for the VLBI case; dozens of
self-calibration iterations are not uncommon.  Given this, it may be
convenient to use tasks {\tt \tndx{SCMAP}} or {\tt \tndx{SCIMG}} which
cycle between imaging and self-calibration with an option to edit the
$UV$ data.  If you wish to edit the Clean components or make plots,
you will need to do the manual Clean/self-cal process with {\tt IMAGR}
and {\tt CALIB}\@.}

Note that VLBI imaging is not an exact science and there are a number
of different views on the ``correct'' imaging method and the
``correct'' software to accomplish this method.  Some users take their
\AIPS\ data into a package written at CalTech to use the {\tt difmap}
program (see {\tt ftp://phobos.caltech.edu/pub/difmap/}).  Others use
the \AIPS\ tasks {\tt SCMAP} and {\tt SCIMG} (see \Sec{selfcal}).
It is beyond the scope of this document to explain in detail all
aspects of VLBI imaging.  For more details, see Craig Walker's chapter
on ``Practical VLBI Imaging'' in the publication {\it VLBI and the
VLBA\/}, {\bf 1995}, edited by A. Zensus, P.J. Diamond, and P.J.
Napier which is available on the World-Wide Web
(www.cv.nrao.edu/vlbabook).  Here we make a few suggestions on how to
control {\tt \tndx{CALIB}} and {\tt \tndx{IMAGR}}\@.  Again, please
note that the latter is preferable to all previous imaging tasks; {\tt
\tndx{SCIMG}} and to a lesser extent {\tt \tndx{SCMAP}} offer the same
improved imaging techniques.  They do not offer several experimental
algorithms found in {\tt IMAGR} including Clean component filtering,
the SDI Clean algorithm, and multi-resolution Cleaning.

\subsections{{\tt CALIB}}
\iodx{calibration}

\xben
\Item Start by correcting antenna phases only, \ie\ use {\us SOLMODE =
    'P' \CR}\@.  Switch on the amplitude correction only after you
    have converged to a fairly good image.  On the first iteration,
    you will need to invent an input model.  For most extragalactic
    continuum sources, a point-source model is a good choice.  Set
    {\tt SMODEL(1)} to the zero-spacing flux density as extrapolated
    by eye using {\tt UVPLT} and consider using a circular Gaussian
    model at the origin to reduce the impact of the longest spacings.
    Start with the so-called SNR parameter {\tt APARM(7)} small ($\leq
    1$) and gradually increase it as the image improves.  If this
    parameter is large during early iterations, when the model used is
    far from correct, then large portions of your data in the output
    file may be flagged.  This is not too important if you use the
    original input \uv\ file as the input to {\tt CALIB} in all
    iterations.  You can also set {\tt APARM(9) = 1} to leave data
    affected by failed solutions uncalibrated.\iodx{self-calibration}
\Item On subsequent iterations, use the Clean image as produced by
    {\tt IMAGR} as your input model.  \Indx{VLBI} applications usually
    require Clean components well beyond the first negative component
    to be used in calculating the source model.  One possibility is to
    use {\tt PRTCC} to find the point where a significant fraction
    (\eg\ one third) of all new Clean components are negative.  An
    alternative is to use all of the Clean components, but to use
    tight windowing in {\tt IMAGR} --- which can now be done
    interactively on the TV as {\tt IMAGR} progresses.  Alternatively,
    use tight windowing and clipping of the Clean components in {\tt
    IMAGR} ({\tt IMAGRPRM(8)} and {\tt IMAGRPRM(9)}) or afterward
    with {\tt \tndx{CCEDT}} or {\tt \tndx{CCSEL}} before running {\tt
    \tndx{CALIB}}\@.  Tight windowing is especially important when
    \uv\ coverage is poor.  Editing Clean components after {\tt
    \tndx{IMAGR}}, but before {\tt CALIB}, can be effective in
    removing possibly spurious features; if they are real they will
    usually reappear in later iterations.  {\tt IMAGR} offers a
    filtering option to remove weak, isolated components when
    requested from the TV and at the end before the components are
    restored to the image.  This removes much of the need for {\tt
    CCSEL}\@.
\Item When carrying out the next {\tt CALIB} iteration with the new
    Clean model, you can either self-calibrate the original data set
    or, alternatively, self-calibrate the data set (output by {\tt
    CALIB}) which was used to produce that Clean model.  It is
    advantageous to use the original data set at least until you  turn
    on amplitude \indx{calibration}.  At that point, you should stick
    with the file produced from the original data with the best
    phase-only solution.  Amongst other things, this can prevent the
    telescope amplitudes from ``wandering'' (see below).
\Item When the model contains extended structure, there may be
    problems with convergence when weighting the data ``correctly''
    (\ie\ by $1/\sigma^2$.)  The {\tt WEIGHTIT} adverb allows you to
    use less extreme weights, such as $1/\sigma$ or $1/\sqrt\sigma$.
    If your array contains antennas that have a wide range of
    sensitivities, \eg\ the VLBA plus the phased-VLA and/or the
    Effelsberg 100-m, it is helpful to alter the weights of the
    antennas in your {\tt CALIB} solutions.  If this is not done, then
    your solution will be dominated by only a few baselines and the
    uniqueness of the solution is not guaranteed.  Use {\tt PRTUV} to
    inspect the weights of your data.  Then set the {\tt CALIB} input
    array {\tt ANTWT}, which provides multiplicative factors adjusting
    the weights for each antenna prior to the {\tt CALIB} solution.
    Set these parameters so that the effective range of baseline
    weights is only 10 to 100.  Alternatively, use {\tt WTMOD} to raise
    the original weights to a power between 0.25 and 0.5.
\Item As you iterate, keep an eye on how the model image is converging
    to fit the data.  Use {\tt VPLOT}, {\tt CLPLT}, {\tt CAPLT}, and
    {\tt UVPLT}\@.
\Item When your source has a lot of extended structure and/or your
    VLBI array has relatively few short spacings, you should consider
    setting {\tt UVRANGE} to only include the range of spacings in
    which the model provides a good fit to the data.  However, given
    the relatively small number of antennas in most VLBI observations,
    you may need to compromise to allow in enough baselines to get
    good self-cal solutions.  Set {\tt WTUV > 0}.\Iodx{VLBI}
\Item When you are finally ready to solve for amplitude corrections,
    you should first apply all previous phase calibration including
    the final phase-only self-calibration solution.  Then run {\tt
    \tndx{CALIB}} setting {\tt SOLMOD\qs 'A+P'}, initially setting
    the solution interval ({\tt SOLINT}) to a longer time than used
    for phase-only solutions (\eg\ 3 times).  Try to prevent the
    antenna amplitudes from ``wandering,'' which can sometimes happen
    if there is still a significant amount of short spacing flux
    density missing from the source model.  Setting {\tt UVRANGE} is
    useful, as is setting {\tt CPARM(2) = 1} to constrain the mean
    amplitude solutions over all antennas to be one.  You can also set
    {\tt SOLMODE='GCON'} and the array {\tt GAINERR} to the expected
    standard deviation of the gains for each antenna.  This constrains
    amplitude solutions to conform to the expected statistics.
    Setting the gain constraint factor {\tt SOLCON} to values larger
    than 1 will increase the importance of these gain error
    constraints.  Finally, going back and self-calibrating starting
    with the original data set and the best available Clean model is
    useful way to prevent amplitude wander.
\xeen
\iodx{self-calibration}

{\tt CALIB} has been enhanced to improve its usefulness for SVLBI
data sets. This has involved the implementation of improved antenna
selection and partial array calibration, through the new adverb {\tt
DOFIT}\@.  The possibility of solving only for a subset of selected
antennas has been implemented in this manner and may prove useful for
SVLBI data. The implementation of adverb {\tt DOFIT} in {\tt CALIB} is
analogous to its implementation in {\tt FRING} (see \Sec{fring}).

\vfill\eject
\subsections{{\tt IMAGR}, {\tt SCIMAG}, and {\tt SCMAP}}
\iodx{calibration}

\xben
\Item Before using {\tt IMAGR} or {\tt \tndx{SCMAP}} or {\tt
    \tndx{SCIMG}}, print out and read the {\tt EXPLAIN} file.  They
    are powerful and complicated tasks with many adverbs --- some of
    which are new --- and shouldn't be used blindly.
\Item The quality of images produced may depend on the type of
    weighting used.  With VLBA-only experiments, the best quality
    images are often produced using natural ({\us UVWTFN\qs 'NA' \CR})
    weighting in {\tt IMAGR}\@.  These images will represent the
    extended structure of the source better.  If the highest
    resolution is required, try uniform ({\us UVWTFN\qs 'UN' \CR})
    weighting.  The {\tt ROBUST} parameter allows weightings
    intermediate between these two extremes often with both good
    signal-to-noise characteristics and a narrow synthesized beam.  It
    may also be worth experimenting with the {\tt UVBOX} parameter to
    allow smoothing of weights over larger areas of the \uv\ plane
    (\ie\ to use ``super-uniform weighting'').  If the array contains
    antennas with very different sensitivities, (for instance, if it
    includes Effelsberg, the phased-VLA, and/or HALCA), then it may be
    advantageous to alter the weights of baselines to these antennas.
    Although this increases the thermal noise in the image, it will
    improve the \uv\ coverage, which, otherwise, will contain
    effectively only the baselines to the most sensitive antennas.
    One way of doing this is to use {\us UVWTFN = 'UV' \CR} in {\tt
    IMAGR}\@.  This option takes the fourth root of the input weights
    before applying uniform weighting.  {\tt SCMAP} and {\tt SCIMG}
    also support these weighting options.  Another flexible (but
    deprecated) approach is to use task {\tt WTMOD} to change the
    weights in the data set prior to running {\tt \tndx{IMAGR}}\@.
\Item After an initial self-calibration against a point-source
    starting model, the deconvolved image will often show spurious
    symmetric structure.  Convergence can be speeded up by placing
    Clean boxes {\tt CLBOX}) around the side showing the brighter
    structure.  Note that {\tt CLBOX} may be used to produced circular
    as well as rectangular windows for use with {\tt IMAGR}\@.
    Alternatively, {\tt CCEDT} can be used to edit the Clean
    components after {\tt IMAGR}, but before the next {\tt CALIB}\@.
    {\tt IMAGR}, {\tt SCIMG}, and {\tt SCMAP} allow this to be done
    interactively at the start of each major Clean cycle including the
    first.
\Item Use {\us DOTV = 1 \CR} to view the residuals and possibly modify
    the Clean boxes as you Clean.  You can stop Cleaning if you feel
    that you are including spurious structure into your model or if
    you feel you need to reset a Clean box to include a new feature.
    Note the {\tt BOXFILE} and {\tt OBOXFILE} options which allow you
    to retain interactively set Clean boxes for use in the next
    self-cal iteration.
\Item {\tt \tndx{SCMAP}} and {\tt \tndx{SCIMG}}, at each
    self-\indx{calibration} cycle, offer a powerful interactive data
    \indx{editing}\iodx{flagging} tool which displays input and
    residual data from up to 11 baselines simultaneously.  This is the
    same editor as found in task {\tt EDITR}\@.
\xeen

\noindent The hints outlined above are by no means the whole story
when it comes to self-calibrating and imaging \Indx{VLBI} data.
Unfortunately, it can still be somewhat of an art form.  Very
experienced users can produce noise-limited images, but there is no
simple recipe that will enable inexperienced users to do the same.
\iodx{self-calibration}

\subsections{Non-conventional methods of imaging}

\begin{figure}[tb]
\centering
%\resizebox{!}{4.0in}{\gname{frmap}}
\resizebox{!}{4.0in}{\gbb{531,543}{frmap}}
\caption[An example of a fringe rate image]{An example of a
preliminary determination of the source location using fringe-rate
analysis. The position of the source in channel 51 is shifted relative
to the reference channel (62) by $\approx 25$ asec to the north.
Conventional imaging can be carried out near this position.}
\label{fig:frmap}
\end{figure}

Since fringe rate is a function of source position, we can use
measurements of the fringe rate to estimate the positions of sources.
Fringe rate imaging is widely used with maser sources which are
usually widely separated point objects.  The angular resolution of
fringe rate images is not as good as conventional aperture synthesis
imaging, but it can be used for an initial determination of the
location of emitting clusters.  This will help in setting field shifts
and Clean windows for use by {\tt IMAGR}\@.  Having measured the
fringe rate $FR(i)$ for each sample in (baseline-time) and computed
the derivative of fringe rate ($UDOT(i)$) wrt to right ascension ($X$)
and the derivative ($VDOT(i)$) wrt declination ($Y$), we obtain a set
of equations of straight lines
    $$ FR(i) = UDOT(i) * X + VDOT(i) * Y$$
describing the loci of constant fringe rate for each observation.  The
positions of the source component(s) can be determined by finding the
places of highest density of crossing lines.  (Details can be read in
Giuffrida,T.S, 1977 Ph.D.thesis MIT and in Walker R.C., 1981, {\it
Astr. J.\/}, {\bf 86}, 9, 1323.)

This algorithm is implemented in \AIPS\ as the task {\tt FRMAP}\@.
The task plots the straight lines on the TV or prepares a plot file.
Then it determines the positions of higher density of crossing lines.
The coordinates in RA and DEC of the components found are written in
an output file.  The fringe rate method is especially attractive in
SVLBI because of the better angular resolution due to faster movement
of the orbiting antenna.  \Rfig{frmap} shows an example of a fringe
rate image.

{\tt FRMAP} can be used for more accurate definition of the source
coordinates that is required by the correlator.  In this case the
correlator carries out two passes.  After the first one (short) {\tt
FRMAP} is used to find a more accurate position of the source.  The
new coordinates are then used in the second pass covering the whole
experiment.

\vfill\eject
\Sects{Summary of VLBI calibration tables}{vlbtables}

Several different tables are supplied with a \Indx{VLBI} data set
created by the Socorro and other correlator; various other tables
(\eg\ {\tt SN} tables) are created by the \indx{calibration} process.
A  list of these tables is given below for your edification.  Not all
\indx{tables} will be present with all files.  See \AIPS\ Memos 114 and
117, reachable via {\tt https://www.aips.nrao.edu}, for complete
documentation of the table and data formats used by \AIPS\@.

\beddes
\item[ AN ]{Antenna table. Contains a list of the antenna names
      and station coordinates.  Also contains instrumental
      polarization terms.}
\item[ AT ]{Antenna characteristics table. Contains additional
      information about antenna properties, including some time
      variable quantities.}
\item[ BL ]{Baseline offset table. Contains non-closing
       baseline-dependent phase and amplitude errors as determined by
       {\tt BLCAL}\@.}
\item[ BS ]{Baseline solution table.  Contains baseline delay, rate
       and phase solutions as determined by {\tt BLING}\@.}
\item[ CL ]{Calibration table.  Version 1 contains, amongst other
      things, the default calibration parameters for the amplitude
      (usually unity), phase, and single-band delay (usually zero) for
      each source for each IF as a function of time.  It also contains
      polynomial coefficients allowing the correlator delay and phase
      models to be recomputed.  As calibration proceeds, higher
      versions of this table are created which incorporate more and
      more calibration effects into the phase, delay, and amplitude
      entries.\Iodx{VLBI}}
\item[ CQ ]{Correlator parameter frequency table. Contains VLBA
       correlation parameters for each \AIPS\ IF, and activates VLBA
       delay decorrelation corrections. Type {\tt EXPLAIN FXVLB} for
       further information.}
\item[ CT ]{{\tt CALC} table. Contains the input parameters passed to
       {\tt CALC} to generate the polynomials recorded in the {\tt IM}
       table.}
\item[ FG ]{Flag table. Contains information used to delete selected
      portions of the data.}
\item[ FQ ]{Frequency table. Contains information about the IF
      frequencies, channel spacings, bandwidths, etc.}
\item[ GC ]{Gain Calibration table. Contains the expected zenith
      gain and gain-elevation curve for each antenna. It is used for
      amplitude calibration.}
\item[ HF ]{Haystack {\tt FRNGE} table. Contains information
       generated from the \AIPS\ tables that can be exported to the
       {\tt CALC} and {\tt SOLVE} package.}
\item[ IM ]{Interferometer model table. Contains the actual
      polynomial coefficients which the VLBA correlator used to
      calculate the geometrical model.  Unlike the coefficients in the
      {\tt CL} table, these have not been re-interpolated onto the {\tt
      CL} time grid, but have time stamps corresponding to the times
      at which the correlator computed the geometrical model.}
\item[ MC ]{Model Components table. Contains the various components
       of the geometric model used in the VLBA correlator to generate
       the {\tt IM} table.}
\item[ NX ]{Index File. Contains information about the time, source,
      sub-array and location within the data file of each observation
      or ``scan.''  It is used by some \AIPS\ tasks in accessing the
      main data file and subsidiary tables.}
\item[ OB ]{Spacecraft Orbit table.  Contains information about the
      positions and velocities used by the correlator for an orbiting
      antenna.}
\item[ PC ]{Phase-calibration table. Contains phases within each
      IF computed from the injected phase calibration signals.  It is
      used to determine the phase offsets and single-band delays for
      each IF channel.}
\item[ SN ]{Solution table.  Contains antenna delay, rate, phase, and
      amplitude corrections solved for by {\tt CALIB} and {\tt
      FRING} and other tasks.}
\item[ SU ]{Source table. Contains a list of the sources found
      within the multi-source file, including information on
      source positions and flux density.}
\item[ TY ]{System temperature table. Contains the system temperature
      as a function of time for each antenna and IF channel. It is
      used for amplitude calibration.}
\item[ VT ]{VLBA Tape table. Contains tape playback statistics for
       use mainly by the VLBA correlator group.}
\item[ WX ]{Weather table. Contains weather-related information for
       each station.}
\eeddes
\iodx{calibration}\iodx{tables}


\sects{Additional recipes}

% chapter C *************************************************
\recipe{Bananes r\^ oties}

\bre
\Item {Preheat oven to \dgg{375}.}
\Item {Place 6 (peeled) {\bf bananas} in a baking dish.}
\Item {Sprinkle bananas with juice of 1/2 {\bf lemon}.}
\Item {Pour 2 tablespoons melted {\bf butter} and 2 tablespoons
   {\bf dark rum} over the bananas.  Sprinkle with 2 tablespoons
   {\bf brown sugar}.}
\Item {Place in oven for 10 minutes.}
\Item {Pour on 2 more tablespoons {\bf melted butter} and 2 more
           tablespoons {\bf dark rum} and bake for 5 minutes more.}
\Item {Serve at once, spooning some sauce over each banana.}
\ere

% chapter  *************************************************
\recipe{Banana curried chicken}

\bre
\Item {Fry 2 chopped {\bf onions} in 50 ml {\bf cooking oil} until
     light brown.}
\Item {Add 1/4 cup {\bf cake flour} and mix well. Add 1 (cup?) {\bf
     chicken stock} gradually while stirring.}
\Item {Add 1 cup {\bf raisins}, 1 teaspoon {\bf salt}, 2 pounds
     cooked, boned {\bf chicken}, 5 sliced {\bf bananas}, 2 grated
     {\bf apples}, 2 tablespoons grated {\bf lemon rind}, 1 tablespoon
     {\bf sugar}, 1 1/2 tablespoons {\bf curry powder}, 1 {\bf bay
     leaf}, 4 {\bf peppercorns}.}
\Item {Cover saucepan and simmer for 20 minutes.}
\Item {Remove bay leaf.  Add 1 cup {\bf cream} and heat just before
     serving.}
\Item {Serve on a bed of rice. Decorate with pineapples if preferred.}
\item[ ]{\hfill Thanks to Turbana Corporation ({\tt www.turbana.com}).}
\ere

