AIPS NRAO AIPS HELP file for BPASS in 31DEC25



As of Mon Dec 9 12:32:01 2024


BPASS: Task to generate a "Bandpass" (BP) table.

INPUTS

INNAME                             Input UV file name (name)
INCLASS                            Input UV file name (class)
INSEQ             0.0     9999.0   Input UV file name (seq. #)
INDISK            0.0        9.0   Input UV file disk unit #

                                   Data Selection
CALSOUR                            Bandpass calibrator sources.
QUAL            -10.0              Calibrator qualifier -1=>all
CALCODE                            Calibrator code '    '=>all
UVRANGE                            UV range to select
TIMERANG                           Time range to select
SELBAND                            Bandwidth to select (kHz)
SELFREQ                            Frequency to select (MHz)
FREQID                             Freq. ID to select.
SUBARRAY          0.0     1000.0   Subarray, 0=>all
ANTENNAS                           Antennas to select

                                   CLEAN map (optional)
IN2NAME                            Cleaned map name (name)
IN2CLASS                           Cleaned map name (class)
IN2SEQ            0.0     9999.0   Cleaned map name (seq. #)
IN2DISK           0.0        9.0   Cleaned map disk unit #
INVERS           -1.0    46655.0   CC file version #.
NCOMP                              # comps to use for model.
                                   1 value per field
FLUX                               Lowest CC component used.
NMAPS             0.0     4096.0   No. Clean map files
CMETHOD                            Modeling method:
                                   'DFT','GRID','    '
CMODEL                             Model type: 'COMP','IMAG'
                                   'SUBI' (see HELP re images)
SMODEL                             Source model, 1=flux,2=x,3=y
                                   See HELP SMODEL for details.

                                   Control options
DOCALIB          -1.0      101.0   > 0 calibrate data & weights
                                   > 99 do NOT calibrate weights
GAINUSE                            CL table to apply (SN table
                                   to apply to single-source)
DOPOL            -1.0       10.0   If >0 correct polarization.
PDVER                              PD table to apply (DOPOL>0)
BLVER                              BL table to apply.
FLAGVER                            Flag table version
SOLINT                             Solution interval (mins)
                                   -1 => do whole time range
SOLTYPE                            Soln type,'  ','L1','GCON',
                                      'R', 'L1R', 'GCOR'
REFANT                             Reference antenna : choose
                                   wisely!
OUTVERS                            Output BP table version
                                   0 => a new table to be
                                        generated.
SMOOTH                             Smoothing function.
                                   BE VERY CAREFUL HERE.
ANTWT                              Ant. wts (0 => 1.)
WEIGHTIT          0.0        3.0   Modify data weights function
MINAMPER          0.0              Amplitude closure error
                                   regarded as excessive in  percent
MINPHSER          0.0              Phase closure error regarded
                                   as excessive in degrees
MINANTEN          0.0              Minimum number of antennas to
                                   attempt a solution.
BPASSPRM                           Control information:
                                   1: if > 0 use only the
                                      autocorrelation data.
                                      < 0 solve only for P
                                      = 0 solve for A&P
                                   2: print level - see help
                                   3: If > 0 do not divide data
                                      by source model
                                   4: If > 0 store phases only
                                      in the BP table.  If < 0
                                      store amplitudes only.
                                   5: Divide by 'channel 0'
                                      **** CHANGED MAY 2010 ****
                                   6: amp closure error limit -
                                      print channels averaging
                                      over this if (2) > 0
                                   7: phase closure error limit
                                      print channels averaging
                                      over this if (2) > 0
                                   8: > 0 => scalar average
                                   9: > 0 => interpolate over
                                      flagged channels if poss.
                                   10:1 => normalize amplitudes
                                        using all channels
                                      2 => normalize amplitudes
                                        using ICHANSEL channels
                                      3 => normalize amplitudes
                                        and zero average phase
                                        using ICHANSEL channels
                                      4 => normalize amplitudes
                                        and zero average phase
                                        using all channels
                                      5 => normalize amplitudes
                                        and zero average phase
                                        using ICHANSEL channels
                                        in power not voltage
                                      6 => normalize amplitudes
                                        and zero average phase
                                        using all channels in
                                        power not voltage
                                      7 => normalize amplitudes
                                        and zero average phase
                                        using ICHANSEL channels
                                        and medians
                                      8 => normalize amplitudes
                                        and zero average phase
                                        using all channels and
                                        medians
                                      9 => normalize amplitudes
                                        only using ICHANSEL
                                        channels and medians
                                     10 => normalize amplitudes
                                        only using all channels
                                        and medians
                                      0 => no deliberate norm.
                                   11: > 0 solution weights are
                                      independent of channel
                                      = -1 weights scaled
                                        by amplitude**2
                                      < -1.5 weights scaled by
                                        1 / amplitude**2
ICHANSEL                           Array of start and stop chan
                                   numbers, plus a channel
                                   increment and IF to be used
                                   to select channels to sum to
                                   find a 'channel 0'.  If all
                                   0, range set to inner 75 percent of
                                   observing band.
DOSCALE          -1.0         2.0  = -1 -> no spectral index
                                      correction
                                   - 0, 1 -> fit spectral index
                                   = 2 -> fit curvature also
SPECINDX                           Spectral index to correct
                                      for first cal; 0 -> fit
SPECURVE                           Spectral index curvature
                                   'Channel 0' uv-data
IN3NAME                            Channel 0 uv name (name)
                                   must be '' to suppress option
IN3CLASS                           Channel 0 uv name (class)
                                   must be '' to suppress option
IN3SEQ            0.0     9999.0   Channel 0 uv name (seq. #)
IN3DISK           0.0        9.0   Channel 0 uv disk unit #
BADDISK           0.0     9999.0   Disks to avoid for scratch

HELP SECTION

BPASS
Task:  To create a 'BP' (bandpass) table which will contain the bandpass
   response functions of the antennas. The program can form the
   functions in two ways: a) by decomposing the baseline-based functions
   (using a least-squares method) into the antenna-based complex
   bandpass function, or b) by using the autocorrelation data as the
   amplitude part of the function and setting the phase of the function
   to zero.  The default is to divide the data by the so-called 'channel
   0' before determining the bandpasses, this removes the requirement of
   calibrating the data first and any division by a model.  Data from
   the VLBA correlator undergo another operation within BPASS.  The
   correlator uses a geocentric reference frame and so all data are
   lobe-rotated to the centre of the Earth rather than to a reference
   station for a given baseline, this means that the diurnal
   aberration is added to the lobe-rotation resulting in a shift of
   the bandpass away from the RF frequency. This shift varies from
   source to source. BPASS will remove this additional frequency shift
   and store the bandpasses in the traditional manner, as though no
   extra diurnal lobe-rotation was applied.  Model images made with
   both values of IMAGR's DO3DIMAG option are handled correctly, as
   are multi-scale images.  Set NMAPS = NFIELD * NGAUSS.

   Unless you normalize the output bandpass with BPASSPRM(5) and/or
   BPASSPRM(10), it is important that SETJY or GETJY have been used on
   the calibrator source in advance.  This is particularly true if you
   choose to use the spectral index parameters.  Spectral index
   parameters are used for "known" sources including 3C286, 3C48,
   3C147, 3C138, 3C123, 3C196, and 3C295.  They are also fit to the
   fluxes in the SU table for "unknown" sources.  To avoid the use of
   spectral index, set DOSCALE = -1.  Spectral index curvature is fit
   for unknown sources only if DOSCALE = 2 (or more).

   If you use more than one calibration source, then you should use
   BPASSP(5) = 0 if there is any channel-dependent flagging.
   Otherwise, the differences in flux (if not in the SU table) or the
   differences in gain will cause channel-dependent problems with the
   resulting bandpass.
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.
  CALSOUR....List of sources for which bandpass response functions are
             to be determined.  All ' ' = all sources; a "-" before a
             source name means all except ANY source named. If the data
             file is a single-source file no source name need be
             specified.  If both IN2NAME and IN2CLASS are specified,
             but multiple sources are selected, BPASS will quit.
  QUAL.......Only sources 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.
  UVRANGE....Range (min, max) of projected baselines to include
             0,0 => all baselines (units: klamda)
  TIMERANG...Time range of the data to be selected. In order: Start day,
             hour, min. sec, end day, hour, min. sec. Days relative to
             reference date.
  SELBAND....Bandwidth of data to be selected. If more than one IF is
             present SELBAND is the width of the first IF required.
             Units = kHz, 0=> all
  SELFREQ....Frequency of data to be selected. If more than one IF is
             present SELFREQ is the frequency of the first IF required.
             Units = MHz, 0=> all
  FREQID.....Frequency identifier to select (you may determine which is
             applicable from the OPTYPE='SCAN' listing produced by
             LISTR). If either SELBAND or SELFREQ are set their values
             override that of FREQID.  However, setting SELBAND and
             SELFREQ may result in an ambiguity, in which case the task
             will request that you use FREQID.
  SUBARRAY...Subarray number to select. 0=>all.
  ANTENNAS...A list of the antennas for which bandpasses are to be
             determined.  If any number is negative then all antennas
             listed are NOT to be used and all others are.
The following specify a CLEAN model to be used if a single source was
specified in SOURCES and if there is no immediate division by channel
0 (i.e. BPASSPRM(5) < -1.5 or > 0.5 => no channel 0):
  IN2NAME....Cleaned map name (name).      ' ' => no Clean model
             Note: a CLEAN image for only a single source may be given
             although the uv data may be in a multi-source file.
             If the source table contains a flux, then that flux will
             be used to scale the components model to obtain the
             stated total flux.  This is needed since initial Cleans
             may not obtain the full flux even though they represent
             all the essentials of the source structure.
  IN2CLASS...Cleaned map name (class).     ' ' => no Clean model
             If a Clean model is specified, then only one source may
             be selected (multi-source files) and no SMODEL may be
             specified (single-source files).
  IN2SEQ.....Cleaned map name (seq. #).    0 -> highest.
  IN2DISK....Disk drive # of cleaned map.  0 => any.
  INVERS.....CC file version #.  0=> highest numbered version
  NCOMP......Number of Clean components to use for the model, one
             value per field.  If all values are zero, then all
             components in all fields are used.  If any value is not
             zero, then abs(NCOMP(i)) (or fewer depending on FLUX and
             negativity) components are used for field i, even if
             NCOMP(i) is zero.  If any of the NCOMP is less than 0,
             then components are only used in each field i up to
             abs(NCOMP(i)), FLUX, or the first negative whichever
             comes first.  If abs(NCOMP(i)) is greater than the number
             of components in field i, the actual number is used.  For
             example
                   NCOMP = -1,0
             says to use one component from field one unless it is
             negative or < FLUX and no components from any other
             field.  This would usually not be desirable.
                   NCOMP = -1000000
             says to use all components from each field up to the
             first negative in that field.
                   NCOMP = -200 100 23 0 300 5
             says to use no more than 200 components from field 1, 100
             from field 2, 23 from field 3, 300 from field 5, 5 from
             field 6 and none from any other field.  Fewer are used if
             a negative is encountered or the components go below
             FLUX.
  FLUX.......Only components > FLUX in absolute value are used in the
             model.
  NMAPS......Number of image files to use for model.  For multi-scale
             models, set NMAPS = NFIELD * NGAUSS to include the Clean
             components of the extended resolutions.  If more than one
             file is to be used, the NAME, CLASS, DISK and SEQ of the
             subsequent image files will be the same as the first file
             except that the LAST 3 or 4 characters of the CLASS will
             be an increasing sequence above that in IN2CLASS.  Thus,
             if INCLASS='ICL005', classes 'ICL005' through 'ICLnnn'
             or 'ICnnnn', where nnn = 5 + NMAPS - 1 will be used.  Old
             names (in which the 4'th character is not a number) are
             also supported: the last two characters are '01' through
             'E7' for fields 2 through 512.  In old names, the highest
             field number allowed is 512; in new names it is 4096.
  CMETHOD....This determines the method used to compute the
             model visibility values.
             'DFT' uses the direct Fourier transform, this
             method is the most accurate.
             'GRID' does a gridded-FFT interpolation model
             computation.
             '    ' allows the program to use the fastest
             method.
             NOTE: when using a model derived from data with
             different uv sampling it is best to use 'DFT'
  CMODEL.....This indicates the type of input model; 'COMP' means that
             the input model consists of Clean components, 'IMAG'
             indicates that the input model consists of images.
             'SUBI' means that the model consists of a sub-image of
             the original IMAGR output.  If CMODEL is '   ' Clean
             components will be used if present and the image if not.
             SUBI should work for sub-images made with DO3DIM true and
             sib-images of the central facet made with DO3DIM false,
             but probably will not work well for shifted facets with
             DO3DIM false.  Use BLANK rather than SUBIM in such cases.
             CALIB will set a scaling factor to correct image units
             from JY/BEAM to JY/PIXEL for image models.  If the source
             table contains a flux, then that flux will be used to
             scale the components model to obtain the stated total
             flux.  This is needed since initial Cleans may not obtain
             the full flux even though they represent all the
             essentials of the source structure.
  SMODEL.....For single-source files only: a single component model to
             be used instead of a CLEAN components model; if SMODEL(1)
             > 0 then use of this model is requested.  Note that
             IN2NAME or IN2CLASS must be blank if SMODEL(1) > 0 and
             both must be specified if SMODEL(1) <= 0 for
             single-source files.
                SMODEL(1) = flux density (Jy)
                SMODEL(2) = X offset in sky (arcsec)
                SMODEL(3) = Y offset in sky (arcsec)
                SMODEL(4) = Model type:
                  0 => point model
                  1 => elliptical Gaussian and
                       SMODEL(5) = major axis size (arcsec)
                       SMODEL(6) = minor axis size (arcsec)
                       SMODEL(7) = P. A. of major axis (degrees)
                  2 => uniform sphere and
                       SMODEL(5) = radius (arcsec)
  DOCALIB....If true (>0), calibrate the data using information in the
             specified Cal (CL) table for multi-source or SN table for
             single-source data.  Also calibrate the weights unless
             DOCALIB > 99 (use this for old non-physical weights).
             The calibration is applied prior to the bandpass
             determination.  This is useful even when dividing by
             channel 0 determined from the same data set since the
             data amplitude enters into the weights used in solving
             for the bandpass.
             ** N.B. This option must be used with care when also using
             ** the IN3NAME (external channel 0 file) option.  AIPS
             ** cannot apply calibration to 2 files at the same time.
             ** Therefore, if you use the IN3NAME option you must set
             ** DOCALIB to the calibration state of the external file
             ** (false if it is uncalibrated, true if it has been
             ** calibrated e.g. by SPLIT).
  GAINUSE....Version number of the CL table to apply to multi-source
             files or the SN table for single-source files.
             0 => highest.
  DOPOL......If > 0 then correct data for instrumental polarization as
             represented in the AN or PD table.  This correction is
             only useful if PCAL has been run or feed polarization
             parameters have been otherwise obtained.  See HELP DOPOL
             for available correction modes: 1 is normal, 2 and 3 are
             for VLBI.  1-3 use a PD table if available; 6, 7, 8 are
             the same but use the AN (continuum solution) even if a PD
             table is present.
  PDVER......PD table to apply if PCAL was run with SPECTRAL true and
             0 < DOPOL < 6.  <= 0 => highest.
  BLVER......Version number of the baseline based calibration
             (BL) table to appply. <0 => apply no BL table,
             0 => highest.
  FLAGVER....Specifies the version of the flagging table to be applied.
             0  => highest numbered table.
             <0 => no flagging to be applied.
  SOLINT.....The interval over which to average the data before solving
             for the bandpasses (MINS).  0 => scan FOR MULTI-SOURCE
             files, whole time range for single-source files.
             < 0 => whole time range and ALL sources.  In this case,
             if there is more than one CALSOUR, no spectral index
             correction will be made.
  SOLTYPE....Solution type:
               '    ' => normal least squares,
               'R   ' => as ' ' with robust iteration
               'L1  ' => L1 solution; a weighted sum of the moduli
                         of the residuals is minimized.
			 The computed gain solutions are less
			 influenced by wild data points, but there
			 is some loss of statistical efficiency.
	      		 See [F.R. Schwab, VLA scientific Memo #136]
			 for further details.
               'L1R ' => as 'L1' with robust iteration
               'GCON' => least squares which may include gain
                   constraint.
               'GCOR' => as 'GCON' with robust iteration
             The robust versions iterate the solution, discarding data
             that does not fit the current solution well enough.  They
             should be less disturbed by bad data, but will be slower.
  REFANT.....The antenna to use as a reference in the least-squares
             solution.  If 0, the task will use the first solution
             interval to select one.  ** It is better if you choose. **
  OUTVERS....The version of the BP table to fill. The default
             (OUTVERS = 0) will cause a new table to be generated.
  SMOOTH.....Specifies the type of spectral smoothing to be applied to
             a uv database . The default is not to apply any smoothing.
             The elements of SMOOTH are as follows:
             SMOOTH(1) = type of smoothing to apply: 0 => no smoothing
               To smooth before applying bandpass calibration
                 1 => Hanning, 2 => Gaussian, 3 => Boxcar, 4 => Sinc
               To smooth after applying bandpass calibration
                 5 => Hanning, 6 => Gaussian, 7 => Boxcar, 8 => Sinc
             SMOOTH(2) = the "diameter" of the function, i.e. width
               between first nulls of Hanning triangle and sinc
               function, FWHM of Gaussian, width of Boxcar. Defaults
               (if < 0.1) are 4, 2, 2 and 3 channels for SMOOTH(1) =
               1 - 4 and 5 - 8, resp.
             SMOOTH(3) = the diameter over which the convolving
               function has value - in channels.  Defaults: 1,3,1,4
               times SMOOTH(2) used when input SMOOTH(3) < net
               SMOOTH(2).
             Note that any use of SMOOTH in BPASS will require that
             the same SMOOTH values be used when accessing any data to
             be calibrated by the BP table produced by BPASS.
  ANTWT......Antenna weights for up to 30 antennas. (0=>1.0)
  WEIGHTIT...If > 0, change the data weights by a function of the
             weights just before doing the solution.  Choices are:
             0 - no change   weighting by 1/sigma**2
             1 - sqrt (wt)   weighting by 1/sigma may be more stable
             2 - (wt)**0.25
             3 - change all weights to 1.0
  MINAMPER...Amplitude closure error regarded as excessive in per cent.
             Summaries of the number of excessive errors by antenna and
             by channel are printed and, if BPASSPRM(2) > 1, up to 1000
             of the individual failures are printed.  0 => do not check
             or report "excessive" closure errors of any sort.  Note
             that amplitude closure errors are accumulated using
             logarithms so that gains of 0.5 and 2.0 are both errors of
             100 percent.
  MINPHSER...Phase closure error regarded as excessive in degrees.
             Summaries of the number of excessive errors by antenna and
             by channel are printed and, if BPASSPRM(2) > 1, up to 1000
             of the individual failures are printed.  0 => do not check
             or report "excessive" closure errors of any sort.
  MINANTEN...Minimum number of antennas to attempt a solution.  0 ->  3
             You can set this to 2 if you dare (which was the old
             setting).
  BPASSPRM...Control information:
             (1) > 0 => fill BP table with autocorrelation data only,
                   setting the phases to 0.
                 < 0 => solve only for phases
                 = 0 => solve for phase and amplitude
             (2) print level: 0 -> no diagnostic information except
                           for a count by antenna of closure errors
                           exceeding MINAMPER and/or MINPHSER (if the
                           adverbs and the count are > 0).
                   > 0  => statistics on closure error by channel (but
                           only those exceeding BPASSPRM(6)  percent or
                           BPASSPRM(7) degrees) and counts of errors
                           exceeding MINAMPER and/or MINPHSER.
                   > 1  => plus explicit closure failures (MINAMPER and
                           MINPHSER above)
                   > 11 => plus antenna solutions for each channel
                   > 13 => plus rms at each iteration
                   > 14 => plus input data and gains
                   RECOMMENDATION: Set MINAMPER and MINPHSER moderately
                   high to make a big deal only about serious
                   excursions, but set BPASSPRM(6 and 7) fairly low
                   since the noise spectrum in the final images seems to
                   mimick the closure error spectrum.  Set BPASSPRM(2) =
                   1 to get a modest amount of output.
             (3) > 0 => do not divide data by a model of the source. The
                   default is that the data will be divided by a source
                   model.  The model used will be (in order of
                   decreasing priority):
                       (a)  the flux density specified in the SU table
                       (b)  a point source model (SMODEL)
                       (c)  CLEAN components,
                   If BPASSPRM(5) <= 0, the data will not be divided by
                   a source model.  For multiple calibration sources,
                   methods b and c do not work and method a depends on
                   the amplitude gains being constant or already
                   calibrated.
             (4) > 0 => store only the phase of the complex bandpass
                   function in the BP table. You may want to do this if,
                   for instance, your data have been normalized by the
                   autocorrelation data as is possible with the VLBA.
                   Note though BPASSPRM(10) and task ACSCL which may
                   be used to correct any slippage in amplitude
                   scaling of autocorrelaton data.
                 < 0 => store only amplitudes of the complex bandpass
                   function in the BP table.  May be needed to correct
                   aliasing at the VLA.
                 In both cases, the solution type is controlled by
                 APARM(1) and is A&P by default.  This just sets the
                 amplitude to 1 or the phase to 0 afterwards.
             (5) Divide by channel 0 option. *** CHANGED MAY 2010 ***
                   In general, use 0 when using multiple calibration
                   sources.

                   If 0 (-0.5 to 0.5) the value of "channel 0" is
                   determined and applied (divided into the data) on a
                   record-by-record basis, either from the average of
                   channels specified by ICHANSEL or from an external
                   file (if IN3NAME and IN3CLASS are specified).  If
                   -1 (-1.5 to -0.5), the same is done but the
                   amplitude of channel 0 is made 1.0 so a phase-only
                   correction is made.  Note that model division is
                   turned off if either of these options is selected.

                   If -2 (< -1.5), divide by the average of channels
                   specified by ICHANSEL (no external file) after the
                   time averaging.  This option allows a normalized
                   bandpass to be found correcting for any
                   uncalibrated variations in the continuum.  If you
                   have poor phase stability use 0 or -1, if you have
                   decent phase stability use -2.

                   If you have good phase stablility use +1.  Note
                   that division by channel 0 adds biased noise
                   because the channel-averaged amplitude is by its
                   very nature biased;  the -2 option should be less
                   biased since the data have been vector averaged in
                   time first and so are less noisy. The -1 (phase
                   only) division should avoid the amplitude bias but
                   then the banddpasses are not normalized.  That can
                   be corrected later with BPASSPRM(10) options.

                   If > 0.5, do no normalization before determining the
                   solutions.  This requires good stability during
                   each integration period.  BPASSP(10)=3 still allows
                   a normalized solution which may be even less biased
                   since it is on an antenna rather than a baseline
                   basis.

                   Note also that a channel 0 may not be determined
                   sensibly if the phase changes a lot across the pass
                   band except by setting ICHANSEL to select a very few
                   channels.

                   ********  Note, if normalization is not done on a
                   record-by-record basis, users must be very careful
                   about averaging different calibration sources.  Any
                   channel-dependent flagging will cause the different
                   sources to be differently weighted in the partly
                   flagged channels than in the completely unflagged
                   ones.  The shape of the bandpass in this case will
                   not be correct.  Therefore, if channel-dependent
                   flagging is done and multiple calibrators averaged,
                   the normalization must be done on a record basis.
             (6) > 0 => if the average amplitude closure error in a
                   channel exceeds BPASSPRM(6) per cent in a scan, a
                   message will be generated if  BPASSPRM(2) > 0.  Thus,
                   if BPASSPRM(6) = 2, corrected relative calibrator
                   data averaging outside the range 0.98 - 1.02 in a
                   channel/scan will be printed.
             (7) > 0 => if the average phase closure errors in a channel
                   and scan exceed BPASSPRM(7) degrees, they will be
                   printed if BPASSPRM(2) > 0.
             (8) > 0 => the amplitudes will be scalar averaged before
                   determining the solutions.
             (9) > 0 => the task will attempt to interpolate over
                   flagged channels in the antenna bandpass spectra. It
                   will inform the user if it does this. If this is
                   necessary you should examine your data carefully, it
                   is usually indicative of a problem of some sort.
                   The interpolation is done atutomatically with the
                   VLBA since flagged channels would destroy the
                   necessary shifting algorithm.  For the VLBA, this
                   may be left 0.
            (10) The BPASS solution may be used to apply changes to
                 the average visibility amplitude and phase.  If this
                 is not intended, then it is essential to normalize
                 the solutions in some way, by dividing by channel 0
                 (BPASSPRM(5)) and/or normalizing after the solution
                 is determined.  The bandpass amplitudes are
                 normalized to average 1.0 on a per IF per antenna
                 basis.  Note that modes 1 and 2 below may shift the
                 average visibility phase although the average
                 vsisbility amplitude will remain unchanged.
                 = 1 => normalize the amplitude portion of the bandpass
                   function for each IF and antenna by the area under
                   the curve using all spectral channels. This is
                   useful for VLBI data where amplitudes are scaled by
                   the full bandwidth and a useful 'channel 0' is
                   sometimes difficult to obtain.
                 = 2 => do the same but using only the channels in
                   ICHANSEL.
                 = 3 => normalize bandpass amplitudes and shift the
                   average bandpass phase to zero for each IF and
                   antenna using the channels specified in ICHANSEL.
                 = 4 => normalize bandpass amplitudes and shift the
                   average bandpass phase to zero in each IF and
                   antenna using all channels.  This is for VLBI and
                   allows ICHANSEL to be used solely for selecting
                   "channel 0".
                 = 5 => normalize bandpass amplitudes and shift the
                   average bandpass phase to zero for each IF and
                   antenna using the channels specified in ICHANSEL.
                   Use the square of the BP function (power) rather
                   than the function itself (voltage).
                 = 6 => normalize bandpass amplitudes and shift the
                   average bandpass phase to zero for each IF and
                   antenna using all channels.  This is for VLBI and
                   allows ICHANSEL to be used solely for selecting
                   "channel 0".  Use the square of the BP function
                   (power) rather than the function itself (voltage).
            ****** NOTE: VLBI data may have the normalization checked
                   and adjusted slightly by the task ACSCL new in
                   31DEC14.  This is a version of ACCOR to make sure
                   autocorrleations average 1.0 over channels of
                   interest after bandpass calibration (and before
                   APCAL).
                 = 7 => normalize bandpass amplitudes and shift the
                   bandpass phase to zero using medians rather than
                   means for each IF and antenna using the channels
                   specified in ICHANSEL.
                 = 8 => normalize bandpass amplitudes and shift the
                   bandpass phase to zero using medians rather than
                   means in each IF and antenna using all channels.
                   This is for VLBI and allows ICHANSEL to be used
                   solely for selecting "channel 0".
                 = 9 => normalize bandpass amplitudes only using
                   medians rather than means for each IF and antenna
                   using the channels specified in ICHANSEL.
                 = 10 => normalize bandpass amplitudes only using
                   medians rather than means in each IF and antenna
                   using all channels.  This is for VLBI and allows
                   ICHANSEL to be used solely for selecting "channel
                   0".
            (11) > 0 => make weights given to the solution be
                   independent of channel.  They will depend on IF,
                   baseline, and polarizations in any case.  This option
                   saves on dynamic memory.
                 = -1 => use weights scaled by amplitude**2 (Probably
                         not needed - weights are adjusted for
                         division by channel zero in any case)
                 < -1.5 => use weights scaled by 1/amplitude**2
                 Note that the weights actually used in the solution
                 are further adjusted by WEIGHTIT.
  ICHANSEL.. Array of start, stop, and increment channel numbers plus
             an IF used for channel selection in the averaging to
             compute a channel 0.  Up to 20 sets if channels/IF may be
             entered.  The first having ICHANSEL(2,i) <= 0 terminates
             the list.  ICHANSEL(4,i) is the IF number, with <= 0
             meaning all IFs.  If an IF has no ICHANSEL set for it,
             then the inner 75 percent of that IF is used.  Note that these
             are absolute channel numbers; they are not relative to
             BCHAN.
             For instance, if you wished to exclude channels 1 - 10
             and 121 - 128 because of bandpass effects, and channels
             56 - 80 of IF 1 but not IF 2 because of interference,
             then you would set ICHANSEL = 11,55,1,1, 81,121,1,1,
             11,121,1,2.  If you only wished to use every other
             channel from the second IF then you would set ICHANSEL =
             11,55,1,1, 81,121,1,1, 11,121,2,2.  if there are actually
             4 IFs, then IFs 3 and 4 would use channels 17 through
             112.  To set the channel range for all IFs to 14, 115
             enter ICHANSEL = 14,125.  To set the channel range for
             all IFs to 14-115 except IF 3 set ICHANSEL=14,115,1,0,
             23 45,1,3, 64,101,1,3 where the all IF part must come
             before the parts that partially override it.
  DOSCALE....Controls whether spectral index corrections are made.
             NOTE: spectral index corrections are applied within each
             IF (spectral window), but not between IFs.  Any
             correction between IFs comes either from the fluxes in
             the Source table or from the normalization options.
             DOSCALE < 0 => do no spectral index correction.
             DOSCALE >= 0 => do spectral index correction, using
                SPECINDX and SPECURVE for the first calibrator or
                using known parameters, or fitting fluxes in the SU
                table.
             DOSCALE >= 2 => fit spectral index and curvature for
                unknown sources.  Do this only for well-determined
                fluxes over a wide frequency range.
  SPECINDX...The fit bandpasses are corrected for calibrator spectral
             index including curvature under control of DOSCALE..  The
             calibrator flux is assumed to be proportional to
             frequency^SPECINDX so the bandpass is multiplied by
             (freq/f0) ** SPECINDX when SPECINDX is not zero.
             If SPECINDX = 0 and the calibrator source is one of
             3C286, 3C48, 3C147, 3C138, 3C123, 3C196, or 3C295 (the
             standard "known" ones) SPECINDX and SPECURVE will be set
             to the known (Perley 20xx) values from SETJY.
             If SPECINDX=0 and the source is not one of the known
             ones, then a spectral index (with curvature if DOSCALE=2)
             is fit to the fluxes in the source table.  If there is
             more than one calibration source, SPECINDX and SPECURVE
             are used for the first source and 0.0 for the others
             (i.e. they are fit or taken from the knowns).
  SPECURVE...If SPECINDX is not zero a curvature term may be added to
             the above correction as
                 A = log(f/f0) * SPECINDX + log(f/f0)^2 * SPECURVE(1)
                   + log(f/f0)^3 * SPECURV(2) + log(f/f0)^3 * SPECURV(2)
             and then multiply by 10^(-A/2.) where the 2 is because
             the BP tables are voltages rather than powers.  f0 is
             taken to be 1.0 GHz by convention and all logs are base
             10.0.

The following specify a uv-file which can be used as an external
'channel 0'. If all the IN3* adverbs are blank, then the task will
determine channel 0 from the line data itself, unless BPASSPRM(5) = 1,
in which case no channel 0 division will be done.  Note that this option
is used unless IN3NAME and IN3CLASS are both = ' '.
  IN3NAME....Channel 0 uv name (name).      Standard defaults.
  IN3CLASS...Channel 0 uv name (class).     Standard defaults.
  IN3SEQ.....Channel 0 uv name (seq. #).    0 -> highest.
  IN3DISK....Disk drive # of Channel 0 uv   0 => any.
             ** N.B. This option must be used with care when also using
             ** the IN3NAME (external channel 0 file) option.  AIPS
             ** cannot apply calibration to 2 files at the same time.
             ** Therefore, if you use the IN3NAME option you must set
             ** DOCALIB to the calibration state of the external file
             ** (false if it is uncalibrated, true if it has been
             ** calibrated e.g. by SPLIT).
  BADDISK....A list of disks on which scratch files are not to
             be placed.  This will not affect the output file.

EXPLAIN SECTION

BPASS:  Task to determine antenna bandpass functions from calibrator
        data
Documentor:  P.J.Diamond
Related Programs: CALIB, POSSM, LISTR, SPLIT, TVFLG

This task is the AIPS routine for generating the bandpass correction
file which can be applied to spectral line format data. The program has
two modes of operation:
 (1) It is able to generate a full complex bandpass response function
     for each antenna by decomposing the baseline-based functions (i.e.
     the cross-power spectra) into antenna-based complex functions using
     a least-squares method analagous to self-calibration.
 (2) It can can generate the real (amplitude only) part of the bandpass
     response function using autocorrelation data, if available. In this
     mode it sets the phase of the bandpass function to zero.

The calibration sources that are used to generate the bandpass
response functions need not be point sources. The generality
of the routine is such that if the user has determined the
structure of the calibrator source the visibility data can be
divided by the source model prior to the bandpass determination.
In addition if the bandpass calibrator is strong enough to be
detected at all times on all baselines (typical VLA case) then
the spectral line data may be divided by the so-called 'channel
0' before the bandpasses are determined, this is the default
mode of operation.

The bandpass solutions determined by BPASS are written to the
BP table extension of the input uv data set. They can then be
applied in a variety of ways to the data through the use of the
adverb DOBAND.

To run BPASS you should specify at least:
  (1) the input uv data set (INNAME, INCLASS, INSEQ, INDISK)
  (2) the sources you wish to use in order to determine the
      bandpass shapes (SOURCES)
  (3) any data selection parameters:
      UVRANGE   -> a range (min,max) of projected baselines to
                   include, the default is all data
                   (units: klambda)
      TIMERANG  -> a time range of data to select, default = all
      BIF, EIF  -> the IF numbers to determine bandpasses for,
                   default = all.
      ANTENNAS  -> the antennas to determine the bandpasses for,
                   default = all.

"CLEAN" component models:
BPASS does not restrict you to the use of point source models for your
calibrators.  Use IN2DISK, IN2NAME, IN2SEQ, INVERS, NCOMP and NMAPS to
specify a CLEAN component model for the field or fields around a
calibrator  and specify that calibrator in SOURCE.

Normalization:
In most cases you will want to normalize the bandpass, particularly if
your data is VLBI where the amplitude scale is based on system temperatures.
This can be done in one of two ways, either divide by "channel 0" (BPASSPRM(5))
or normalize the amplitudes and, possibly, shift the phases (BPASSPRM(10).
Channel 0 can be defined in two ways, either by averaging all or some portion
of the channels for the bandpass calibrator or useing an external channel 0.
If there is poor phase stability over the bandpass calibrator scan(s) then
BPASSPRM(5)=0 should be used, even though it will add some noise, since it
does the channel 0 on a record by record bases before averaging in time.
Otherwise BPASSPRM(5)=-1 is recommended.  For VLBI it may be necessary to
use BPASSPRM(10) which does not produce a complex channel 0 but normalizes
the amplitudes and can also shift the phases to zero.  NOTE THAT BPASSPRM(10)
(AND BPASSPRM(5)=-1) SHOULD ONLY BE USED IF THE PHASES FOR THE BANDPASS
CALIBRATOR ARE STABLE ACROSS THE ENTIRE SCAN(S).  When the bandpass is
applied the bandpass is averaged (by default) over all time, if the phases
are not stable then the normalization will be go haywire.

The control parameters:
The program is controlled by a series of adverbs , the default setting
of which should give the user sensible results. The adverbs and their
effect on the data are described below.

DOCALIB:
If DOCALIB is set to 1 then BPASS will calibrate the data selected
before attempting to determine any bandpass response functions.  The
default (DOCALIB = 0) is no calibration.  If you have a useful CL table,
it should be applied.  The amplitude of channel 0 scales the weights
of the ratios used in the bandpass solutions.  If one antenna has a
significantly different gain than another, leaving out the gain
correction will significantly alter the relative weights.  Applying
delay and rate corrections in VLBI data sets is also important prior to
determining channel 0.
N.B. This option must be used with care when also using the IN3NAME
(external channel 0 file) option.  AIPS cannot apply calibration to 2
files at the same time.  Therefore, if you use the IN3NAME option you
must set DOCALIB to the calibration state of the external file (false if
it is uncalibrated, true if it has been calibrated e.g. by SPLIT).

GAINUSE:
GAINUSE specifies the version of the CL table to be applied in the
calibration. If GAINUSE = 0 then the highest numbered version will be
used.

FLAGVER:
If FLAGVER is .ge. 0 then if a flagging (FG) table is present the data
will be flagged before any other operation.  The default (FLAGVER = 0)
is to use the highest numbered version.

SOLINT:
SOLINT defines the time interval over which to average the uv-data
before solving for the bandpasses.  The default (SOLINT = 0) is the
whole scan defined by the NX table.  SOLINT = -1 will average all data
selected before determing the bandpass functions.

REFANT:
REFANT defines the antenna to be used as the reference in the least
sqaures solution. Try to choose an antenna with good signal to noise and
that was present for as long as possible through the observing run. The
default (REFANT = 0) causes the program to choose a reference antenna
itself, it tries to do this sensibly.

OUTVERS:
The version of the BP table to fill.  The default (OUTVERS = 0) will
cause a new table to be generated.

SMOOTH:
Specifies the type of spectral smoothing that can be applied
to the data before the bandpasses are determined. See
HELP SMOOTH for more details.

** WARNING ** If SMOOTH is specified then all channels of
the database must be present in a single file, it will not
work properly if for instance you have split your data into
4 files each of 16 channels. The rest of BPASS will work
with no problem in that mode but the SMOOTH option will
result in corrupted data.

ANTWT:
Each antenna can be assigned a weight which only affects its
weighting in the least-squares solution. So if you have an
antenna which is noisy you can set its weight to 0.1 and all
the others to 1 and it will have a very small effect on the
bandpass determination.

BPASSPRM:
The BPASSPRM parameters control various options within the
program.  See the help section too for details:
  BPASSPRM(1): if > 0 then only the autocorrelation data are used to
            determine the bandpasses, the phases of the bandpass
            functions are then not determined and are set to zero.
            This is sometimes useful for VLBI, especially prior to
            corrections for fring rates and delays.
  BPASSPRM(2): print level, the higher it is set the more tedious crap
            will be printed on your terminal.  Level 1 is useful for
            statistical reports on closure errors exceeding
            BPASSPRM(6) ( percent) and BPASSPRM(7) (degrees).  Level 2 gets
            explicit closure failures > MINAMPER and/or MINPHSERR.
            Levels 11, 13, 14 are for debugging.
  BPASSPRM(3): if > 0 do not divide the data by a source model.  If
            BPASSPRM(5) > 0, then the point source model (if SMODEL >
            0), the point source model (SU table flux), or a Clean
            image (Celan components) model will be used.
  BPASSPRM(4): if > 0 store the phases only in the BP table.
  BPASSPRM(5): if = 0 then calculate channel 0 by vector averaging
            channels ICHANSEL (default = centre 75 percent of the observing
            band) and divide the line data by the result on a record
            by record basis.  This compensates for continuum shifts in
            phase and amplitude over the averaging period (which can
            average the data to nearly zero) at the cost of adding
            some noise.  If you have very good phase stability, set
            BPASSPRM(5)=-1 to do the channel zero division on the
            averaged data (over SOLINT) rather than on the individual
            records.  This adds less noise.
            Warning: if channel-dependent flagging has been done and
            multiple sources are being averaged, then record-by-record
            division by channel zero must be done.
            Further warning: if the phase changes a lot across the
            band (i.e due to uncalibrated delay errors), then channel
            zero may be used only if ICHANSEL selects only a very few
            channels.
  BPASSPRM(6): amplitude closure allowed level before triggering the
            displays selected by BPASSPRM(2) > 0 in per cent.
  BPASSPRM(7): phase closure allowed level before triggering the
            displays selected by BPASSPRM(2) > 0 in degrees.
  BPASSPRM(8): > 0 => use scalar averaging for the amplitude in
            determining the gain solutions in each SOLINT.
  BPASSPRM(9): > 0 => use interpolation to determine solutions for
            failed (e.g. all flagged) channels.
  BPASSPRM(10): > 0 => normalize the output, antenna solutions.
             =1  normalize amplitude over all channels.
             =2  normalize amplitude using channels in ICHANSEL to
                 determine normalization.
             =3  normalize amplitude and phase using channels in
                 ICHANSEL to determine normalization.  For VLBI, set
                 ICHANS = 1,Nchan where Nchan is the total number of
                 channels.
             Note that VLBI is normalized over the full bandwidth
             (using Tsys measurements) while the VLA traditionally
             uses the center 75 percent only (using "channel 0" data sets).

AIPS