!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!
begin data gag_scratch:selfcal.hlp
1 SELFCAL
    SELFCAL [?|AMPLI|APPLY|PHASE|SUMMARY|SHOW [Threshold|Last [First]] [/WIDGET]
  
  Command to perform Self Calibration (even on spectral line data). 
  The solution is computed, saved and/or applied.

  The arguments control the action.
    SELFCAL ?        Lists the self calibration parameters
    SELFCAL AMPLI    Compute an Amplitude only self calibration
    SELFCAL APPLY    Apply the computed solution
    SELFCAL FLAG []  Flag data according to self calibration correction
    SELFCAL PHASE    Compute a Phase only self calibration
    SELFCAL SHOW []  Show the computed corrections
    SELFCAL SAVE     Save self calibration parameters in selfcal.last
    SELFCAL SUMMARY  Display the improvements in Noise & Dynamic range
                     and calibration status
2 /WIDGET
    SELFCAL /WIDGET
    
    Activates the widget interface to perform self calibration (even on
  spectral line data set). A continuum data set is extracted from the
  specified channel range, with all selected channels averaged to
  provide improved sensitivity to find a solution.

  The buttons control the action.
     AMPLI    Perform an Amplitude only self calibration
     PHASE    Perform a Phase only self calibration
     Continue Continue execution when the script is in Pause
     APPLY    Apply the solution
     FLAG     Flag data (without correction)
     INPUT    List parameters (as in SELFCAL ?)
     SAVE     Save the parameters in selfcal.last
     SHOW     Show the computed corrections
     SUMMARY  Display the improvements in Noise & Dynamic range

2 Arguments:

  The arguments control the action.
    SELFCAL ?        Lists the self calibration parameters
    SELFCAL AMPLI    Perform an Amplitude only self calibration
    SELFCAL APPLY    Apply the solution
    SELFCAL FLAG []  Flag data according to self calibration correction
    SELFCAL PHASE    Perform a Phase only self calibration
    SELFCAL SAVE     Save the parameters in selfcal.last
    SELFCAL SHOW []  Show the computed corrections
    SELFCAL SUMMARY  Display the improvements in Noise & Dynamic range

2 AMPLITUDE
    SELFCAL AMPLI
    
    Compute an Amplitude only self-calibration. The integration
  times, SELF_TIME, should in general be significantly larger
  than for a Phase only self-calibration.
    SELFCAL automatically adjusts the gains so that their mean is
  1.0, to avoid changing the flux scale.
  
  See HELP SELFCAL SELF_LOOP to find out how to control the number
  of iterations.
    
2 APPLY
    SELFCAL APPLY
    
    Apply the self calibration solution. This is done only
  if the return status from the previous computation, SELF_STATUS,
  is > 0.  SELFCAL APPLY automatically saves the parameters and 
  results in the "selfcal.last" file.
  
2 FLAG
    SELFCAL FLAG [Threshold]
    
    Flag data which have no valid correction, or a correction
    above the specified Threshold (in degrees, > 0 for PHASE, 
    no units, > 1 for AMPLI). No correction is applied however.
    
    With the Widget interface, no Threshold is applied.
    
2 INPUT
    SELFCAL INPUT  or SELFCAL ?
    
    Display SELFCAL control variables
    
2 PHASE
    SELFCAL PHASE
    
    Compute a Phase-only self calibration. The integration time should
  be short enough to correct for atmospheric errors, but large enough
  to obtain significant signal to noise for most antennas.
  
2 SAVE
    SELFCAL SAVE
    
    Save the parameters and results in the "selfcal.last" file.

2 SHOW
    SELFCAL SHOW [Last [First]]

    Shows the correction computed by self calibration.
  By default, the difference between the last two iterations is
  displayed: phase should be around 0, and amplitude around 1
  if the solution is converged.
    
    If Last and First are present, it shows the difference
  between these two specified iteration.
    If Last only is present, it shows the total correction 
  between the original data and that iteration.
  
2 SUMMARY
    SELFCAL SUMMARY
    
    Display a summary of the Self-calibration process: type of
  calibration, rms and dynamic range at each iteration, as well
  as the number of flagged or uncalibrated visibilities.

2 Results:
    SELFCAL returns results in several variables, creates a CGAINS
  array containing the Gain values, and one file to display the
  computed correction. The file name is specified by SELF_SNAME.
    
  The result variables are:    
    SELF_APPLIED
      Indicates whether the solution has been applied      
    SELF_STATUS 
      Indicates if a solution has been computed    
    SELF_DYNAMIC[Self_Loop+1]
      The dynamic range at each iteration
    SELF_RMSCLEAN[Self_Loop+1]
      The rms noise at each iteration

2 SELF_APPLIED

    Indicates whether a solution has been applied (#0) or not (0).
  The value indicates the type and quality of solution, as for 
  SELF_STATUS

2 SELF_STATUS

    Indicates if a solution has been computed
      0 no solution
      +/- 1   Phase solution
      +/- 2   Gain solution
    >0 means a good solution, <0 a poor one.

2 SELF_DYNAMIC

    Variable length array of size Self_Loop+1, containing the
  dynamic range at each iteration.
     
2 SELF_RMSCLEAN

    Variable length array of size Self_Loop+1, containing 
  Clean map rms noise at each iteration.

2 Variables:

    SELFCAL behaviour can be adjusted through control variables
  named SELF_... (see EXA SELF_ for a list), in addition to the
  control variables of UV_MAP (MAP_...) and CLEAN (CLEAN_...)  

    The most important variable is SELF_TIMES, a variable length array 
  which controls the integration time at each loop. SELF_NITER and 
  SELF_MINFLUX also control the number of Clean components and minimum 
  flux retained in each loop. These arrays define the number of loops. 

  See HELP SELFCAL SELF_LOOP to find out how to control the number
  of iterations.
    
2 SELF_CHANNEL

    SELF_CHANNEL[2]

    First and last channel to define the range to compute the UV table
  for the self-calibration solution. For example, if you have used
  UV\_PLUGC to plug a continuum data into the last channel, this could
  be set to the number of channels. 0 0 means all channels are averaged
  to compute the "continuum" image.

2 SELF_LOOP

    Number of self-iteration loops. It is a ReadOnly variable that 
  is automatically computed from the size of the variable length
  arrays SELF_TIMES, SELF_NITER and SELF_MINFLUX.  
  
    These variable length arrays can be resized using the LET /RESIZE
  command. For example
    LET SELF_TIMES 40 20 10 /RESIZE
  will lead to an array of 3 elements, SELF_TIMES[3]. 
  
  SELF_TIMES, SELF_NITER and SELF_MINFLUX must be of equal size. To
  simplify the process, constant arrays are assumed of arbitrary 
  length in this determination.  If all 3 arrays have constant values, 
  SELF_TIMES determines the number of loops. 
    
2 SELF_NITER

    Variable length array specifying the number of Clean components
  retained for each loop of the self-calibration process.  Default is 0,
  meaning all Clean components found by CLEAN.

    For simple structures and Phase calibration, 10 may be enough. 
  For more complex ones, be sure to include enough Clean components 
  in the model. More components can be taken at each step, although the 
  better knowledge of phase errors often allows the source to be 
  represented with a smaller number of components after self-calibration 
  than before.

2 SELF_TIMES

    Variable length array specifying the integration time (in seconds)
  for each loop of the self-calibration process.

    At NOEMA, 45 sec is the normal minimum integration time. Depending
  on Signal to Noise, you may need to have this longer, e.g. 120 sec.
  For several loops, start with a longer value, and decrease only
  at the end. 
    
    At ALMA, the minimum integration time is 6 sec. At VLA, this may 
  be as small as 1 sec.
  
    It is recommended to use the same integration time for the last
  two iterations, to simplify the interpretation of the results
  and of the SELFCAL SHOW display.

2 SELF_MINFLUX

    Variable length array specifying the minimum flux density
    (in Jy/beam) to be considered in the Clean image for each loop 
    of the self-calibration process. Note that this is the brightness
    of a pixel, not the flux of a Clean component.

2 SELF_REFANT

    The reference antenna number. If 0, the program will peak the one
    with the shortest average baselines.

2 SELF_FLUX

    Maximum value in the FLUX window. If 0, the FlUX window of Clean is
    not displayed
    
2 SELF_PRECISION

    Tolerance to test for self-calibration convergence. The default
    is 0.01. SELFCAL SUMMARY will write a message when no more selfcal
    iteration improves the solution (noise and dynamic range) at 
    this precision level.

2 SELF_RESTORE

    Use UV_SELF /RESTORE after Cleaning. This avoids signal aliasing
    at image edges, and leads to a better estimate of the noise level.
    It also allows to use smaller images, in practice. 

2 SELF_DISPLAY

    Display Clean image before each calibration loop, and prompt for user
    input. If set, Cleaning at each step will use the number of 
    iterations specified by NITER, while if unset, Cleaning will stop
    at SELF_NITER, saving time.
      Dynamic range progress is only accurate if SELF_DISPLAY is set.

2 SELF_FLAG

    Flag data with no solution, or Keep it as before.

2 SELF_SNR  

    Minimum Signal to Noise ratio to consider a solution to be valid
  for an antenna. 
    
2 SELF_SNOISE

    Noise scaling factor. This should be 1, but some noise estimates
  need corrections. Continuum data from ALMA often requires sqrt(2)
  instead, for example.  Command UV_PREVIEW may help you checking
  the noise scale.
    
2 CLEAN_ARES

    Maximum absolute residual to stop Cleaning
    
2 CLEAN_FRES

    Maximum fractional residual to stop Cleaning

2 CLEAN_NITER

    Maximum number of Clean components. If all of CLEAN_ARES, CLEAN_FRES
  and CLEAN_NITER are 0, Clean stops by checking the stability of the
  cleaned flux over CLEAN_NKEEP iterations.
    
1 ENDOFHELP
end data gag_scratch:selfcal.hlp
!
!! define command selfcal "@ p_selfcal" gag_scratch:selfcal.hlp
