AIPS HELP file for ELINT in 31DEC24
As of Wed Apr 24 19:30:41 2024
ELINT: Determines and removes gain dependence on elevation
INPUTS
INNAME Input UV file name (name)
INCLASS Input UV file name (class)
INSEQ 0.0 9999.0 Input UV file name (seq. #)
INDISK Input UV file disk unit #
INVERS 0.0 9999.0 Input SN table version
0 => high
GAINVER Input CL table to copy to
CL=high+1 and then correct
0=>high
SOURCES Source list ' '=>all.
CALSOUR Calib. list. Do not use ' '
QUAL -10.0 Calibrator qualifier -1=>all
CALCODE Calibrator code ' '=>all
STOKES Stokes type to process
SELBAND Bandwidth to select (kHz)
SELFREQ Frequency to select (MHz)
FREQID Freq. ID to select, 0=>all
BIF 0.0 100.0 Lowest IF number 0=>all
EIF 0.0 100.0 Highest IF number 0=>all
TIMERANG Time range to use. 0=>all
ANTENNAS Antennas to correct. 0=>all
SUBARRAY 0.0 9999.0 Subarray; 0 => 1.
NPLOTS Number of plots per page
0=>5, -1=> Don't make plots
XINC 0.0 5000.0 Plot every XINC'th point
OPTYPE ' ' OR 'AMPL' => gain fit
without opacity
'AMPT' => fit both gain and
opacity (see HELP)
OPCODE Fit type: ' ' => 'POLE'
'POLE' Ampl. vs. Elevation
'POLZ' Ampl. vs. zenith dist.
'PWR ' Power vs. zenith dist.
'PWRN' Power vs. zenith dist.
normalized.
DPARM (1) Scale to 1.0 at elevation
DPARM(1) 0 -> 50 deg
< 0 -> no normalization
(2) >0 Display physical parms
b0 + b2*(E-b3)^2
DOPLOT 0.0 3.0 2 all solutions 1 plot
3 one solution from all data
PRTLEV 0=> no printout.
1 => print coefficients
2 => print coefficients
and their errors
and rms of residual
see help.
>10 => see help
DO3COLOR -1.0 3.0 > 0 use 3-color symbols for
different sources
= 3 plot colored names
DOALL -10.0 10.0 > 0 => plot all times
= +10 or -10 no points
DOHIST >0 => put coefficients in
history file.
PIXRANGE (2)>(1) fixed plot scale
DOTV -1.0 1.0 > 0 Do plot on the TV, else
make a plot file
GRCHAN 0.0 8.0 Graphics channel 0 => several
BADDISK 0.0 9999.0 Disks to aviod for scratch
HELP SECTION
ELINT
Task: Determines and removes gain dependence on elevation
Adverbs:
INNAME.....Input UV file name (name). Standard defaults.
INCLASS....Input UV file name (class). Standard defaults.
INSEQ......Input UV file name (seq. #). 0 => highest.
INDISK.....Disk drive # of input UV file. 0 => any.
INVERS.....Input SN table version number. 0 => high.
GAINVER....Input CL table version. If GAINVER <= -1, no CL table is
modified. If GAINVER is equal zero or greater than the
total number of the CL tables then GAINVER is equal to the
last existing CL table. The input CL table version
(GAINVER) is copied to the output CL table version =
(high+1), and then the output CL table is corrected.
SOURCES....list of sources to process.
' ' = all; a "-" before any source name means ALL listed
sources will be skipped.
CALSOUR....list of calibrators to use.
Do not use ' '; a "-" before any calibrator name
means ALL listed calibrators will be skipped.
CALSOUR(1) is the flux density standard source.
QUAL.......Only calibrators with a source qualifier number in the SU
table matching QUAL will be used if QUAL is not -1.
CALCODE....Calibrators may be selected on the basis of the calibrator
code:
' ' => any calibrator code selected
'* ' => any non blank code (cal. only)
'-CAL' => blank codes only (no calibrators)
anything else = calibrator code to select.
NB: The CALCODE test is applied in addition to the other
tests, i.e. CALSOUR and QUAL, in the selection of sources
for which to determine solutions.
STOKES.....The desired Stokes type of the output data:
'R', 'L', ' '=> all available.
SELBAN.....Bandwidth to select (kHz)
SELFREQ....Frequency to select (MHz)
FREQID.....Freq. ID to select. 0=>all
BIF........First IF to process. 0=>all.
EIF........Highest IF to process. 0=>all higher than BIF
TIMERANG...Time range of the data to be used. In order:
Start day, hour, min. sec, end day, hour, min. sec.
Days relative to reference date. 0=>all
ANTENNAS...A list of the antennas to be calibrated. If any
number is negative then all antennas listed are
ignored. All 0 => use all antennas.
SUBARRAY...The subarray to calibrate. Does only one at a time.
NPLOTS.....Number of gain plots per page; 0=>5.
If NPLOTS < 0, then no plots are made.
XINC.......Plot every XINC'th point
OPTYPE.....Data to be fitted: 'AMP ', ' ', 'AMPL'= ampl.
without opacity fit, 'AMPT' = ampl.+opacity fit.
'AMPT' is experimental and not recommended for use.
OPCODE.....Fit type:
'POLE': G = G0 + G1*ELEV + G2*ELEV*ELEV,
ELEV in degrees
'POLZ': G = G0 + G1*ZA + G2*ZA*ZA,
ZA in degrees
'PWR ': G = G0 + G1*ZA + G2*ZA*ZA,
ZA in degrees
In this type of solution, the 'data'
are taken as 1 over the raw data squared.
'PWRN': as 'PWR ', but coefficients are
normalized before being printed/put in
history file.
' ' => 'POLE'
DOPLOT.....2 => Plot all solutions for an antenna/polarization on a
single plot. Included IFs are colored yellow, green,
pink, cyan, yellow, green, ...iff GRCHAN=0
3 => Fit all selected data for one solution and then
plot it per antenna and polarization
else plot each SPW/polarization/antenna separately with
NPLOTS control
PRTLEV.....0 => Don't print the coefficients.
1 => print the coefficients for each antenna,
IF and Stokes.
2 => print coefficients and their errors and
rms of residual for each antenna, IF and Stokes.
If a second digit is included (e.g. '21' or '11'),
the coefficients are written in the form:
G = Gm + G2*(ZA - Zm)^2; Gm = min. correction,
Zm = angle of min. correction (= max gain).
DO3COLOR...> 0 => use true color to separate sources
> 2.5 => print a line with the source names in the
appropriate colors in each plot area
<= 0 => use truecolor to separate IFs in DOPLOT=2
starting with red for BIF. Else the graphics
colors are used: yellow, green, pink, cyan, yellow,
green , ...
DOALL......Use TIMERANG when doing the fit of the data always,
but when DOALL > 0, plot data from all times.
DOHIST.....if DOHIST > 0, the gain coefficients are written
into the history file.
PIXRANGE...When PIXRANGE(2) > PIXRANGE(1), use these values as
a fixed scale for all plots
DOTV.......> 0 Do plot on the TV, else make plot files
GRCHAN.....Graphics channel 0 => several
BADDISK....A list of disks on which scratch files are not to
be placed. This will not affect the output file.
EXPLAIN SECTION
ELINT: Task to apply corrections to an CL table as a function
of elevation or zenith distance.
Documentors: L.R. Kogan, B. Butler, R. Perley
Related Programs: CLCAL, SNPLT
PURPOSE
The widely used task CLCAL provides for the interpolation of antenna
gains measured on calibrators to the target sources. The
interpolation is carried out as a function of time. If the elevation
difference between calibrator and target sources is large, (either due
to a large physical or time separation), significant errors can
result, especially at high frequencies where there is a strong
dependence of antenna gain on elevation. The task ELINT will both
solve for the gain dependence on elevation, and will implement the
required corrections into an CL table. In addition, ELINT will solve
for the flux densities of the calibrators used, assuming the flux
density of the first calibrator is known.
The input data is an SN table obtained as a result of preliminary
calibration using a set of selected calibrators. The task fits a given
type of fitting function to these data. This functional form is then
used to interpolate gain values for all sources. The fitting is done
independently for each antenna, each IF, and each polarization
(Stokes).
The simplest mode of operation is to determine the gain dependence
using only a single calibrator whose elevation range matches or
exceeds that of the target sources.
In many situations however, the elevation range covered by a single
calibrator is not sufficient, while that of all, or many calibrators,
is. In this case, ELINT can solve for *both* the elevation gain
dependence, and the flux density ratios between the calibrators,
assuming the first-named calibrator is the flux density reference. It
then determines the corrected flux densities of the calibrators.
ELINT does *not* enter these new values into the SU table, however.
The result of fitting can be displayed on the TV or recorded in a
plot file. The average (for all selected antennas, IF's, and Stokes)
found voltage factors, (MEANFACTOR), original flux densities of
selected calibrators (FLUXOLD) and corrected flux densities of the
calibrators (FLUXNEW) are printed at display. The determined
correction of the antennas' gain vs. elevation is written in an output
CL table for all selected target sources.
The program fits a third order polynomial to the data. The type of
fit is controlled by the OPCODE adverb: 'POLE' fits the amplitude
vs. elevation, 'POLZ' (the default) fits the amplitude vs. zenith
distance, 'PWR ' fits the power (1/amplitude*amplitude) vs. zenith
distance, while 'PWRN' normalizes these coefficients to maximum unity
gain. At this time (Dec '96) only amplitude data are fitted -- others
are planned in the future. The purpose of OPCODEs 'PWR ' and 'PWRN'
is to permit measurement of the power gain dependence, instead of
voltage gain correction.
For testing purposes, we have implemented an OPTYPE command to
additionally fit for the opacity (following a law of the form
exp(-tau/cos z)) as well as the polynomial form described above. This
is turned on by setting OPTYPE to 'AMPT'. Use of this option is not
recommended -- it could only be useful in situations of high optical
depth (such as at the upper end of Q-band, or a soaking wet day at
K-band). OPTYPE = 'AMPL', or ' ' is the normal mode.
ELINT should be run as the initial step in calibration. A
normal calibration sequence, using ELINT, would be:
1) Do an opacity correction if you know the atmospheric opacity at
the time (e.g., via use of the TIPPER function). To do this,
copy CL table 1 to table 2 (via TACOP), then run CLCOR, with
OPCODE = 'OPAC', CLCORPRM(1) = zenith opacity in nepers.
This step is optional, as ELINT can solve for the entire
elevation dependence (both opacity and antenna dependent gain)
but helps in certain cases.
2) Run CALIB on one, or many calibrators. If step 1 was
done, make sure to set DOCALIB = 1;GAINUSE = 2.
3) Run ELINT to determine the elevation gain. If one
calibrator alone covers the range of elevation, use just
that one. If many are required, use them all. Put
'SOURCES' equal to all your objects, both targets and
calibrators (or leave blank). CALSOUR(1) is your flux density
standard. ELINT will estimate the gain dependendence on elevation
fitting the second order polynom to the input SN table data for
each antenna and apply the corrections for the list of the sources
to the output CL table.
Examine the plots of the fits to convince yourself of their
validity.
4) Continue with normal calibration, using CALIB, GETJY,
CLCAL, etc. Be sure to apply the calibration when running
CALIB!
IMPORTANT! If your phase stability is poor (phases changing
by near a radian within the calibrator scans) and the calibrators' SNR
is not high (this is a common combination), you should calibrate out
the phase gradients within each calibrator scan before solving for the
antenna gains. To do this, generate a new default CL table with a
time interval as short as the timescale for significant phase changes
(this can be as short as 3 seconds -- in which case your visibility
integration time had better be as short !), and run CALIB, with
SOLMODE = 'P'. Then CLCAL this with INTERPOL = 'SIMP' (for all
sources, including the calibrators) to remove these phase changes.
Then proceed as described above, with all CL tables incremented by one
(since CL#2 now contains the needed phase changes).