AIPS NRAO AIPS HELP file for ELINT in 31DEC25



As of Wed Dec 11 6:34:20 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).

AIPS