As of Mon Jul 15 11:36:40 2024

EVAUV: does statistics on comparison of model and uv data


INNAME                             Input UV file name (name)
INCLASS                            Input UV file name (class)
INSEQ             0.0     9999.0   Input UV file name (seq. #)
INDISK                             Input UV file disk unit #
SRCNAME                            Source name
QUAL            -10.0              Calibrator qualifier -1=>all
CALCODE                            Calibrator code '    '=>all
STOKES                             Stokes of output ' ' -> HALF
TIMERANG                           Time range to use
SELBAND                            Bandwidth to select (kHz)
SELFREQ                            Frequency to select (MHz)
FREQID                             Freq. ID to select.
ANTENNAS                           Antennas to copy 0=>all
BASELINE                           Baselines with ANTENNAS
SUBARRAY          0.0     1000.0   Sub-array, 0=>all
BIF                                Low IF number to do
EIF                                Highest IF number to do
BCHAN             0.0              First channel included
ECHAN             0.0              last channel included
DOCALIB          -1.0      101.0   > 0 calibrate data & weights
                                   > 99 do NOT calibrate weights
GAINUSE                            CL (or SN) table to apply
DOPOL            -1.0       10.0   If >0.5 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.5 apply bandpass cal.
                                   Method used depends on value
                                   of DOBAND (see HELP file).
BPVER                              Bandpass table version
SMOOTH                             Smoothing function. See
                                   HELP SMOOTH for details.
NMAPS             0.0     4096.0   No. maps to use for model.
NGAUSS            0.0              Number Gaussians in NMAPS
IN2NAME                            Cleaned map name (name)
IN2CLASS                           Cleaned map name (class)
IN2SEQ            0.0     9999.0   Cleaned map name (seq. #)
IN2DISK                            Cleaned map disk unit #
INVERS           -1.0    46655.0   CC file version #.
BCOMP                              First CLEAN comp to sub.
                                   1 per field.
NCOMP                              Last CLEAN comp to sub.
                                   to use (0 => all)
FLUX                               Lowest CC component used.
CMETHOD                            Modeling method:
                                   'DFT','GRID','    '
SMODEL                             Source model, 1=flux,2=x,3=y
                                   See HELP SMODEL for models.
                                   (1) not 0 -> ignore IN2NAME
                                   < 0 => solve for flux from
                                   SU table (-2 curvature)
SPECINDX                           If SMODEL, spectral index
SPECURVE                           If SMODEL, spectra curvature
DOOUTPUT         -1.0        1.0   > 0 save the UV files from
                                   model subtraction & division
OUTNAME                            Output files name
OUTSEQ                             Output files sequence
OUTDISK                            Output files disk
SOLINT                             Closure averaging (min)
                                   0 => do not do closure
DOPLOT                             > 0 => plot Re vs Im maps
                                   = 2 => plot histograms too
CELLSIZE                           Cell size in asec (if SMODEL)
APARM                              2-D Re/Im plot controls
                                   (1) Plot subtracted data
                                       over +/-APARM(1)*RMS(sub)
                                   (2) Plot divided data over
                                       +/- APARM(2)*RMS(div)
                                   (3) Number pixels on a side
                                       for these images
                                   (4) Gaussian smoothing size
PIXRANGE                           Intensity range to use
FUNCTYPE                           'LG' use logarithms in plot
                                   of image intensities
LTYPE                              type of labeling
DOTV                               > 0 use TV, else plot file
GRCHAN                             TV graphics channel to use
BADDISK                            Disks to avoid for scratch
         @     Output adverbs
RPARM    @                         Results (see help)


Task:  Subtracts and divides a model into a uv data base.  The model
       may be a specific model, a set of CLEAN components files, or a
       set of images.  "CLEAN" models may be points, Gaussians or
       uniform, optically thin spheres.  The task will compute the
       model and then both subtract it from the input UV data and
       divide it into the UV data.  It then reports on statistical
       attributes of the two data sets.  The mean and rms of the real
       and imaginary parts and the amplitude are reported for the
       model subtracted data set and for the divided data set (after a
       constant 1.0 is subtracted from the real part).  The amplitude
       mean is computed in a robust fashion and controls which samples
       enter into the real and imaginary part averages.  Then the
       number of samples more than 3 rms away from the mean amplitude,
       the total number of samples, and the average of the absolute
       difference of the bad samples and the mean are reported.

       The model will use Clean Components if they are present and
       otherwise will do the image.  No correction for convolution by
       the Clean Beam (if any) are made in the latter case.  Offset
       sub-images are not supported.

       Following the UV analysis, the robust mean and rms over the
       images are determined and reported.  Note that this mean and
       rms should omit any real source signals.

            Model images made with both values of IMAGR's DO3DIMAG
       option are handled correctly, as are multi-scale images.  Set
            EVAUV works only on single-source files.

       Sample output:
   Image mean -7.3490E-07  rms 1.5078E-04
   method    real part          imaginary part     amplitude
   subtract  0.0002 +-  0.157   0.0002 +-  0.157   0.1977 +-  0.103
   divide-1 -0.0040 +-  6.770   0.0017 +-  6.770   7.9390 +-  5.364
   method   # bad samples  total samples  avg bad amp
   subtract         79124        5333006       0.3918
   divide-1        267058        5333006      27.1805

       The optional plots are
         1. The average and rms of the model subtracted data in bins
            of UV-plane radius.
         2. The average and rms of the model divided - 1.0 data in
            bins of UV-plane radius.
         3. The histogram of image pixels over a pixel value range
            selected by the user or the first of the model images.
         4. The histogram of image pixels over a pixel range of
            plus/minus 5 times the rms of the first of the model
         5. The real vs imaginary visibilities of the model subtracted
            data over a range of APARM(1) times the amplitude rms.
            The plot is a contour in logarithmic intervals of the 2-D
            histogram image controlled by APARM.  Contours are drawn
            at 0.5, 1, 1.5, 2, 2.5, 3, etc in the log of the counts.
         6. The real and imaginary gains minus (1,0) of the model
            divided data over a range of APARM(2) times the amplitude
            rms.  Logarithmic contours also.
         Actually plots 5 and 6 cover somewhat larger areas but some
         data samples will not be plotted (totals on and off the plot
         are reported).

         The task will now compute and report closure phase and
         amplitude statistics from the "visibilties" of the gain
         data set (produced by division of the input data by the
         model, not subtracting (1,0)).  It will do this only when the
         STOKES value is appropriate: HALF, RRLL, RR, LL, VVHH, VV, and
         HH and when SOLINT is not zero..  It will do these as a
         function of IF.  Closure amplitude in the quadrangle of
         antennas a, b, c, and d is defined as
             LN [ (amp_ab * amp_cd) / (amp_ac * amp_bd) ]
         which should be independent of any antenna-based instrumental
         gains.  Closure phase in the triangle of antennas a, b, and c
         is defined as
                  Phase_ab - Phase_ac + Phase_bc
         which should be independent of any antenna-based instrumental
         phases.  Since these apply to the RR and LL, closure amplitude
         and phase are only meaningful in the STOKES values listed
         above.  The data/model data set should ideally be a point
         source at the coordinate origin and so these closure parameters
         should be zero, if the model is perfect.

         Closure information is produced by the following tasks:
         CLPLT   Plots closure phases for individual triangles as a
                 funtion of time.
         CAPLT   Plots closure amplitudes for individual quadrangles as
                 a funtion of time.
         EVACL   Computes the RMS of closure phase and amplitude as a
                 function of IF for an individual Stokes.
         EVAUV   Computes two data sets: data-model and data/model.  The
                 closure RMSes of the latter may be computed as
                 functions of polarization and IF.  Other statistics
                 are computed and plotted.
         CLOSE   Computes the RMS closure phase or amplitude as a
                 function of spectral and IF channel.  A plot is
                 produced and a text file may be written.

  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.
  SRCNAME....Source name to be gridded.  Must specify if input is
             a multi-source data set, otherwise all sources are
  QUAL.......Qualifier of source to be processed. -1 => all.
  CALCODE....Calibrator code of source to be processed. ' '=> all.
  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. For data which contain multiple
             bandwidths/frequencies the task will insist that some form
             of selection be made by frequency or bandwidth.
  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.
  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 that case, the task
             will request that you use FREQID.
  ANTENNAS...A list of the antennas to  list.  If any number is
             negative then all antenna numbers in ANTENNAS are NOT
             desired and all others are.  All 0 => list all.
             Note that antenna numbers that do not appear in the
             relevant antenna file(s) or which appear with a name
             containing the string 'OUT' are not displayed.
  BASELINE...Baselines are specified for the LIST option using
             BASELINE. Eg. baselines 1-6,1-8, 2-6 and 2-8 use
             ANTENNAS=1,2; BASELINE=6,8.
  SUBARRAY...Sub-array number to process. 0=>all (okay if not
  BIF........Start IF; 0 -> 1
  EIF........End IF; 0 -> max
  BCHAN......Start channel; 0 -> 1
  ECHAN......End channel; 0 -> max
  NCHAV......Number of channels to average.  Note that ECHAN is
             adjusted if necessary to make (ECHAN-BCHAN+1) and integer
             multiple of NCHAV.  0 -> 1.
  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 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 apply. <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
             (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
             IMAGR uses DOBAND as the nearest integer; 0.1 is therefore
  BPVER......Specifies the version of the BP table to be applied
                0 => highest numbered table.
               <0 => no bandpass correction to be applied.
  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
  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.
  NGAUSS.....Number of Gaussians in NMAPS.
  IN2NAME....Model map name (name).      Standard defaults.
  IN2CLASS...Model map name (class).     Standard defaults.
  IN2SEQ.....Model map name (seq. #).    0 => highest.
  IN2DISK....Disk drive # of model map.  0 => any.
             WARNING: SMODEL overrides the above model map
  INVERS.....CC file ver. number.          0 => highest.
  BCOMP......The first clean component to process. One value is
             specified for each field used.
  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
  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: data in any sort order may be used by the 'DFT'
             method but only 'XY' sorted data may be used by the
             'GRID' method.
             NOTE: CMETHOD='GRID' does not work correctly for RL
             and LR data; DO NOT USE CMETHOD='GRID' for RL, LR!
  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) at header frequency
                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)
             If SMODEL(1) < 0, EVAUV will try to solve for the
             spectrum using the SU table.  SMODEL(1) < -1.5 means to
             include curvature in the solution.
  SPECINDX...Spectral index to use with SMODEL(1) > 0. Alternatively
             it will be solved using the SU table if SMODEL(1) < 0.
             Not used when SMODEL(1) = 0.
  SPECURVE...Spectral curvature to use with SMODEL when SMODEL(1) > 0.
             log(T(f)/T(f0) = S * log(f/f0) + C(1) * (log(f/f0))^2
                + C(2) * (log(f/f0))^3 + C(3) * (log(f/f0))^4
             where S is SPECINDEX and C is SPECURVE, f0 is the header
             frequency and all logs are base 10.  Will be solved from
             the SU table if SMODEL(1) < -1.5.
  DOOUTPUT...> 0 => save the residual (data minus model) and gain
                   (data divided by model) files as cataloged files.
             <=0 => delete these files at the end of the task.
  OUTNAME....Output files name (name).   ' ' -> INNAME
             The classes will be EVAUVS and EVAUVD for subtracted and
             divided data sets.
  OUTSEQ.....Output files name (seq #).  0 -> next highest
  OUTDISK....Output files disk number.  0  -> highest with space.
  SOLINT.....= 0 => do not do closure phases and amplitudes
             If SOLINT > 0, the time interval (minutes) over which to
             average the data in order to form the closure phase and
             amplitude.  This function works on the gain (data / model)
             which should, with an ideal model, be (1, 0).  Use of a
             very small value of SOLINT  (but > 0) will cause
             inadequately aligned data to be discarded in order to avoid
             misleadingly high closure  phases and amplitudes.  However
             larger SOLINTs appear to go faster.
             If SOLINT < 0, the task will form a closure phase/amplitude
             as soon as it has accumulated at least one sample for each
             of the three/four baselines in the triangle/quadrangle.
             These are then averaged over abs(SOLINT) minutes.
  DOPLOT.....> 0   => Plot the two real versus imaginary histogram
                      images as contour maps with contours in the log
                      at intervals of 0.5, 1, 1.5, 2.0, 2.5 etc
             > 1.5 => Also plot two plots showing the mean and rms
                      residual and (gain-1) versus baseline length
                      and two plots of the image histogram.
             <= 0  => no plots
  CELLSIZE...Cell size of images in arc seconds.  Used when there are
             no model images (i.e. when using SMODEL) to scale
             histograms of data versus radius in UV plane.  Default
             0.1 asec which is not likely to be useful.
  APARM......The real parts of the model subtracted and model divided
             data are plotted against the corresponding imaginary
             parts in two contour plots of the 2-D histogram images.
             The contour intervals are 0.5 in the logarithm of the
             counts in each cell of the images.  APARM controls the
             extent of these images, their size, and whether they are
             (1)....The model subtracted data are plotted over a range
                    of +/- APARM(1) times the subtracted amplitude
                    rms.  0 -> 5
             (2)....The model divided data are plotted over a range
                    of +/- APARM(2) times the divided amplitude rms.
                    0 -> 10
             (3)....The plots are summed in images of APARM(3) pixels
                    on a side.  0 -> SQRT (Nvis * Nchan / 10) <= 1024
             (4)....The images are smoothed by a Gaussian kernel of
                    APARM(4) pixels on a side before plotting.
                    0 -> no smoothing - will be set to an odd number
                    <= 33.
             Hints: For large numbers of samples, you may wish to set
             APARM(1) and APARM(2) to higher numbers, e.g. 15 and 25
             and you will want to smooth by e.g. 5 or 9 before
             plotting.  For a small data set, a small image is a good
  PIXRANGE...The range of image intensities to be used in the
             histogram that is intended to encompass the full
             interesting range of the image(s).  0 => use the range in
             the header of the first image.
  FUNCTYPE...'LG' => use logarithms in the plots of the image
             histograms, else do a linear plot.
  LTYPE.......Labelling type, see HELP LTYPE for details:
              1 = border, 2 = no ticks, 3 or 7 = standard, 4 or 8 =
              relative to ref. pixel, 5 or 9 = relative to subimage
              (BLC, TRC) center, 6 or 10 = pixels.  7-10 all labels
              other than tick numbers and axis type are omitted.
              Less than 0 is the same except that the plot file
              version number and create time are omitted.
              Add n * 100 to alter the metric scaling.
  DOTV.......> 0 => plot on the TV, else make plot files.
  GRCHAN.....If plotting on the TV, use graphics plane GRCHAN.  0 =>
             use more than one graphics plane, separating portions of
             the plot by color.
  BADDISK....The disk numbers to avoid for scratch files.
  RPARM......Output adverb with results
             ( 1, 2) Subtracted real part mean, rms
             ( 3, 4) Subtracted imag part mean, rms
             ( 5, 6) Subtracted ampl part mean, rms
             ( 7, 8) Subtracted fraction bad and average bad
             ( 9,10) Divided - 1 real part mean, rms
             (11,12) Divided - 1 imag part mean, rms
             (13,14) Divided - 1 ampl part mean, rms
             (15,16) Divided - 1 fraction bad and average bad
             (17,20) Image mean, rms of mean, rms, rms of rms
             (21,23) Average phase & amplitude closure pol #1
             (24,25) Average phase & amplitude closure pol #2
             (26) SMODEL(1) actually used (if > 0)
             (27) SPECINDX if SMODEL used
             (28,30) SPECURVE if SMODEL used