; EVAUV
;-----------------------------------------------------------------------
;! Subtracts & divides a model into UV data, does statistics on results
;# TASK UV IMAGING MODELING CALIBRATION
;-----------------------------------------------------------------------
;;  Copyright (C) 2009-2010, 2012, 2014-2015, 2017
;;  Associated Universities, Inc. Washington DC, USA.
;;
;;  This program is free software; you can redistribute it and/or
;;  modify it under the terms of the GNU General Public License as
;;  published by the Free Software Foundation; either version 2 of
;;  the License, or (at your option) any later version.
;;
;;  This program is distributed in the hope that it will be useful,
;;  but WITHOUT ANY WARRANTY; without even the implied warranty of
;;  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;;  GNU General Public License for more details.
;;
;;  You should have received a copy of the GNU General Public
;;  License along with this program; if not, write to the Free
;;  Software Foundation, Inc., 675 Massachusetts Ave, Cambridge,
;;  MA 02139, USA.
;;
;;  Correspondence concerning AIPS should be addressed as follows:
;;         Internet email: aipsmail@nrao.edu.
;;         Postal address: AIPS Project Office
;;                         National Radio Astronomy Observatory
;;                         520 Edgemont Road
;;                         Charlottesville, VA 22903-2475 USA
;-----------------------------------------------------------------------
EVAUV     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
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 #
SOURCES                            Source name
QUAL            -10.0              Calibrator qualifier -1=>all
CALCODE                            Calibrator code '    '=>all
STOKES                             Stokes of output
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
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)
----------------------------------------------------------------
EVAUV
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
       NMAPS = NFIELD * NGAUSS.
            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
            images.
         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).
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.
  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
             specification.
  INVER......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
             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.
  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.
  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
             smoothed:
             (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
             idea.
  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,25) not used yet
             (26) SMODEL(1) actually used (if > 0)
             (27) SPECINDX if SMODEL used
             (28,30) SPECURVE if SMODEL used
----------------------------------------------------------------

