%-----------------------------------------------------------------------
%;  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 November 27}}
\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{\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]{{\large \tt #1}}
\newcommand{\uvdata}{{\it uv}-data}
\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{\FREQID}{{\normalsize \sc FREQID}}
\newcommand{\normalstyle}{\baselineskip 8mm \parskip 1mm \large}
\newcommand{\tablestyle}{\baselineskip 4mm \parskip 0mm \normalsize }

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

\centerline{{\it From VLA Archive Tape to a UV FITS Tape}}
\normalsize
\centerline{{\it Supersedes \AIPS Memo 68}}
\centerline{\lastedit}
%\centerline{Glen Langston}

\normalstyle
The Gentle User enters the Computer room with a VLA archive
tape containing a scientific breakthrough.
The user's sources are named \APEIN{source1} and \APEIN{source2}.
The interferometer phase is calibrated by observations of
\APEIN{cal1} and \APEIN{cal2}.
The flux density scale is calibrated by observing \TCTES\
(=1328+307 or 1331+305).
Mount the tape on drive number {\it n}, log in and start \AIPS.
Example input: \APEIN{AIPS NEW}.  Mount the tape:
\APEIN{INTAPE={\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.
Select only one band at a time to process.
\APEIN{TASK='FILLM'; VLAOBS='?'; BAND='?'; NFILES={\it m}; INP;GO}.
FILLM will load your visibilities (\uvdata) into a large file
and create 6 \AIPS tables.
The tables have two letter names described below.
\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.
The CL table contains entries at regular time intervals (i.e. 2
minutes) for each antenna.
{\bf The ultimate goal of calibration is to create a good \CL version 2.}
Use PRTAB to read tables.
\eeddes
\normalstyle
\myitem{PRTAN} Print out the antenna locations.
\APEIN{TASK='PRTAN'; PRTLEV=0; INP; GO}.
Choose a good {\it Reference} antenna (called {\it R})
near the center of the array (\APEIN{REFANT=R}).
Check the VLA operator log to make sure the antenna was OK
during the entire observation.
\myitem{QUACK} Flag the bad points at the beginning of each
scan, even the ones with good amplitudes could have bad phases.
Creates a Flag Table (\APEIN{FG}).  You want to use
\APEIN{FG} table version 1 for all tasks.
\APEIN{TASK='QUACK'; FLAGV=1; OPCOD='~'; APARM=0; SOUR='~'; INP;GO}
\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{LISTR} Lists your UV data in a variety of ways.  Make a list
of your observations.
\APEIN{TASK='LISTR'; OPTYP='SCAN'; DOCRT=-1; SOUR='~'; CALC='*';}
\APEIN{TIMER=0; INP;GO}.
NOTE: IF you have observed in a such a way as to create more than one
\FREQID,  you must run through the entire calibration
once for EACH \FREQID.
For new users, it is better to use \APEIN{UVCOP} to copy each
\FREQID\ into separate files and calibrate each file separately.
\myitem{UVCOP} Skip this step if your data consists of only one \FREQID.
Copy different \FREQID s into separate files.
\APEIN{TASK='UVCOP'; FREQID=?; CLRON; 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'; FREQID=1; INP;GO}.
Correct for partial resolution using the VLA Calibration Source
Manual or the \AIPS\ Cookbook.
\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.
\APEIN{RUN VLAPROCS}, an \AIPS\ {\it runfile}, to create
procedures \APEIN{VLACALIB, VLACLCAL} and \APEIN{VLARESET}.
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.
\APEIN{CALIB} places antenna amplitude and phase corrections into
an \SN table for the
time of observation of phase calibration sources.
\tablestyle
\beddes
\mybitem{SN} Solution table contains antenna based amplitude
and phase corrections for the time of observations of the calibration
sources.
These \SN table results are latter interpolated for all times
of observation and placed in a \CL table.
Only the \CL table corrections will be applied to the program sources.
\eeddes
\normalstyle
\APEIN{TASK='VLACAL';}~ \APEIN{CALS='3C286','~';}~
\APEIN{CALCODE='*';}~ \APEIN{REFANT={\it R};}~
\APEIN{UVRA=?; SNVER=1;}~
\APEIN{MINAMP=10; MINPH=10; INP; VLACAL}.
The task \APEIN{CALIB} lists antenna pairs which deviate
significantly from the solution.
If you have lots of errors, then
carefully examine your data using \APEIN{TVFLG}. (See \AIPS Cookbook)~
If one antenna is 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.
\myitem{UVFLG} Flag bad UV-data.
\APEIN{TASK='UVFLG'; ANTEN=?,0; BASELI=?,0; TIMER=?; FLAGV=1;
SOUR='~'; OPCOD='~'; INP;GO}.~
If in doubt about any data, \APEIN{FLAG THEM!}
\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.
\APEIN{TGET VLACAL; CALS='cal1','cal2','~'; ANTEN=0; BASELI=0; INP; VLACAL}.
Flag bad baselines listed.  Each execution of \APEIN{CALIB} replaces
previous corrections in the \SN table or appends new corrections.
If unsatisfied with a \APEIN{VLACAL} execution, all effects
of it are removed by running \APEIN{VLACAL} again
for the same sources (but different \APEIN{ADVERBS}
or after flagging bad data).
\myitem{GETJY} Sets the flux of phase calibration sources in the \SU table.
\APEIN{TASK 'GETJY'; SOUR='cal1,'cal2','~';}~
\APEIN{CALS='3C286','~'; BIF=0; EIF=0; INP;GO}.~
\APEIN{GETJY} over-writes existing \SU table
entries, and is not effected by previous executions.
\myitem{TASAV} Good time to save your tables.
\APEIN{TGET TASAV; INP;GO}.~
\myitem{CLCAL} Read the antenna amplitude and phase corrections from
the
\SN table and interpolate the corrections into a new \CL table.~
\APEIN{CLCAL} applies calibration source corrections to the
program sources.
Each execution of \APEIN{CLCAL} adds to output \CL table version 2.
\APEIN{CLCAL} is run using the procedure \APEIN{VLACLCAL}.~
\APEIN{TASK='VLACLC';}~ \APEIN{SOUR='source1','cal1','~';}~
\APEIN{CALS='cal1','~'; OPCODE='CALI';}~
\APEIN{TIMER=0;}~
\APEIN{INTERP='2PT';}~ \APEIN{INP; VLACLC}.~
Run \APEIN{CLCAL} for the second source using the second calibrator.
\APEIN{TGET VLACLC; SOUR='source2','cal2','~'; CALS='cal2','~'; INP;
VLACLC}.~
Move the \SN table corrections for \TCTES\ into the \CL table.
\APEIN{TGET VLACLC; SOUR='3C286','~';CALS='3C286','~'; INP; VLACLC}.
(\TCTES\ could also be calibrated with \APEIN{cal1} or \APEIN{cal2}.)
\eeddes
\clearpage

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

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

\begin{description}
\myitem{LISTR} Make a matrix listing of the Amplitude and RMS of
calibration sources with calibration applied.  Look for wild points.~
\APEIN{TASK='LISTR'; OPTYP='MATX'; SOUR='cal1','cal2','~'; DOCAL=1;}~
\APEIN{DOCRT=-1; DPARM=3,1,0; UVRA=0; ANTEN=0; BASELI=0; BIF=1; INP;GO}.~
If only a few points are bad, flag them and continue.
If too many are bad, delete \CL table 2 and the \SN
tables using \APEIN{VLARESET}.
Then return to the first \APEIN{CALIB} step.
If the data look good, run \APEIN{LISTR} again for \IF two.
\APEIN{TGET LISTR; BIF=2; INP;GO}
\myitem{UVPLT} Plot the \uvdata\ in a variety of ways.  Make at Flux
versus Time plot first.
Choose \APEIN{XINC} so the plot will have no more
than 1000 points.
\APEIN{TASK='UVPLT'; SOUR='source1','~'; XINC=10; BPARM(1)=11;
DOCAL=1; BIF=1; INP;GO}.~
Look at the plot with \APEIN{LWPLA, QMSPL, TVPL} or \APEIN{TXPL}.~~
Plot other \IF. Flag wild points. Plot Flux versus baseline.
\APEIN{TGET UVPLT; BPARM=0; INP;GO}.
\eeddes

Calibration is now complete for continuum, un-polarized observations.
Write the calibrated data to tape with \APEIN{FITTP}.
To create images from the \uvdata\ use \APEIN{SPLIT} to calibrate
the multi-source data and create a single source \uvdata\ set.
(\APEIN{FITTP} and \APEIN{SPLIT} are described at the end of the
polarization calibration process.)

\clearpage
\centerline{\bf POLARIZATION CALIBRATION}
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.
\beddes
\myitem{TASAV} As added insurance, save your tables again.
\APEIN{TGET TASAV; INP; GO}.
\myitem{LISTR} Print the parallactic angles of the calibration
sources.
\APEIN{TGET LISTR; SOUR='~'; CALC='*';
OPTYP='GAIN'; DPARM=9,0; INP;GO}~
\myitem{PCAL} Intrinsic antenna polarization calculation.
\APEIN{PCAL} will be successful
only if cal. sources are observed at several parallactic angles.
\APEIN{PCAL} will modify the \APEIN{AN} and \APEIN{SU} tables.
\APEIN{TASK='PCAL'; CALS='cal1','cal2','~'; BIF=1; EIF=2;
REFANT={\it R}; INP;GO}
\myitem{LISTR} Now determine the absolute linear polarization angle.
Make a matrix listing of the angle of \TCTES.
\APEIN{TGET LISTR; SOUR='\TCTES','~'; DOCAL=1; BIF=1; DOPOL=-1;}~
\APEIN{GAINUSE=2; OPTYP='MATX'; DPARM=1,0; STOKES='POLC'; INP; GO}.~
Record the matrix average angle, $\phi_1$, for \IF 1.
The observed angles are different for each frequency and \IF.
Record the matrix average angle, $\phi_2$, for \IF 2
(\APEIN{BIF=2; INP; GO}).
\myitem{CLCOR} Now apply the angle correction to CL table 2.
\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$ and for
\TCOTE, $\phi=-24^o$.
\APEIN{TASK='CLCOR'; STOKES='L'; SOUR='~'; OPCOD='POLR'; BIF=1; EIF=2;
\mbox{CLCORPRM=66-$\phi_1$,66-$\phi_2$,0}; GAINVER=2; INP; GO}.~
Run \APEIN{LISTR} again to check the phases.~
\APEIN{TGET LISTR; DOPOL=1; INP; GO}.~
If the phases are wrong run \APEIN{CLCOR} again.
\APEIN{TGET CLCOR; OPCOD='PHAS';
\mbox{CLCORPRM=66-$\phi'_1$,66-$\phi'_2$,0;} INP; GO}~
\myitem{FITTP} Writes the output {\it uv}-data to tape.
\APEIN{DISMOUNT} your archive; \APEIN{MOUNT} your output tape.
\APEIN{TASK='FITTP'; DOEOT=-1;BLOCK=8; OUTTAP=INTAP; INP; GO}.~
\myitem{SPLIT} The \AIPS calibration process only modifies the tables
associated with the multi-source \uvdata\ set.  \APEIN{SPLIT} selects
individual sources, reads the \CL table and multiplies the
visibilities by the corrections to produce a calibrated single-source
\uvdata\ set.
\APEIN{TASK='SPLIT'; SOUR='~'; CALC='~'; UVRA=0; TIMER=0; DOCAL=1;}
\APEIN{FLAGVER=1; GAINUSE=2; DOPOL=1; DOBAN=-1; BIF=0; EIF=0; STOKES='~';}
\APEIN{BLVER=-1; APARM=0; DOUVCOM=1; CHANSEL=0; INP; GO}
\myitem{Mapping} Use your favorite Fourier Transform task
(e.g. \APEIN{MX} or \APEIN{HORUS}) to produce images from the
calibrated data.  A set of \AIPS procedures (called \APEIN{MAPIT})
has been developed to
automatically Fourier Transform, deconvolve and self-calibrate the
\uvdata.
See \AIPS Memo 72.
\eeddes

Please send comments to Glen Langston, NRAO C'ville.
E-mail address: glangsto@nrao.edu
\end{document}


