.ti +4
    SELFCAL [?|AMPLI|APPLY|PHASE|SUMMARY|SHOW [Last [First]] [/WIDGET]
  
  Command to perform Self Calibration (even on spectral line data,
and even on Mosaics since Version 3.6 -- Jul-2023). 
The solution is computed, saved and/or applied. SELFCAL encapsulates
the use of commands from the CALIBRATE_\ language to provide a
more user-friendly approach to self-calibration.

  The arguments control the action.
.nf  

    SELFCAL ?        Lists the self calibration parameters
    SELFCAL AMPLI    Compute an Amplitude only self calibration
    SELFCAL APPLY    Apply the computed solution
    SELFCAL CHECK    Check if Self-Cal makes sense
    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
.fi                    
.ti -4
2 /WIDGET
.ti +4
    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.
.nf
     AMPLI      Perform an Amplitude only self calibration
     PHASE      Perform a Phase only self calibration
     CHECK      Check if it makes sense
     Continue   Continue execution when the script is in Pause
     APPLY      Apply the solution
     FLAG       Flag data according to self calibration 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
.fi
.ti -4
2 Arguments:
.ti +4
  The arguments control the action.
.nf  
    SELFCAL ?        Lists the self calibration parameters
    SELFCAL AMPLI    Perform an Amplitude only self calibration
    SELFCAL APPLY    Apply the solution
    SELFCAL CHECK    Check if Self-Cal makes sense
    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
.fi
.ti -4
2 AMPLITUDE
.ti +4
    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.
  
.ti -4
2 APPLY
.ti +4
    SELFCAL APPLY [Type [Gain]]
    
Apply the self calibration solution. This is done only if the return 
status from the previous computation, SELF__STATUS, is greater than 0.  
SELFCAL APPLY automatically saves the parameters and results in the 
"selfcal-AMPLI.last" or "selfcal-PHASE.last" file, depending on the
Type of solution applied.
  
  Type is the type of solution to apply. The default is 'SELF__MODE', i.e.
PHASE or AMPLI depending on the last type of self-calibration computed.
Type can also take the DELAY value, where the "phase" corrections
are interpreted as atmospheric path changes and scale as Frequency.

  Gain is an optional gain factor (default is 1.) on the correction.

.ti -4
2 CHECK
.ti +4
    SELFCAL CHECK
    
Check whether self-calibration is possible, based on a quick estimate
of S/N, and returns a minimum recommended integration time. Actual
performance of self-calibration may however significantly depends
on the source structure and antenna configuration.

.ti -4
2 FLAG
.ti +4 
    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). The mode (AMPLI, PHASE
or DELAY) is taken from the default mode 'SELF__MODE'.
No correction is applied however.
    
    With the Widget interface, no Threshold can be specified.

.ti -4 
2 INPUT
.ti +4
    SELFCAL INPUT  or SELFCAL ?
    
Display SELFCAL control variables
    
.ti -4
2 PHASE
.ti +4
    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.
  
.ti -4
2 SAVE
.ti +4
    SELFCAL SAVE
    
    Save the parameters and results in the "selfcal.last" file.

.ti -4
2 SHOW
.ti +4
    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.

The displayed ranges are controlled by SELF__ARANGE[2] (limits
of Amplitude gain), SELF__PRANGE[2] (limits of Phase correction)
and SELF__TRANGE[2] (limits for time axis).
  
.ti -4
2 SUMMARY
.ti +4
    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.

.ti -4
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:    
.nf
    SELF__APPLIED
      Indicates whether the solution has been applied      
    SELF__DYNAMIC[Self__Loop+1]
      The dynamic range at each iteration
    SELF__LOOP
      Number of Loops
    SELF__RMSCLEAN[Self__Loop+1]
      The rms noise at each iteration
    SELF__STATUS 
      Indicates if a solution has been computed    
.fi
.ti -4
2 SELF__APPLIED

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

.ti -4
2 SELF__DYNAMIC

SELF__DYNAMIC is a variable length array of size Self__Loop+1, 
containing the dynamic range at each iteration.
 
.ti -4 
2 SELF__LOOP

Number of self-iteration loops. It is a ReadOnly variable that is 
automatically computed from the size of the SELF__TIMES, SELF__NITER 
and SELF__MINFLUX arrays.  

  These variable length arrays can be resized using the LET /RESIZE
command. For example
.br
    LET SELF__TIMES 40 20 10 /RESIZE
.br
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. 

Constant arrays are assumed of arbitrary 
length in this determination. If all 3 arrays have constant values, 
SELF__TIMES determines the number of loops. 
    
.ti -4
2 SELF__RMSCLEAN

SELF__RMSCLEAN is a variable length array of size Self__Loop+1, 
containing the Clean map rms noise at each iteration.

.ti -4
2 SELF__STATUS

Variable SELF__STATUS indicates if a solution has been computed
.nf
      0 no solution
      +/- 1   Phase solution
      +/- 2   Gain solution
    >0 means a good solution, <0 a poor one.
.fi

.ti -4
2 Variables:

The 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. The size of these arrays define the 
number of loops.  
    
See HELP SELFCAL SELF__LOOP to find out how to control the number of loops.
    
.ti -4
2 SELF__ARANGE
.ti +4
    SELF__ARANGE[2]
    
  Displayed amplitude range, two numbers bracketing 1.0 when Amplitude calibration
  has been made correctly.
  
  
.ti -4
2 SELF__CHANNEL
.ti +4
    SELF__CHANNEL[2]

First and last channel to define the range to compute the UV table for 
the self-calibration solution. 0 0 means all channels are averaged to compute 
the "continuum" image. CHannels filtered out by UV__FILTER are
ignored.


.ti -4
2 SELF__COLOR
.ti +4
    SELF__COLOR
    
Controls the LUT color range at each self-calibration cycle if non Zero.
Since the dynamic range evolves, this can be a useful way to highlight
the gain. If non Zero, SELF__COLOR is passed as argument to a COLOR
command executed at each cycle after display. 

Pratical values for SELF__COLOR are -8 ("bright" version, highlights the 
noise level) or +8 ("dark" version, hides the noise), but lower 
absolute values may be needed for higher dynamic ranges.

See HELP COLOR for details.

.ti -4
2 SELF__DISPLAY

If YES, display Clean image before each calibration loop, and prompt 
for user input. If YES, Cleaning at each step will use the number of 
iterations specified by NITER, while if set to NO, Cleaning will stop at 
SELF__NITER, saving time.
      
The dynamic range progress report is accurate only if SELF__DISPLAY is set.


.ti -4
2 SELF__FLAG

    If SELF__FLAG is YES, SELFCAL will flag data with no solution. If NO,
it will keep the data as it was before.

.ti -4
2 SELF__FLUX

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

.ti -4
2 SELF__GAIN

    Phase calibration convergence factor, in range ]0-1]. At each iteration
the applied phase is SELF__GAIN times the derived phase. Default is 1.
Smaller values will slow down convergence, but may stabilize the process
if the initial model is poor. Do not make it smaller than about 0.7, however.

  This is only used for PHASE Self-Calibration.

.ti -4
2 SELF__HARD
.ti +4
    
Indicates whether a Hardcopy (EPS or PDF file) of the SELFCAL SHOW
command is kept or not. 

.ti -4
2 SELF__ITER
    
Internal variable controlling the number of Clean components during
an iteration. It is derived from SELF__NITER[Iteration].

.ti -4
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.

This variable length array can be resized using the LET /RESIZE
command. For example
.nf
    LET SELF__MINFLUX 0.001 0 0  /RESIZE
.fi
will lead 3 self-calibration loops (if SELF__TIMES and SELF__NITER 
are also of size 3) selecting on regions brighter than 1 mJy/beam
in the first one, and all regions in the last 2 ones.

.ti -4
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.
The default is a reasonably good compromise, although faster convergence
may be obtained with smaller number of components.

This variable length array can be resized using the LET /RESIZE
command. For example
.nf
    LET SELF__NITER 10 0 0 /RESIZE
.fi
will lead to 3 self-calibration loops (if SELF__TIMES and SELF__MINFLUX
are also of size 3), the first one selecting only 10 components,
the two others all components.
  
.ti -4
2 SELF__PRANGE
.ti +4
    SELF__PRANGE[2]
    
  Displayed Phase range (in degrees), two numbers bracketing 0.0 when 
  Phase calibration has been made correctly. If 0, SELFCAL will
  make an educated guess.

.ti -4
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.

.ti -4
2 SELF__REFANT

The reference antenna number. This is used mostly for debug.
The default is 0, meaning that the program will peak the 
antenna with the shortest average baselines.
    
.ti -4
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,

.ti -4
2 SELF__SNAME

Name of Self-Calibration intermediate file. Being used internally only, it is
typically set as gag__scratch:test unless you want to keep the file
for debugging or other purpose.

.ti -4
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.

.ti -4 
2 SELF__SNR  

Minimum Signal to Noise ratio on the antenna gain to consider a 
solution to be valid for an antenna. 6 is a good value, 3 a lower 
limit. Beware that this SNR makes sense only if the a priori estimate 
of the noise from the UV weights is correct: see SELF__SNOISE.

In practice, it is the product SELF__SNR * SELF__NOISE that must be
adjusted correctly.
    
.ti -4
2 SELF__THRESHOLD

Minimum (global) Signal to Noise required to attempt self-calibration.
If this is 0, it is set to the inverse of the strongest negative beam
sidelobe, as the dynamic range can hardly be improved in other cases.

.ti -4
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 usually 6 sec, 2 sec
on long baselines. 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.

This variable length array can be resized using the LET /RESIZE
command. For example
.nf
    LET SELF__TIMES 180 90 45 /RESIZE
.fi
will lead 3 self-calibration loops (if SELF__TIMES and SELF__MINFLUX
are also of size 3) with decreasing integration times.

.ti -4
2 SELF__TRANGE
.ti +4
    SELF__TRANGE[2]
    
  Displayed Time range (in seconds, sorry...). for SELFCAL SHOW.
Normally 0 to see all observing times, but you may adjust it to zoom on a region.


.ti -4 
2 CLEAN__ARES

    Maximum absolute residual to stop Cleaning
    
.ti -4 
2 CLEAN__FRES

    Maximum fractional residual to stop Cleaning

.ti -4 
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. See HELP CLEAN for details. 
    
