AIPS HELP file for BPASS in 31DEC24
As of Thu Apr 25 13:08:21 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
DOBAND -1.0 10.0 If >0 apply bandpass cal.
Method used depends on value
of DOBAND (see HELP file).
BPVER Bandpass 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.
DOBAND.....If true (>0) then correct the data for the shape of the
antenna bandpasses using the BP table specified by BPVER.
The correction has five modes:
(a) if DOBAND=1 all entries for an antenna in the table
are averaged together before correcting the data.
(b) if DOBAND=2 the entry nearest in time (including
solution weights) is used to correct the data.
(c) if DOBAND=3 the table entries are interpolated in
time (using solution weights) and the data are then
corrected.
(d) if DOBAND=4 the entry nearest in time (ignoring
solution weights) is used to correct the data.
(e) if DOBAND=5 the table entries are interpolated in
time (ignoring solution weights) and the data are then
corrected.
BPVER......Specifies the version of the BP table to be applied.
<0 => no bandpass correction done.
** NOTE - AIPS does not now have a way to "concatanate"
** BP tables. Thus, if one determines a BP table having
** applied a BP table, one has no way to get that net
** calibration applied to the data. Nonetheless, it may
** be of interest, for example, to use DOBAND=1 for
** example and then to see what is left as a
** time-variable BP, examining it with BPLOT.
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).