%-----------------------------------------------------------------------
%;  Copyright (C) 1995
%;  Associated Universities, Inc. Washington DC, USA.
%;
%;  This program is free software; you can redistribute it and/or
%;  modify it under the terms of the GNU General Public License as
%;  published by the Free Software Foundation; either version 2 of
%;  the License, or (at your option) any later version.
%;
%;  This program is distributed in the hope that it will be useful,
%;  but WITHOUT ANY WARRANTY; without even the implied warranty of
%;  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%;  GNU General Public License for more details.
%;
%;  You should have received a copy of the GNU General Public
%;  License along with this program; if not, write to the Free
%;  Software Foundation, Inc., 675 Massachusetts Ave, Cambridge,
%;  MA 02139, USA.
%;
%;  Correspondence concerning AIPS should be addressed as follows:
%;          Internet email: aipsmail@nrao.edu.
%;          Postal address: AIPS Project Office
%;                          National Radio Astronomy Observatory
%;                          520 Edgemont Road
%;                          Charlottesville, VA 22903-2475 USA
%-----------------------------------------------------------------------
% Summary of standard aips calibration process.
% last edited by  glen langston
\documentstyle{article}
\newcommand{\lastedit}{{\it 91 April 04}}
\large
\parskip 3mm
\textwidth 6.5in
\linewidth 6.5in
\marginparsep 0in
\oddsidemargin 0in
\evensidemargin 0in
\topmargin -.5in
\headheight 0in
\headsep 0.25in
\textheight 9.25in
\headheight 0.25in
\pretolerance=10000
\parindent 0in

\newcommand{\beq}{\begin{equation}}       % start equation
\newcommand{\eeq}{\end{equation}}
\newcommand{\uvdata}{{\it uv}-data~}
\newcommand{\beddes}{\begin{description} \leftmargin 2cm} % description list
\newcommand{\eeddes}{\end{description}} % description list
\newcommand{\backs}{$\backslash$}
\newcommand{\myitem}[1]{\item{\makebox[2cm][l]{\bf {#1}}}}
\newcommand{\mybitem}[1]{\item{\makebox[0.65cm][l]{\sc {#1}}}}
\newcommand{\AIPS}{{$\cal AIPS$~}}
\newcommand{\APEIN}[1]{{\normalsize \sc {#1}}}
\newcommand{\IF}{{\normalsize \sc IF}~}
\newcommand{\SN}{{\normalsize \sc SN}~}
\newcommand{\SU}{{\normalsize \sc SU}~}
\newcommand{\CL}{{\normalsize \sc CL}~}
\newcommand{\TCTES}{{\normalsize \sc 3C286}~}
\newcommand{\TCOTE}{{\normalsize \sc 3C138}~}
\newcommand{\normalstyle}{\baselineskip 7mm \parskip 1mm \large}
\newcommand{\tablestyle}{\baselineskip 4mm \parskip 0mm \normalsize }

\begin{document}
\pagestyle{myheadings}
\newcommand{\HEADING}{{\it \AIPS Calibration Summary} \hfill
\AIPS Memo Number 68 \hfill Page~~}
\markboth{\HEADING}{\HEADING}
\vskip -.5cm
\pretolerance 10000
\normalstyle
\listparindent 0cm
\labelsep 0cm
\centerline{\huge{\it Summary of \AIPS UV-data Calibration}}

\centerline{{\it From VLA Archive Tape to a UV FITS Tape}}
%\centerline{Glen Langston and Dean Schlemmer}
\centerline{\lastedit}

The Gentle User enters the Computer room with their VLA archive
tape containing a scientific breakthrough.
For the sake of demonstration, let's call the user's sources
\APEIN{source1} and \APEIN{source2}.
The interferometer phase is calibrated by observations of the
calibration sources \APEIN{cal1} and \APEIN{cal2}.
The flux density scale is calibrated by observing \TCTES.
Mount your tape on drive number {\it n}, log in and start \AIPS.
Example user input: \APEIN{AIPS NEW}.  Mount the tape:
\APEIN{INTAP {\it n}; DENS=6250; MOUNT}.
\beddes
\myitem{PRTTP} Find out what is on the tape, get project number and
bands: \APEIN{TASK='PRTTP'; PRTLEV=-2; NFILES=0; INP;GO; WAIT; REWIND}.
\myitem{FILLM} Load your data from tape.
\APEIN{TASK='FILLM'; VLAOBS='?'; BAND=''; DOALL=1; NFILES={\it m}; INP;GO}.
FILLM will load your visibilities (UV data) into a large file
and create 6 \AIPS tables.
The tables have two letter names:
\tablestyle
\beddes
\mybitem{HI} Human readable history of things done to your data.
Use PRTHI to read it.
\mybitem{AN} Antenna location and polarization tables.  Antenna
polarization calibration is placed here.
\mybitem{NX} Index into visibility file based source name and
observation time.  Not modified by calibration.
\mybitem{SU} Source table contains the list of sources observed
and indexes into the frequency table.  The flux densities of the
calibration sources are entered into this table.
\mybitem{FQ} Frequencies of observation and bandwidth with index
into visibility data. Not modified.
\mybitem{CL} Calibration table describing the antenna based gains.
Version 1 should never be modified. Ultimate goal of calibration
is to create a good version 2.  Use PRTAB to read tables.
\eeddes
\normalstyle
\myitem{PRTAN} Print out the antenna locations (\APEIN{PRTLEV=0; TASK
'PRTAN'; INP; GO}) and choose a good Reference antenna
near the center of the array (\APEIN{REFANT=?}). Check the VLA
operater log to make sure the antenna was OK during the entire observation.


\myitem{LISTR} Lists your UV data in a variety of ways.  Make a list
of your observations:
\APEIN{TASK='LISTR'; OPTYP='SCAN'; DOCRT=-1; CALCODE=''; SOUR=''; TIMER 0;
INP;GO}. NOTE: If you have observed in a such a way as to create more than one
\APEIN{FREQID}, you must run through the entire calibration procedure which
follows {\it ONCE FOR EACH} \APEIN{FREQID}. For new users, it is better at this
point to use \APEIN{UVCOP} to copy each \APEIN{FREQID} into separate files
and then calibrate each file separately.
\myitem{UVCOP} Skip this step if your data consists of only one
\APEIN{FREQID}. Copies different \APEIN{FREQID}s into separate files.
\APEIN{TAST='UVCOP'; FREQID=?; OUTNAME='?'; OUTDI=INDI
; INP; GO}. The
result will be a .\APEIN{UVCOP} file.
\myitem{SETJY} Sets the flux of your flux calibration source in the \SU
table:
\APEIN{TASK='SETJY'; SOUR='3C286',''; OPTYP='CALC'; INP;GO}.
\myitem{TASAV} As insurance, make a copy of all your tables:
\APEIN{TASK='TASAV'; CLRON; OUTDI=INDI; INP;GO}.
\myitem{CALIB} \APEIN{CALIB} is the heart of the \AIPS
calibration package.
Execute \APEIN{VLAPROCS}, an \AIPS ``runfile'', to create
procedures \APEIN{VLACALIB, VLACLCAL} and \APEIN{VLARESET} (\APEIN{RUN
VLAPROCS}). The procedure \APEIN{VLACALIB} runs \APEIN{CALIB}.
Set the UV and Antenna limits for \APEIN{3C286}.
For L, C and X band, 10\% and 10 degree errors are OK;
for other bands the limits are higher.
\tablestyle
\beddes
\mybitem{SN} Solution table contain antenna based gains corrections.
These \SN table results are latter placed in a \CL table by task
\APEIN{CLCAL}.
\eeddes
\normalstyle
\APEIN{TASK='VLACAL'; CALS='3C286',''; CALCODE='*';~REFANT=?;
 UVRA=0; MINAMP=10; MINPH=10; INP; VLACAL}.
The task \APEIN{CALIB} lists antenna pairs which deviate
significantly from the solution.

\myitem{TVFLG} If you have lots of errors, then
carefully examine your data using \APEIN{TVFLG}. (See \AIPS Cookbook)~
If only a few antenna pairs are bad over a limited time range, use
\APEIN{UVFLG} to flag that antenna for the time from just after the previous
good \APEIN{cal} observation to before the next good \APEIN{cal} observation
and then run \APEIN{VLACAL} again.
\myitem{UVFLG} Flags bad UV-data. Skip this step if you have no bad data.
\APEIN{TASK='UVFLG'; ANTEN=?,0; BASELI=0; TIMER=?; FLAGV=1;
SOUR=''; OPCOD=''; INP;GO}.
If in doubt about any \uvdata, \APEIN{FLAG THEM!}
This will create a Flag Table (\APEIN{FG}).  You want to use
\APEIN{FG} table version 1 for all tasks.
\tablestyle
\beddes
\mybitem{FG} A flag table marks bad data. FG tables contain
an index into the UV data based
on time range, antenna number, frequency and \IF number.
\eeddes
\normalstyle
\myitem{CALIB} Now calibrate the antenna gain based on the
rest of the cal sources.
Look in the Calibrator manual for UV limits; If there are limits,
\APEIN{VLACAL} must be run separately for these sources (i.e. enter \APEIN{
TGET VLACAL; CALS='?',''; ANTEN=?; BASELI=0; INP; VLACAL} for \APEIN{cal1}
and then again for \APEIN{cal2}). Otherwise:
\APEIN{TGET VLACAL; CALS='cal1','cal2',''; ANTENN=0; BASELI=0; INP; VLACAL}.
Flag bad baselines listed.  Continue if only a few are listed, otherwise
run VLACAL again.
\myitem{GETJY} Sets the flux of phase calibration sources in the \SU table.
\APEIN{TASK 'GETJY'; SOUR='cal1','cal2',''; CALS='3C286','';
BIF=0; EIF=0; INP;GO}.
\myitem{TASAV} Good time to save your tables:
\APEIN{TGET='TASAV'; OUTDI=INDI; CLRON; INP;GO}.
\myitem{CLCAL} Calibrate the antenna gain and interpolates it into
a new \CL table.
Each execution of \APEIN{CLCAL} adds to
output \CL table version 2.
\APEIN{CLCAL} is run using the procedure \APEIN{VLACLCAL}.~
\APEIN{TASK='VLACLC'; SOUR='source1','cal1',''; CALS='cal1','';
OPCODE='CALI'; TIMER=0; INTERP='2PT'; INP; VLACLC}.
Run \APEIN{CLCAL} for the second source using the second calibrator:
\APEIN{TGET VLACLC; SOUR='source2','cal2',''; CALS='cal2',''; INP;
VLACLC}. Next, self-calibrate the flux calibrator: \APEIN{TGET VLACLC;
SOUR='3C286',''; CALS='3C286',''; INP; VLACLC}.~
\myitem{LISTR} Make a matrix listing of the Amplitude and RMS of
calibration sources with calibration applied:
\APEIN{TASK='LISTR'; OPTYP='MATX'; SOUR='cal1','cal2',''; DOCAL=1;
DOCRT=-1; DPARM=3,1,0; UVRA=0; ANTEN=0; BASELI=0; BIF=1; INP;GO}.~
Look for antenna pairs with wild RMSs and flag them with \APEIN{UVFLG}.
If only a few are bad, continue, else delete \CL table 2 and the \SN table
using \APEIN{VLARESET}. Then return to the first \APEIN{CALIB} step.
If the data look good, run \APEIN{LISTR} again for the remaining
\IF(s). \APEIN{TGET LISTR; BIF=2; INP;GO}
\myitem{UVPLT} Plots the \uvdata in a variety of ways.  Make at Flux
versus Time plot first. Choose \APEIN{XINC} so the plot will have
approximately 1000 points (divide the number of visibilities by 1000 and
choose the closest prime number to that).
Set \APEIN{ANTEN=0; BASELI=0; TIMER=0}. Then:
\APEIN{TASK='UVPLT'; SOUR='source1','',''; XINC=13; BPARM(1)=11;
DOCAL=1; BIF=1; INP;GO}.~
Repeat \APEIN{UVPLT} with your calibrators also.
Look at the plots with \APEIN{QMSPL, TVPL} or \APEIN{TXPL} (for plotting
on the QMS, the TV, or the terminal, respectively).
Plot other \IF(s). Flag wild points using \APEIN{UVFND} and either
\APEIN{UVFLG} or \APEIN{CLIP}. Plot Flux versus baseline:
\APEIN{TGET UVPLT; BPARM=0; INP;GO}.

If the calibration failed because of a bad reference antenna or too much
noisy data, you may reset the parameters with: \APEIN{INP VLARESET; VLARESET}
This will bring you back to the first \APEIN{CALIB} step above.

\eeddes
Calibration is now complete for continuum, un-polarized observations.
Skip down to FITTP.
For polarization observations, the following steps are required.
For 21cm or longer wavelength observations, ionospheric Faraday
rotation corrections may be needed.  See FARAD in the \AIPS cookbook.

\begin{figure}[h]
\vskip 4in
{\it \hskip 1.5in a) \hfill b) \hskip 1.5in}

{\bf Figure:}
{\it a)} Uncalibrated \uvdata and  {\it b)}
calibrated \uvdata from an X-band snapshot of 3C286.
Default VLA gains are a tenth of the actual gains and
show significant scatter.
Only wild \uvdata points $\sim$50 \% greater than the average
can be detected before calibration.
\end{figure}

\clearpage
\centerline{\bf{POLARIZATION CALIBRATION}}
\beddes
\myitem{TASAV} As added insurance, save your tables again:
\APEIN{TGET TASAV; INP;GO}.
\myitem{LISTR} Examine the parallactic angles of your calibrator observations:
\APEIN{TASK='LISTR'; ANTEN=0; SOUR=''; CALCOD='*'; OPTYPE='GAIN'; DPARM=9,0;
INP; GO.}
\myitem{PCAL} Intrinsic antenna polarization calculation.  This step
is only possible if you have observed calibration sources at many
parallactic angles. PCAL will only modify the \APEIN{AN} table.
\APEIN{TASK='PCAL'; CALS='cal1','cal2',''; BIF=1; EIF=2;
REFANT=?;  INP;GO}
\myitem{TACOP} Make a copy of the last \APEIN{CL} table;
In case the \APEIN{CLOCR} fails, the original \APEIN{CL} table will be
preserved. \APEIN{TASK='TACOP'; OUTDI=INDI ; INEXT='CL'; INVER=2; NCOUNT=1;
OUTVER=3; INP; GO}. Use \APEIN{CL} table version 3 for all following steps.
\myitem{LISTR} Now determine the absolute linear
polarization angle.  Make a matrix listing of the angle of \TCTES.
The observed angles
are different for each frequency and \IF.
\APEIN{TASK='LISTR'; SOUR='3C286',''; DOCAL=1; GAINUSE=3; BIF=1; DOPOL=1;
OPTYP='MATX';
INP; GO}.
Record the matrix average angle, $\phi_1$, for \IF 1.
Run LISTR again for \IF 2.
\APEIN{TASK='LISTR'; BIF=2; INP; GO}.
Record the matrix average angle, $\phi_2$, for \IF 2.
\myitem{CLCOR} Now apply the angle correction to CL table 3.
\APEIN{CLCOR} needs only to be run once, unless you make a mistake.
The phase correction is applied to the Left circularly polarized
signal.  (The relative phase of L and R produces the
linear polarization angle)
The angle of linear polarization for \TCTES is $66^o$.
(For \TCOTE, $\phi=-24^o$.)
\APEIN{TASK='CLCOR'; STOKES='L'; SOUR=''; OPCOD='POLR'; BIF=1; EIF=2;
\mbox{GAINVER=3; CLCORPA=66-$\phi_1$,66-$\phi_2$,0;} INP; GO}.~
Run \APEIN{LISTR} again to check the phases.~
\APEIN{TGET LISTR; DOPOL=1; INP; GO}.~
Check the phases, if they are wrong run \APEIN{CLCOR} again.
\APEIN{TGET CLCOR; OPCOD='PHAS';
\mbox{CLCORPA=66-$\phi'_1$,66-$\phi'_2$,0;} INP;GO}~
\myitem{FITTP} Writes the output \uvdata to tape.
\APEIN{DISMOUNT} your archive; \APEIN{MOUNT} your output tape.
\APEIN{TASK='FITTP'; DOEOT=-1;BLOCK=10; OUTTAP=INTAP; INP;GO}.
\myitem{Mapping} See \AIPS cookbook for instructions on
using \APEIN{TASK='SPLIT'} to create a single source data set.
Next use your favorite Fourier Transform task
(i.e. \APEIN{MX} or \APEIN{HORUS}).
Automatic imaging and self-calibration is now possible using the \AIPS
procedure \APEIN {MAPIT}. See the \AIPS \APEIN {MAPIT} memo for more details.
\eeddes


Please send comments to Glen Langston or Dean Schlemmer, NRAO-Charlottesville.
E-mail addresses: glangsto@nrao.edu, dschlemm@nrao.edu
\end{document}


