; SCMAP
;---------------------------------------------------------------
;! Imaging plus self-calibration loop with editing
;# TASK AP IMAGING CALIBRATION EDITING OOP INTERACTIVE
;-----------------------------------------------------------------------
;;  Copyright (C) 1995-2000, 2003-2004, 2006-2007
;;  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
;-----------------------------------------------------------------------
SCMAP     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
SCMAP:  Imaging plus self-calibration
INNAME                             Input UV data (name)
INCLASS                            Input UV data (class)
INSEQ                              Input UV data (seq. #)
INDISK                             Input UV data disk drive #
OUTNAME                            Output image name
OUTSEQ          -1.0     9999.0    Output image seq. no.
OUTDISK                            Output image disk drive #
OUT2NAME                           Output UV file name
OUT2CLAS                           Output UV file class
OUT2SEQ           -1.0      9999.0 Output UV file seq. #
OUT2DISK           0.0         9.0 Output UV file disk drive #
                                       Imaging info
CELLSIZE      1.E-12               (X,Y) size of grid in asec
IMSIZE          0.0      4096.     Image size (power of 2)
SHIFT                              (X,Y) image shift in asec
                                   NOT a "3D" shift.
UVTAPER         0.                 (U,V) Gaussian taper
                                     units are kilo-lambda
UVRANGE         0.                 Min & max baseline (klambda)
UVWTFN                             UV dist. weight function
                                     blank => uniform
UVSIZE          0.                 Array size for doing uniform
                                   weights.  0 -> actual field
                                   size.  ??
ROBUST                             Robustness power: -4 -> pure
                                   uniform weights, 4 => natural
UVBOX           0.        128.     Additional rows and columns
                                   used in weighting.
UVBXFN                             Box function type when UVBOX
                                   > 0.  0 -> 1 round pill box.
ROTATE                             Rotate image CCW from N by
                                   ROTATE degrees
ZEROSP                             0-spacing fluxes and weights
XTYPE           0.         10.     Conv. function type in x
                                     default spheroidal
YTYPE           0.         10.     Conv. function type in y
                                     default spheroidal
XPARM                              Conv. function parms for x
YPARM                              Conv. function parms for y
                                        Cleaning info
GUARD             -1.0         0.9 x,y guard band fractional
                                   radius
NBOXES             0.0        50.0 Number of boxes for CLEAN
CLBOX             -2.0      4096.0 Four coordinates for each box
OBOXFILE *                         Output file for final Clean
                                   boxes
GAIN     *         0.0         2.0 CLEAN loop gain
FLUX     *                         Minimum CLEAN component (Jy)
MINPATCH *         0.0             Min. BEAM half-width in AP.
NITER    *         0.0             Maximum # of CLEAN components
BMAJ     *      -999.9             FWHM(asec) major axis CLEAN
         *                         restoring beam.
BMIN     *      -999.9             FWHM(asec) minor axis CLEAN
         *                         restoring beam.
BPA      *      -360.0       360.0 CLEAN beam position angle
FACTOR   *        -5.0         5.0 Speedup factor see HELP
MAXPIXEL *         0.0    500000.0 Maximum pixels searched in
         *                         each major cycle.
CMETHOD                            Modeling method:
                                   'DFT','GRID','    '
                                        Self cal info
NMAPS    *                         Number of self-cal loops.
SMODEL                             Initial model, 1=flux,2=x,3=y
REFANT   *                         Reference antenna
SOLINT   *                         Solution interval (min)
APARM                              Control parameters
                                      1=min. no. antennas
                                      2 >0 => normalize gain
                                      3 > 0 => avg. RR,LL
                                      5 > 0 => avg. IFs.
                                      6=print level, 1=some
                                      7=soln SNR cutoff (0=>5)
                                      8=SIGMA (see HELP SCMAP)
                                      9=Edit averaging time
                                     10=Amplitude smoothing time
SOLTYPE  *                         Soln type,'  ','L1','GCON',
         *                            'R', 'L1R', 'GCOR'
SOLMODE  *                         Soln. mode: 'A&P','P','P!A',
         *                         'GCON'
SOLCON   *                         Gain constraint factor.
ANTWT    *                         Ant. weights (0=>1.0)
GAINERR  *                         Std. Dev. of antenna gains.
WTUV     *                         Weight outside full weight
                                   range in self-cal
WEIGHTIT *        0.0        3.0   Modify data weights function
DOCALIB          -1.0      101.0   > 0 calibrate data & weights
                                   > 99 do NOT calibrate weights
GAINUSE                            SN table to apply
DOPOL            -1.0       10.0   If >0 correct polarization.
BLVER                              BL table to apply.
FLAGVER                            Flag table version
OUTFGVER          0.0              Output FG 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
SMOOTH                             Smoothing function. See
                                   HELP SMOOTH for details.
DOTV     *       -16.0        16.0 Display residuals on TV ?
                                   0 -> no, 1 -> after each
                                   major cycle and each full
                                   Clean, -1 only after each
                                   full Clean.  If you can, do
                                   at least -1.
DOWEIGHT *        0.0              Rescale weights by DOWEIGHT
                                   for editing display only
DOTWO    *       -1.0       1.0    True => do second observable
                                   plot of main baseline for
                                   display only
BADDISK           -1.0      1000.0 Disks to avoid for scratch.
BPARM                              Subarray weight factors
CPARM                              Subarray ref. ant.
----------------------------------------------------------------
SCMAP
Type:  Task
 Use:  Self calibration loop.
   This task will do multiple iterations of self-calibration and imaging
optionally starting with a one component model (SMODEL).   Each
iteration consists of 1) a visibility based imaging and CLEAN
deconvolution (MX like), 2) determination of the appropriate number of
CLEAN components and self-calibration uvrange, and 3) self-calibration
of the visibility data based on the new model.  A final
imaging/deconvolution is then done on the final uvdata.

   The products of this task are a dirty beam, a CLEAN image and
a calibrated set of uv data.

   Interactive data editing is now available as well.  Both the
calibrated input data and the residual data are displayed.  The former
is used for editing.  This forces the task to run as an interactive
task; the AIPS session that started it is frozen until SCMAP finishes.
If you need to TELL SCMAP something, you must use a second interactive
AIPS session and set NUMTELL to the SCMAP AIPS number.  This nuisance is
one of the reasons why we recommend using at least the TV option at the
self-cal loop point (DOTV = -1).
Adverbs:
  INNAME.....Input UV data file (name).       Standard defaults.
             This should be a single source file with all prior
             calibration and editing done..
  INCLASS....Input UV data file (class).      Standard defaults.
  INSEQ......Input UV data file (seq. #).     0 => highest.
  INDISK.....Input UV data file disk drive #. 0 => any.
  OUTNAME....Output image name.       Standard defaults.
             There will be output ICL001 and IBM001 images.
             The output CLEAN image will be used during
             execution as the residual image.
  OUTSEQ.....Output sequence number.
  OUTDISK....The disk drive # of output images.  0 => highest
             with space (note: map and Beam go on same disk.
  OUTSEQ.....Output sequence number.
  OUT2NAME...Output UV file name (name).   Standard defaults.
             The output uv data file is used as a scratch file
             during execution.
  OUT2CLASS..Output UV file name (class).  Standard defaults.
  OUT2SEQ....Output UV file name (seq. #). 0 => highest unique
  OUT2DISK...Disk drive # of output UV file.  0 => highest
               disk number with space

   The following control imaging:
  CELLSIZE...(X,Y) pixel separation in asec.
  IMSIZE.....(X,Y) The desired size of the CLEAN image; must be
             a power of 2.
  SHIFT......(X,Y) shift of map center from phase center in
             asec.  Map center = Phase center + shift. If X>0
             & Y>0, source shifts to south-west (down & right).
             NOTE: SHIFT(1) and SHIFT(2) are not strictly
             a shift in RA and Dec. The effect of SHIFT(1) on
             the RA of the map center is roughly
             SHIFT(1)/COS(Dec).
             If the UV data have been rotated then SHIFT(1) and
             SHIFT(2) refer to X and Y in the new coordinate
             system.
             THE DO3DIMAG OPTION OF IMAGR IS NOT SUPPORTED BY SCMAP.
  UVTAPER....(U,V) Gaussian taper (kilo-lambda) at 30% level
  UVRANGE....(Minimum,Maximum) baseline (kilo-lambda) in map.
             Note: this value is used only in imaging.  The uv
             range used in self-calibration is set by the task.
  UVWTFN.....Weighting function of (u-v) plane in 2 character
             code.  If the first character is N use "natural"
             weighting (no variation due to local density),
             otherwise use "uniform" weighting (weights are
             modified by local density of samples - first letter
             C - or weights under control of UVSIZE, UVBOX,
             UVBXFN, and ROBUST).  If the second character is
             the letter O, all weights are set to one, and if
             the second letter is V, all weights are set the
             their fourth root, before any use is made of them.
  UVSIZE.....Size of the array used to count samples for uniform
             weighting.  Does not have to be a power of two and
             can be smaller than or bigger than the image size.
             The default is the size of the first output image.
  ROBUST.....Briggs' "robustness" parameter.  "Uniform" weights
             are tempered by a constant being added to the local
             density of weights.  ROBUST = -4 is nearly pure
             uniform weighting, ROBUST = +4 is nearly pure
             natural weighting.  Use of this option requires a
             second array in the "AP" memory and may therefore
             force the data to be sorted.  The option is turned
             off if ROBUST < -7 and uniform weighting is turned
             off is ROBUST > 7.  See HELP ROBUST.
  UVBOX......(U,V) box size for weighting.  This is the support
             radius over which a sample is counted.  I.e., the
             sample or its weight is counted over an area
             2*UVBOX+1 cells on each side in the UV plane, where
             the UV cell size is (after correcting units) given
             by 1 / (UVSIZE(i) * CELLSIZE(i)).
  UVBXFN.....If UVBOX > 0, UVBXFN controls how the samples are
             counted as a function of u and v (UVBXFN < 0) or of
             radius (UVBXFN > 0).  In the latter case, the
             function is 0 for radius > UVBXFN.  Functions are
             pill box, linear, exponential, and Gaussian for
             ABS(UVBXFN) = 1-4, resp.  0 -> 1.  See HELP UVBXFN.
  ROTATE.....Rotation angle to be applied in degrees.
  ZEROSP.....(1)= zero spacing flux density for the
             polarization being processed.  Zero spacing flux is
             placed at the center of image.
             (2)= FWHM size of major axis for Zero spacing flux
             component (in arc seconds).
             (3)= FWHM size of minor axis for Zero spacing flux
             (4)= Position angle (north through east, degrees)
             If (2) is zero, source is assumed bigger than
             image.
             (5)= the weight for zero spacing flux.
  XTYPE......Convolution function type in X-direction
             1=Pill-box, 2=exponential, 3=Sinc, 4=Exp*Sinc,
             5=Spheroidal, 6=exp*BESSJ1(x)/x.
              <= 0 or > 5  -> 5.
  YTYPE.....Convolution function type in Y-direction
  XPARM.....Array containing parameters for XTYPE.
            See HELP UVnTYPE when n=convolution type.
  YPARM.....Array containing parameters for YTYPE.
  GUARD.....Fraction of the x and y radius for which uv samples
            are not allowed.  < 0 => just enough to avoid
            mathematical errors in the convolution.
              0 => 0.3 * SQRT(taper weight at 0.3 from edge).

   The following control CLEANing:
  NBOXES.....Number (<=50) of rectangular search boxes to search on the
             first field; the Clean window in all other fields is given
             by  FLDSIZE.  0 => use FLDSIZE to determine windows on
             field 1.
  CLBOX......A 4x50 array with the parameters of each box.
             0 => use window specified in FLDSIZE.
             CLBOX(1,i)=-1 indicates a circle of radius CLBOX(2,i)
                pixels centered on (CLBOX(3,i), CLBOX(4,i)).
             CLBOX(1,i) >= 0 indicates a rectangular box.  NOTE: CLBOX
             is not used to determine the size of the image to be made;
             IMSIZE or FLDSIZE must set the size of the image.
  OBOXFILE...Output text file to record the Clean boxes used.  Each time
             a TV REBOX or TVBOX is selected the file is rewritten (as
             the TV interaction ends) with all of the Clean boxes
             currently in force for all fields
  GAIN.,.....The CLEAN loop gain.  0 => 0.10.
             Can be changed by TELL.
  FLUX......Stop CLEAN when abs(resid. image max) < FLUX (Jy)
            IF FLUX < 0 then Clean stops at first negative
            Clean Component.  Can be changed by TELL.
            SCMAP may lower this values and in general uses 1.0
            times the previous RMS residual unless a lower value
            has been set.
  MINPATCH..Minimum half width of the portion of the beam
            which is used in the AP minor CLEAN.
            Can be changed by TELL.
  NITER.....CLEAN iteration limit.  This is an upper limit as
            each CLEAN may stop prior to this limit.  The final
            CLEAN  continues until NITER CLEAN components are
            found. Can be changed by TELL.
            0 => 200
  BMAJ......The FWHM (asec) major axis of the restoring beam.
            If 0; value obtained from fitting to the beam.
            Can be changed by TELL
  BMIN......The FWHM (asec) minor axis of the restoring beam.
            Can be changed by TELL.
  BPA.......The position angle in the unrotated image of BMAJ.
            Can be changed by TELL.
  FACTOR....FACTOR>0 causes deeper CLEAN in each major cycle,
            speeding CLEAN, maybe "eating" extended structure.
            FACTOR=0 => the normal Clark CLEAN. FACTOR=-0.3 is
            good for deep CLEANs of extended structure.
            Can be changed by TELL.
  MAXPIXEL..The maximum number of pixels that are searched
            for components inside the ``AP'' in each major
            cycle.  < 3000 => 20050.  This number affects the
            cpu usage significantly.  Too many causes the task
            to search over many points it will never use.  Too
            few causes the task to do many more small major
            cycles, also at great expense.  Use this with great
            caution, but big wins are possible using larger
            sizes on very large cleans.
  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.
            Can be changed by TELL: once set to 'DFT' it can
            no longer be changed, however.

   The following control self-calibration:
  NMAPS......Number of self-calibration loops.
  SMODEL.....A single component model to be if SMODEL(1)>0
                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 (others NYI)
  REFANT.....The desired reference antenna for phases.
  SOLINT.....The solution interval (min.)
             0 => data interval which may or may not be a good
             idea.  SCMAP doubles SOLINT when(if) it switches
             from phase only to amp & phase solutions.
  APARM......Task enrichment parameters:
  APARM(1)...Minimum number of antennas allowed for a solution.
             < 3 => 4.
  APARM(2)...If >0 then constrain the mean gain modulus of the
             calibration applied to be unity.
  APARM(3)...If > 0 then average RR, LL.
  APARM(5)...If > 0 then make a combined solution for the IFs;
             if <= 0 then make separate solutions.
  APARM(6)...Print flag, 0=none, 1=time,some info including the antenna
             signal to noise ratio, 2=lots.
  APARM(7)...The minimum allowed solution signal-to-noise ratio.  0 => 5
  APARM(8)...SIGMA.  Each CLEAN can be restarted using a subset of the
             components from the previous CLEAN.  All merged components
             brighter than SIGMA*(residual_RMS) will be reused. 0 => 10
  APARM(9)...Averaging time used when data are read into the interactive
             editing tool in minutes.  <= 0 => SOLINT.
  APARM(10)..Amplitude solutions may be box-car smoothed wrt the phase
             solutions by APARM(10) minutes.
  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.
  SOLMODE....Solution mode:
              'A&P ' => amplitude and phase.
              'P   ' => phase only
              'P!A ' => phase only (no amplitude information)
              'GCON' => amplitude and phase with constraints on
                        amplitude.  This mode requires setting
                        SOLTYPE='GCON', uses GAINERR and
                        SOLCON may be used.
              '    ' => start with phase only and switch to amp and
                        phase.
  SOLCON.....Gain constraint factor; a value larger than 0 will increase
             the strength of the amplitude constraint in gain
             constrained solution with SOLMODE='GCON'
  ANTWT......Antenna weights.  These are additional weights to be
             applied to the data before doing the solutions, one per
             antenna.  Use PRTAN to determine which antenna corresponds
             to each antenna number.  0 => 1.0
  GAINERR....Estimates of the standard deviation of the modulus of the
             gains for each antenna.  These are used ONLY if SOLMODE and
             SOLTYPE='GCON'.  The solution will attempt to make the
             standard deviation  of the modulus of the antenna gains
             match these values so accurate values are essential.
  WTUV.......The weighting factor for data outside of the uv range given
             full weight.   <= 0 => 0.05.
             Warning: SCMAP sets its own UVranges for self-cal and it is
             a bad idea to have WTUV near zero when these ranges are
             small.
  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
  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 SN table to apply.  0 => highest.
  DOPOL......If > 0 then correct data for instrumental polarization as
             represented in the AN table.  Only one subarray may be
             done at a time.  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.
  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
             on input.
  OUTFGVER...Flag table version to be used on output for both single-
             and multi-source data sets.  If OUTFGVER is <= 0 or
             greater than FGmax (the previously highest FG version
             number), then a new FG table will be created for the new
             flags with version FGmax+1.  This new table will also
             contain the flags applied on input (if any) from FG
             version FLAGVER.  If OUTFGVER specifies a pre-existing FG
             version, then the input flags are not copied even if
             OUTFGVER and FLAGVER are not equal.
  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.
  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).
  DOTV.......Display residuals on TV channel 1. > 0 => display field
             number DOTV initially. Can be changed by TELL.  When using
             this option, you may interact with the residual images at
             the end of each major cycle of Clean, selecting which field
             is examined in what window, resetting the Clean boxes, and
             stop the CLEANing of the current self-cal loop.
             SCMAP additional option: DOTV < or > 0 => display field
             number abs(DOTV) at the end of each Clean and interact with
             that image including UV data editing options.  If DOTV < 0,
             the only display is at the end of each Clean else both are
             done.  DOTV = 0 => no TV display.  It is strongly
             recommended that you use at least DOTV = -1.  That display
             lets you change parameters including DOTV to resume the
             display during Clean.
  DOWEIGHT...The display of error bars in the editing phase depends on
             the data weights being 1/(sigma**2) in 1 (Jy**2).  Set
             DOWEIGHT to get the data weights into this scale,
             multiplying the input weights by DOWEIGHT.  0 -> 1.
  DOTWO......> 0 (true) means to do the secondary plot of a second
             observable (phase, amplitude, diff amplitude) from the
             primary baseline in the editing phase.  <= 0 means to plot
             only the primary observable used for the editing.  True is
             highly recommended.
  BADDISK....This array contains the numbers of disks on which it is
             desired that scratch files not be located.
             BADDISK has no effect on input and output data.
  BPARM......Subarray relative weight factors; applied to all data.
  CPARM......Subarray refence antenna (2->10 only).
----------------------------------------------------------------
SCMAP:  Imaging - self-calibration loop task.
Documentor:  W. D. Cotton, NRAO
Related Programs: CALIB, MX, EDITR

       This task will do multiple iterations of self-calibration and
imaging optionally starting with a one component model (SMODEL).   Each
iteration consists of 1) a visibility-based imaging and Clean
deconvolution (like IMAGR), 2) determination of the appropriate number
of Clean components and self-calibration uvrange, and 3)
self-calibration of the visibility data based on the new model.  A final
imaging/deconvolution is then done using the solution which gave the
best RMS/(sum CC) residual.  This solution is then used to produce the
final output uvdata.
   Only I polarization data is imaged but the resulting self-calibrated
uvdata will contain properly calibrated data for all input
polarizations.
   For spectral line data a "continuum" data set should be formed from
selected line channels using SPLIT, UVCOP etc. and used as the input to
SCMAP.  The resultant image can then be used with CALIB to calibrate the
line data set

   This task uses a number of techniques to improve the efficiency and
stability of the self-calibration process.  After the first Clean,
future Cleans may be restarted using some number of components from the
previous Clean.  In addition, the minimum residual level is set the RMS
residual of the previous Clean.
   The number of Clean components used in the next Clean is determined
from the value of APARM(8).  The previous CC table is first merged and
then all components brighter than APARM(8) times the RMS residual of the
previous Clean are reused.

Depth of Clean:
   Each self-calibration iteration SCMAP decides on the depth of the
Clean.  The Clean proceeds until the absolute value of the residual is
the RMS residual of the previous iteration.  This can be modified by
using adverbs NITER and FLUX.  Cleaning never proceeds longer than NITER
iterations and FLUX will never be increased.  Deeper Cleans can be
forced by setting FLUX to a small, but positive value and NITER to a
sufficiently large number. The final Clean is up to NITER components
with no minimum flux density level test.
   The number of iteration is not a totally accurate determination of
the depth of Clean as the CC table is merged each cycle and some
components will be reused.  Thus, the Clean is deeper than would be
obtained from the same number of components without merging.
   Both NITER and FLUX may be adjusted interactively during the self-cal
TV interaction.

Uv Baseline Range:

   The range of baseline lengths (UVRANGE) specified in the input is
only used in the imaging step.  In each iteration of self-calibration
the appropriate uv range and number of Clean components to use is
determined heuristically.  The Clean components are merged and all
components up to the first negative one are used.  The corresponding uv
range for self-calibration is determined from comparison of the sum of
the flux in the Clean model and the distribution of average amplitudes
as a function of baseline length.  Baselines longer that the longest
with an average higher that the summed Clean model are given full
weight.  A slight tolerance (1 sigma) is used to allow for noise.
   Baselines outside of the range given full weight are weighted by the
factor UVWT.  Note there is no default and UVWT=0 causes this data to be
completely ignored.

Convergence:

   The test for convergence is based on the RMS residual value (ignoring
the outer pixels) of the Clean image divided by the sum of the Clean
flux.  Convergence is declared when either the convergence measure
increases by more than 10 percent or if more than three self-calibration
cycles has elapsed since the best solution.  When convergence is
obtained the solution with the best convergence measure is used to
produce the final image and uv data.

Solution Mode:

   The solution type can be set to either 'P', 'P!A', 'A&P' or '   '.
The first three will cause only solutions of the appropriate type to be
performed.

   If SOLMODE is set to '    ' the self-calibration solutions are
initially done using only phase until the convergence measure no longer
shows improvment.  The last self-calibration solution is then applied to
the input data and a new scratch file is filled with the result.
Further processing uses this data.
   After the mode switch amplitude calibration is enabled and all
selected IFs and polarizations are averaged in the self-cal solutions.
The minimum number of antennas is changed to 4 if it is initially less
and gain constraint is enabled (APARM(2)). Also, the solution interval
(SOLINT) is doubled; or, if an initial value of 0 was given 30 seconds
is used.

Restarting:

   If SCMAP previously terminated normally then the output uv data is
suitable for input for another execution.  If SCMAP did not terminate
normally then the last SN table produced can be used as the starting
calibration (see DOCALIB and GAINUSE).  This method can recover results
up to a switch between phase only and amplitude and phase calibration
(see discussion above on SOLMODE).  After a mode switch the working data
is written to the output file.  A restart can then use the output of the
previous run and the last SN table attached to it.  If SCMAP terminated
normally there will be no SN tables attached to the output.
   The output Clean image should always have a CC version 2 which is a
copy of the latest, merged CC table.  This table can always be used with
CALIB to produce suitable input for SCMAP.

Limiting messages:

   SCMAP can produce a large quantity of messages.  These messages can
be limited using the verb MSGKILL.  MSGKIL 4 will result in only the
most important messages.

****************************************************************
***********************   TV DISPLAYS   ************************
****************************************************************

**********************   During Clean:   ***********************

     The TV display may be used to follow the progress of your imaging
and Cleaning.  If you set DOTV > 0, the dirty image of field DOTV will
be displayed before Clean begins and the residual image of the selected
field will be displayed after each major Clean cycle.  When the image is
displayed, a menu of interactive options is also displayed.  Move the TV
cursor to a desired option, and press TV button A, B, or C.  To get help
on the message screen about an option, move the cursor to that option
and press TV button D.  The selected option is highlighted in a
different color.  If you select no options in 30 seconds, SCMAP will
continue without you until the end of the next major cycle. Interactive
options do not appear on the final display which is either of the dirty
image (NITER = 0) or the Clean image with components restored.  If you
forget to turn on the TV display - or turn it off after starting SCMAP -
you may turn it back on with TELL SCMAP (say SHOW SCMAP in AIPS to see
all the TELL parameters that you may send to SCMAP after it has
started).

     The interactive options appear in two columns.  The left column
offers:
----------------
| OFFZOOM      |   turn off any zoom magnification
| OFFTRAN      |   turn off any black & white enhancement
| OFFCOLOR     |   turn off any pseudo-coloring
| TVFIDDLE     |   as in AIPS, allows zoom, pseudo-color contours or
                   black and white enhancement
| TVTRAN       |   black and white enhancement as in AIPS
| TVPSEUDO     |   many pseudo-colorings as in AIPS
| TVFLAME      |   flame-like pseudo-colorings as in AIPS
| TVZOOM       |   interactive zoom magnification and center
| CURVALUE     |   display image intensity, pixel x/y at cursor
| SET WINDOW   |   set sub-image display window
| RESET WINDOW |   re-set display window to full image
| TVBOX        |   set number of Clean boxes and their
                   parameters interactively
| REBOX        |   modify and add Clean boxes for this field
----------------
When a field is displayed, the pixel increments are chosen to load the
full field to the TV screen.  The TV window is even forced to be bigger
to show the image if needed and small fields are interpolated by up to a
factor of 3.  The Clean boxes for the field are displayed in a graphics
overlay.  You may select a smaller sub-image of the field for display in
greater detail, but SCMAP does insist that the sub-image includes all
Clean boxes for the field.  You may use TVBOX or REBOX to create and
modify the Clean boxes interactively.  Note that these set the number as
well as the type and parameters of the boxes.  This is currently one of
two interactive ways to set Clean boxes for fields numbered > 1.  The
other if the verb FILEBOX in AIPS.

TVBOX: To set the number, type, and parameters of the Clean boxes for
the displayed field with a TV graphics display of the boxes as they are
being set.  The terminal will issue instructions.  While setting the
lower left corner of each box for the first time, buttons A and B will
mark the corner and switch to setting the upper right corner of the box.
Button C will change the rectangular box to a circular one and button D
will exit.  Similarly, while first setting the center of a circular box,
buttons A and B switch to setting the radius, C switches back to a
rectangular box, and D exits deleting that incomplete box.  While
setting or re-setting the upper right corner or radius of the box or
re-setting the lower left corner or center, button A marks the current
corner and switches to the other corner (or marks and switches between
radius and center), button B marks the current corner and switches to
the next (new) box, button C marks the current corner and switches to a
search mode leading to the resetting of a previous box, and button D
exits keeping the current and previous boxes with their current
settings.  In search mode, move the cursor to any lower left or upper
right corner of any already set rectangular box or the center or any
point on the circumference of an already set circular box and press
button A or B to reset that corner or push button C to go on to the next
box.  As usual button D exits.  REBOX is TVBOX started with the current
boxes in a resetting mode.

     The right-hand column offers the options:
-------------------
| CONTINUE CLEAN  |   Continue Cleaning now, not waiting for the timer
                      to expire
| STOP CLEANING   |   Declare the Clean of this channel done, restore
                      components and write the output
| TURN OFF DOTV   |   Resume Cleaning now and turn off future TV
                      displays
| ABORT TASK      |   Drive a silver stake through SCMAP's heart without
                      waiting for a full moon or even for midnight.
-------------------
If you turn off the TV display, you may restart it with TELL from AIPS.

****************************************************************
********************   Before self-cal:   **********************
****************************************************************

     The TV display may be used also (or instead) to follow the progress
of your imaging at the end of the Clean step before doing the next
self-cal.  If you set DOTV not= 0, the residual image of field DOTV will
be displayed after Clean ends.  When the image is displayed, a menu of
interactive options is also displayed.  Move the TV cursor to a desired
option, and press TV button A, B, or C.  To get help on the message
screen about an option, move the cursor to that option and press TV
button D.  The selected option is highlighted in a different color.  If
you select no options in 30 seconds, SCMAP will continue without you
until the end of the next major cycle of Clean (if selected) or until
the end of the next Clean.  If you forget to turn on the TV display - or
turn it off after starting SCMAP - you may turn it back on with TELL
SCMAP (say SHOW SCMAP in AIPS to see all the TELL parameters that you
may send to SCMAP after it has started).

     The interactive options appear in two columns.  The left column
offers:
------------------
| OFFZOOM        |   turn off any zoom magnification
| OFFTRANS       |   turn off any black & white enhancement
| OFFCOLOR       |   turn off any pseudo-coloring
| TVFIDDLE       |   as in AIPS, allows zoom, pseudo-color contours or
                     black and white enhancement
| TVTRAN         |   black and white enhancement as in AIPS
| TVPSEUDO       |   many pseudo-colorings as in AIPS
| TVFLAME        |   flame-like pseudo-colorings as in AIPS
| TVZOOM         |   interactive zoom magnification and center
| CURVALUE       |   display image intensity, pixel x/y at cursor
| SET WINDOW     |   set sub-image display window
| RESET WINDOW   |   re-set display window to full image
| TVBOX          |   set number of Clean boxes and their parameters
                     interactively
| REBOX          |   modify and add Clean boxes for this field
| EDIT DATA      |   select the data editing tool to view visibility
                     data and current residuals and delete bad points
| SET PARAMETERS |   Reset various adverb values.
| SWITCH TO A&P  |   Switch from phase-only to amplitude and phase
----------------
When a field is displayed, the pixel increments are chosen to load the
full field to the TV screen.  The TV window is even forced to be bigger
to show the image if needed and small fields are interpolated by up to a
factor of 3.  The Clean boxes for the field are displayed in a graphics
overlay.  You may select a smaller sub-image of the field for display in
greater detail, but SCMAP does insist that the sub-image includes all
Clean boxes for the field.  You may use TVBOX or REBOX to create and
modify the Clean boxes interactively.  Note that these set the number as
well as the type and parameters of the boxes.  The EDIT DATA selects a
data editing tool described below.  It is slow in starting up so do not
select this option more than needed.

SET PARAMETERS: Since SCMAP is run as an interactive task, TELLing it to
change parameters requires a second AIPS session and some care.  This
option brings up a question and answer session that prompts you for all
TELL parameters plus a couple other useful ones.  Answer with a blank
line (simple carriage return) to leave the parameter unchanged; answer
with a Q or q to stop the questioning.  The parameters are, in order,
NMAPS, DOTV, SOLINT, APARM(10), NITER, APARM(9), APARM(8), FLUX, GAIN,
FACTOR, MINPATCH, MAXPIXEL, BMAJ, BMIN, BPA, REFANT, WTUV, SOLTYPE,
SOLMODE, SOLCON.  If SOLMODE is already A&P due to a switch from P, do
not change it.

SWITCH TO A&P: If this option is offered, you may declare to SCMAP that
enough phase-only iterations have been done and that it is time to do
the switch to amplitude and phase.  The option is offered only if
SOLMODE = ' ' to begin with and, then, only if the switch has not
already taken place.  SCMAP applies the latest phase calibration to the
input data moving them to another file.  Then it doubles the SOLINT and
does the remaining self-cals as A&P.  If you want to ignore the previous
phase cals (other than by their effect on the current Clean image), use
SET PARAMETERS and change SOLMODE instead.

TVBOX: To set the number, type, and parameters of the Clean boxes for
the displayed field with a TV graphics display of the boxes as they are
being set.  The terminal will issue instructions.  While setting the
lower left corner of each box for the first time, buttons A and B will
mark the corner and switch to setting the upper right corner of the box.
Button C will change the rectangular box to a circular one and button D
will exit.  Similarly, while first setting the center of a circular box,
buttons A and B switch to setting the radius, C switches back to a
rectangular box, and D exits deleting that incomplete box.  While
setting or re-setting the upper right corner or radius of the box or
re-setting the lower left corner or center, button A marks the current
corner and switches to the other corner (or marks and switches between
radius and center), button B marks the current corner and switches to
the next (new) box, button C marks the current corner and switches to a
search mode leading to the resetting of a previous box, and button D
exits keeping the current and previous boxes with their current
settings.  In search mode, move the cursor to any lower left or upper
right corner of any already set rectangular box or the center or any
point on the circumference of an already set circular box and press
button A or B to reset that corner or push button C to go on to the next
box.  As usual button D exits.  REBOX is TVBOX started with the current
boxes in a resetting mode.

     The right-hand column offers the options:
-------------------
| CONTINUE SELFCAL|   Continue self-cal now, not waiting for the timer
                      to expire
| STOP SELFCAL    |   Declare the self-cal done, do a deeper Clean and
                      write out the final images and calibrated data set
| TURN OFF TV     |   Resume processing now and turn off future TV
                      displays
| ABORT TASK      |   Drive a silver stake through SCMAP's heart without
                      waiting for a full moon or even for midnight.
-------------------
If you turn off the TV display, you may restart it with TELL from AIPS.
That will require using a second AIPS session since the AIPS session
that started SCMAP is suspended until it ends.

****************************************************************
*********************   While editing:   ***********************
****************************************************************

     SCMAP implements a version of task EDITR as a TV graphic editor
for uv data using the uv data themselves and the current residuals.  It
works with the XAS-TV display graphics planes (7 of them) to allow you
to flag uv data based on their values.  It does not change the input
data set, but will write a flag table used in the next step of self-cal.

     The editor averages spectral channels and over a specified time
interval as it reads the data set(s).  It attempts to read the entire
data set into the pseudo-AP memory when if starts up.  If it cannot fit
all the data, it attempts to read just one IF at a time and/or all
baselines to one antenna at a time.  In that case, when you switch IFs
or main antennas, the editor has to reads in the next IF or set of
baselines.  The editor will tell you as it starts whether "All data will
reside in memory" or  various other combinations.  Judicious choices of
APARM(9) can help the task to read all selected data and thus to be more
efficient

     There are 6 parts to the editor's display:
(1) A menu of operations displayed in two columns, one each at the left
and right sides of the screen.  When the menu is displayed, move the
cursor to the desired item and press buttons A, B, or C.  To get on-line
help in the message window about a given option, move the cursor to the
desired menu item and press button D.
(2) A plot at the bottom of the screen in a bright color (usually) of
the data which may be actively edited at present.  It is of the chosen
type for the selected baseline, polarization, and IF and is limited in
time range by the current frame (which can be all or a portion of the
total time range).  Flagged data are shown in a different color.  The
time range of the frame may be made small to expand the time axis, but
may also be made so large as to cause serious crowding of the plotted
data points.  (Increase your XAS window width to increase the plot
scale.)
(3) A plot above the edit area plot in the same bright color of the data
from the selected baseline, polarization, and IF.  This plot is in a
second observable (e.g. if amplitude is in the edit plot, phase is often
the second observable).  Data in this second area may not be used for
editing but should be helpful in choosing which data to delete in the
edit area.  Flagged data are shown in a different color.  This plot may
be suppressed by adverb DOTWO.
(4) 0-10 plots of data of the current data type, IF, and polarization
for a list of 0-10 other baselines to the main antenna are shown above
the second plot.  They are shown for comparison using another color,
while flagged data are shown in a different color.
(5) Data from the Clean residuals will be shown in another color in each
of the windows (2, 3, 4) above.  This display may be turned off and on
with a menu item.
(6) Several text areas also appear including (a) the start and end times
for the current frame's time axis, (b) the selected data type, IF, and
polarization at the bottom of the screen, (c) the antenna shown in each
plot at the top right of each plot, (d) the current all-IF,
all-polarization, and all-antenna flags, (e) the y-axis tick values on
each of the frame plots, and (f) while interactively setting time and/or
value ranges, the time and/or value to which you are currently pointing
and the associated source name.

     You may change the size of the XAS window at any time.  The editor
will not allow it to become too small, but will adjust its display for
all reasonable sizes.

     The left-hand menu can contain
-------------------
| FLAG TIME       |  To delete one time at a time.
| FLAG TIME RANGE |  To delete one or more time ranges.
| FLAG BELOW      |  To delete all displayed times with data below a
                        cutoff value.
| FLAG ABOVE      |  To delete all displayed times with data above a
                        cutoff value.
| FLAG AREA       |  To delete one or more areas in the data-value -
                        time plane.
| FLAG POINT      |  To delete one sample at a time using both
                        horizontal and vertical cursor position.
| FLAG FAST       |  To delete samples using only mouse clicks
| ENTER AMPL RNG  |  To select the display range for amplitude plots.
                        Use 0 -1 for 0 to antenna maximum and
                        0 0 for min to max.
| ENTER PHASE RNG |  To select the display range for phase plots.
| ENTER DAMP RNG  |  To select the display range for plots of the
                        amplitude of the visibility minus a running
                        vector average visibility.
| PLOT ERROR BARS |  To plot error bars based on data weights
| SET SCAN LENGTH |  To set the averaging time used to determine the
                        running average in seconds.
| LIST FLAGS      |  To list all flags now in the Flag Command table.
| UNDO FLAGS      |  To undo one of the flag operations in the FC table
| REDO FLAGS      |  To reapply all remaining flags after one or more
                     have been undone (see note below)
| SET REASON      |  To set the 24-character "reason" string to be put
                        in the uv-data flag table
| USE EXPERT MODE |  To control the task from the keyboard instead of
                        the menu.
| HOLD TV LOAD    |  To stop updating the TV display with every change
                     of parameter; change several, then select
| DO TV LOAD      |  To update the TV display now and with each change
                     of display parameter.
| REPLOT          |  To do the current plot over again, recomputing
                     the differences from the running mean if
                     appropriate.
| EXIT            |  To exit editing, moving the FC table to a uv-data
                     FG table
| ABORT           |  To exit editing, deleting the FC table
-------------------

     The right-hand menu can contain
-------------------
| NEXT CORRELATOR |  To switch to viewing the next correlator,
                        switching to the other polarization and, if
                        needed, incrementing the IF.
| SWITCH POLARIZ  |  To switch to viewing and editing the other
                        polarization.
| SWITCH ALL POL  |  To switch functions from applying to one
                        polarization to applying to both polarizations
                        or vice versa.
| ENTER IF        |  To select which IF is viewed and edited.  This
                        can force a read of data if all IFs did not fit
                        in memory.
| SWITCH ALL IF   |  To switch functions from applying to one IF to
                        applying to all IFs or vice versa.
| SWITCH ALL TIME |  To switch FLAG ABOVE and FLAG BELOW between all
                        times and the time range of the frame
| ROTATE ALL ANT  |  To rotate functions from applying to (a) one
                        baseline, (b) all baselines to the main antenna,
                        and (c) all baselines.
| ENTER ANTENNA   |  To select the main antenna, baselines to which are
                        displayed on the screen.
| ENTER OTHER ANT |  To select up to 11 other antennas to define the
                        baselines to be displayed; enter 10 numbers, 0's
                        are then ignored (to plot 5 enter the 5 plus 6
                        0's).  The first one is used for the edit area.
| NEXT BASELINE   |  To rotate the list of other antennas, selecting
                        the next one for the edit area.
| NEXT ANTENNA    |  To select a new main antenna, one higher than the
                        current main antenna.  The "others" MAY also
                        be adjusted.
| PLOT ALL TIMES  |  To display all data for the selected baselines.
| SELECT FRAME    |  To select a window into the current data
                        interactively.
| NEXT FRAME      |  To select the next time-range window of the same
                        size as the current frame.
| PREVIOUS FRAME  |  To select the previous time-range window of the
                        same size as the current frame.
| SHOW AMPLITUDE  |  To display and edit amplitudes.
| SHOW PHASE      |  To display and edit phases.
| SHOW DIFF AMPL  |  To display and edit the amplitudes of the vector
                        difference between the sample and its running
                        mean
| SHOW ALSO AMPL  |  To display amplitudes of the edit baseline for
                        reference with the phase or difference
                        amplitude edit window.
| SHOW ALSO PHASE |  To display phases of the edit baseline for
                        reference with the amplitude or difference
                        amplitude edit window.
| SHOW ALSO DAMP  |  To display difference amplitudes of the edit
                        baseline for reference with the phase or
                        amplitude edit window.
| TV ZOOM         |  To alter the display zoom used while in the flag
                        functions.
| OFF ZOOM        |  To turn off any zooming.
| 2ND UV OFF      |  To disable the display of the residual uv data set.
| 2ND UV ON       |  To enable the display of the residual uv data set.
-------------------

     The menus will not show all of these options every time.  The HOLD
TV LOAD option is shown until invoked, and then is replaced with the DO
TV LOAD.  When that is invoked, the HOLD TV LOAD option reappears. The
SWITCH POLARIZ and SWITCH ALL POL options appear only if there are two
polarizations in the data.  The ENTER IF option appears only if there is
more than one IF in the data and the SWITCH ALL IF option appears only
if there is more than one IF and all IFs fit in the program memory.
Only one of the three SHOW ALSO choices appears at any one time.

     Plots of the difference between the visibility and its running mean
can be particularly sensitive to short term disturbances while ignoring
slow changes due to gradually changing source structure and the like.
The running mean is not carried between sources and, as a result, is not
normally carried across scan boundaries.

     Note that value-dependent flagging (FLAG BELOW, ABOVE, AREA) use
the values currently plotted to make a list of value-independent flag
commands (i.e., a single time for the specified antennas, IFs,
polarizations, etc.).  When a value-dependent FLAG operation is undone
(UNDO FLAGS) or redone (REDO FLAGS), it is these value-independent flags
which are undone or redone.  You may have to undo more commands and then
repeat FLAG commands to get the results you could have gotten by doing
the now desired value-dependent command in the first place.  You need
also to be careful with the ROTATE ALL ANT setting with these
value-dependent commands.  If one baseline is set, then the commands
only apply to the current baseline.  If one antenna is set, the commands
apply to all baselines to the current main antenna, while if all
antennas is set, the commands apply to all baselines.  The first two set
a clip level, below or above which data are deleted, based on the value
of the observable in each baseline independently.  The FLAG AREA
command, however, only looks at the values of the observable in the main
edit baseline and flags those samples from all applicable baselines.

     Be careful when choosing EXIT versus ABORT.  The former applies the
flag commands to a flag table attached to the input uv data, the latter
causes the flag commands to disappear without a trace.

     The colors used by EDITR are those of the various graphics planes
when it begins to run.  You may change them with the AIPS verb GWRITE to
more desirable colors.  The planes are:
   Plane     Default RGB      Use
     1     1.00  1.00  0.00   Main editing and secondary windows
     2     0.06  1.00  0.00   Comparison baseline data windows
     3     1.00  0.67  1.00   Menu highlight
     4     0.00  1.00  1.00   Edit and frame window boundaries
     5     1.00  0.18  0.18   Flagged data in all windows
     6     0.60  0.60  1.00   Menu foreground
     7     1.00  0.80  0.40   Second uv data set if present
You may wish to change the colors to ones that you can see better.

     In "expert" mode, you are prompted with a set of 4-character codes.
You type in the letter within that code that is shown in upper case
(left-justified with a carriage return) to get the desired function.
The expert functions allowed are

      Code  Prompt  Full menu OP name
         T   Time   FLAG TIME
         R   Rang   FLAG TIME RANGE
         B   Belo   FLAG BELOW
         A   Abov   FLAG ABOVE
         E   arEa   FLAG AREA
         O   pOin   FLAG POINT
         Q   Quik   FLAG FAST
         L   List   LIST FLAGS
         U   Undo   UNDO FLAGS
         S   baSl   NEXT BASELINE
         C   nCor   NEXT CORRELATOR
         N   Nant   NEXT ANTENNA
         F   Fram   SELECT FRAME
         M   aMpl   SHOW AMPLITUDE
         P   Phas   SHOW PHASE
         D   aDif   SHOW DIFF AMPL
         X   eXit   EXIT EXPERT MODE
         H   Help   THIS HELP LIST

although some may be suppressed depending on what is currently
displayed.
------------------------------------------------------------------------

