As of Fri Jul 19 9:33:39 2024

BLCHN: Task to compute closure offset corrections per channel


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 #
OUTNAME                            Output UV file name (name)
OUTCLASS                           Output UV file name (class)
OUTSEQ            0.0     9999.0   Output UV file name (seq. #)
OUTDISK           0.0        9.0   Output UV file disk unit #
                                   Data selection (multisource):
SOURCES                            Sources to calibrate with
TIMERANG                           Time range to use.
SELBAND                            Bandwidth to select (kHz)
SELFREQ                            Frequency to select (MHz)
FREQID                             Freq. ID to select.
SUBARRAY          0.0     1000.0   Subarray, 0=>all
                                   Cal. info for input:
FLAGVER                            Flag table version
DOCALIB          -1.0      101.0   > 0 calibrate data & weights
                                   > 99 do NOT calibrate weights
GAINUSE                            CAL table to apply.
                                   CLEAN map (optional)
DOPOL            -1.0       10.0   If >0 correct polarization.
PDVER                              PD table to apply (DOPOL>0)
DOBAND           -1.0       10.0   If >0 apply bandpass cal.
                                   Method used depends on value
                                   of DOBAND (see HELP file).
BPVER                              Bandpass table version
BLVER            -1.0    46655.0   INPUT BL table version
SMOOTH                             Smoothing function. See
                                   HELP SMOOTH for details.
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 flux included
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
                                   BE CAREFUL overrides IN2NAME
ICHANSEL                           Array of start and stop chn
                                   numbers, plus a channel
                                   increment and IF to be used
                                   for channel selection in the
                                   averaging. See HELP ICHANSEL.
                                   Default = full band
DOSCALE          -1.0         2.0  = -1 -> no spectral index
                                   - 0, 1 -> fit spectral index
                                   = 2 -> fit curvature also
SPECINDX                           Spectral index to correct
SPECURVE                           Spectral index curvature
BPARM                              Control info:
                                      1 > 0 => already divided
                                      2 > 0 => print statistics
                                      3-5 > 0 => smooth the
BADDISK                            Disk no. not to use for
                                      scratch files.


Task:  This task reads a UV file, calibrates, divides by a model,
       averages the data over all included times on each baseline, and
       saves the resulting BL information as a function of frequency.
       Known bad channels may have the average over the good channels
       substituted for the suspect average.  The final averages are
       applied to the input file (all sources, no calibration, no
       flagging) on a channel-by-channel basis and written to the
       output file.

       This is an experimental task.  The assumption is that the uv
       data must have a well-determined antenna-based calibration
       before BLCHN is run.  For multi-source input files, the antenna
       based gain solutions must be applied when running BLCHN; these
       solutions and the source models must be such that after the
       calibrated data are divided by the model, all data have
       amplitudes near 1 and phases near 0.  Source models input to
       BLCHN must describe ALL of the flux in the calibrators (including
       any significant confusing flux).   In general, the BL
       correction should be a slow function of channel.  Therefore,
       for improved S/N, you should smooth the input data substantially
       with SMOOTH.  The IF-dependent, channel-independent solutions by
       BLCAL produce a BL table which is understood by the standard
       calibrations and can be time-dependent.  BLCHN on the other hand
       produces a channel-dependent, time-independent solution which
       is written into a BD table and applied to the data to produce a
       new outfile data set.  Task BDAPL may be used thereafter to apply
       the BD solution to a different data set.  Note that that data set
       must have the same number of spectral channels and IFs as the
       input data of BLCHN.
  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.
  OUTNAME....Output UV file name (name).     Standard defaults.
  OUTCLASS...Output UV file name (class).    Standard defaults.
  OUTSEQ.....Output UV file name (seq. #).   0 => highest unique
  OUTDISK....Disk drive # of output UV file. 0 => highest w room

The following are used for multi-source data files only:
  SOURCES....List of sources for which calibration constants
             are to be determined.  '*' = all; a "-" before a
             source name means all except ANY source named.
             Note: solutions for multiple sources can only be
             made if the sources are point sources at their
             assumed phase center and with the flux densities
             given in the source (SU) table. All '  ' =>all.
  TIMERANG...Time range of the data to be used. In order:
             Start day, hour, min. sec,
             end day, hour, min. sec. Days relative to ref.
  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 overide that of FREQID.
             However, setting SELBAND and SELFREQ may result in
             an ambiguity, in which case the task will request
             that you use FREQID.
The following may be used for all data files (except as noted):
  SUBARRAY...Subarray number to use. 0=>all.
  FLAGVER....(multisource) specifies the version of the flagging table
             to be applied. 0 => highest numbered table.  <0 => no
             flagging to be applied.
  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).
  GAINUSE....version number of the CL or SN table to apply to
             the data.  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.
  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
             (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
  BPVER......Specifies the version of the BP table to be applied.
             <0 => no bandpass correction done.
  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
  IN2NAME....Cleaned map name (name).      Standard defaults.
             Note: a CLEAN image for only a single source may be given
             although it may be in a multi-source file.
             For a multi-source file, the flux of the clean components
             selected for the model are summed and scaled to the source
             flux found in the SU table.  If that flux is zero, no
             scaling is done.
  IN2CLASS...Cleaned map name (class).     Standard defaults.
  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
                   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.......Only components > FLUX in absolute value are used in the
  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
             '    ' allows the program to use the fastest
             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.....A single component model to be used instead of a CLEAN
             components model; if abs (SMODEL) > 0 then use of this
             model is requested.
                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 (only model inplemented)
             NOTE: If neither a CLEAN nor a point model is given then
             a point model using the flux densities given in the
             source table is used.
  ICHANSEL...Array of start and stop channels plus a channel increment
             and IF, used to select the channels thought to be
             "good".  Channels not included in ICHANSEL have their
             (suspect) averages replaced by the average over the
             channels included in ICHANSEL.  For instance, if you
             know that channels 1 - 10 and 121 - 128 are dubious
             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.  Channels
             1-10, 56-80, and 121-128 will have their averages
             replaced by the average over channels 11-55 plus 81-120
             in IF 1.  Channels 1-10 abd 121-128 will have their
             averages replace by the average of channels 11-120 in IF
             2.  Up to 20 groups of start, stop and increment channel
             numbers plus IF numbers can be specified. The default
             (ICHANSEL = 0) is to call all channels good.  If ICHANSEL
             describes bad channels explicitly for some IFs, but skips
             other IFs, then all channels are taken as good for the
             skipped IFs.  For example: ICHANSEL=2,6,1,2 => The
             channels 2-6 will be used as good for IF=2 and all
             channels will be taken as good for the rest of the IFs.
             Channels 1 and 7-N will be replaced with the average of
             channels 2-6 in IF 2 only.
  DOSCALE....Controls whether spectral index corrections are made.
             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
             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 baseline corrections are corrected for spectral
             index.  The source flux is assumed to be proportional to
             frequency^SPECINDX so the corrections are 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.
  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
  BPARM......Control information:
  BPARM(1)...If > 0 then the data has already been divided by the model.
             No division by the model will be done.  Note that this
             option will write out the already divided data set
             corrected by the multiplicative correction.  In this case,
             the output BD table and task BDAPL are probably the most
  BPARM(2)...If this value is larger than 0.0, then the correlator
             averages and their RMSs will be printed on the monitor
             terminal and the message file.
  BPARM(3-5)....If > 0, smooth the solution before it is written to the
             BD table and applied to the input data set.  BPARM (3)-(5)
             have the same meaning as SMOOTH (1)-(3) above.
  BADDISK....Disk numbers on which scratch files are not to be placed.


BLCHN:  Task to collect baseline-based (closure) corrections.
DOCUMENTOR: R.C.Walker (modified by W.Cotton & A.Bridle)


     Most modern interferometers are calibrated under the assumption
that the gains needed to calibrate each baseline are simply the
geometric means of the gains of the two antennas involved in the
baseline, i.e. that a single gain can be determined for each antenna
and can then be used to calibrate all baselines to that antenna.  This
assumption can break down at levels involved when large dynamic ranges
are required.  Possible reasons for the breakdown are mis-matched
bandpasses, pointing errors on large sources, offsets in the
correlator, large delay errors, etc.  Errors introduced by such effects
are often called "closure errors" because they invalidate the
assumption that phase and amplitude errors are antenna based and
therefore "close" around some loop of baselines.

     The old VLA often had closure errors between 0.5 and 1 percent
and similar, somewhat smaller, errors are present in the EVLA.
These errors vary in time in ways that are not fully understood, but
they are sufficiently constant that measurements of closure offsets
made within a few hours of observations can be used to improve high
dynamic range maps significantly (see Walker, VLA Scientific Memo
152). If the dynamic range (measured as the ratio of peak to
off-source rms) is less than 10,000, closure offsets are probably not
causing problems.  If the dynamic range is near 10,000:1 and the map
is not noise-limited, closure offsets may be the limiting effect.
Correction of closure offsets may always be needed to obtain dynamic
ranges >10,000:1.  With closure offset corrections, dynamic ranges
>10,000:1 have been achieved (see Lecture 11 in the Course Notes of
the NRAO Summer School on "Synthesis Imaging", held on August 5-9

     Closure offsets are best measured by observing a strong, compact
source.  The observing time and source strength should be such that
the data on each baseline has a SNR of nearly 1000.  The data from the
compact source should be accurately calibrated before running BLCHN;
the data will be divided by the specified model before averaging.  If
multiple compact sources are used for calibration in a given run of
BLCHN, they should be pointlike to high accuracy.

     VLA data provided to BLCHN should have amplitudes within a few
percent of 1.0 and phases within a degree or two of 0 after division
by the model; deviations may be worse for other (especially VLBI)
arrays. The data should be examined carefully using LISTR or PRTUV
before running BLCHN.

     Once a properly calibrated and edited data set is available,
BLCHN can be run to average the selected data from the input data set
and then apply that correction to all of the data in that data set.
This is done to apply a channel-dependent BL solution rather than the
channel independent solution determined by BLCAL.

     BLCHN calculates means and rms's for the baseline corrections and
writes the results in the form of amplitudes and phases in the message
file if requested.

     Division of the data by the model may be done in one of four
ways.  1) External to BLCHN, by e.g. OOSUB, this is indicated by
BPARM(1)=1.  2) Division by a CLEAN model, this is indicated by
filling in IN2NAME etc.  3) Specifying a point model, this is
indicated by the appropriate values in SMODEL.  4) Using a point
source at the phase center with the flux density given in the source
(SU) table.  This method is used when either none of the above methods
are requested or multiple sources are requested.