Starting iclean

iclean is interactive clean: it runs CASA’s image reconstruction, tclean, one cycle at a time, and shows the residual image, the mask and the convergence in a window where you can change the mask and the iteration control between cycles.

iclean takes tclean’s parameters, and its documentation is tclean’s:

iclean · from the Python source: _iclean

tclean — Radio Interferometric Image Reconstruction

Form images from visibilities and reconstruct a sky model. This task handles continuum images and spectral line cubes, supports outlier fields, contains standard clean based algorithms along with algorithms for multi-scale and wideband image reconstruction, widefield imaging correcting for the w-term, full primary-beam imaging and joint mosaic imaging (with heterogeneous array support for ALMA).

Before you start

  • An environment with cubevis[iclean], which brings in CASA6’s casatasks and casatools, and arcae for reading the images: see Installing.

  • A calibrated measurement set.

Starting

iclean is called as tclean is. vis and imagename are required:

from cubevis import iclean

iclean( vis='refim_twopoints_twochan.ms', imagename='test',
        imsize=100, cell='8.0arcsec',
        phasecenter="J2000 19:59:28.500 +40.44.01.50",
        niter=50, cycleniter=10, deconvolver='hogbom',
        specmode='mfs', spw='0:0' )

The call shows the window in your web browser and runs until you stop interactive clean there, then returns its result. The images are written as tclean writes them, named after imagename.

The measurement set of this example can be downloaded.

Note

A screenshot of the window, and a tour of its controls, will be added here when the layout is final.

iclean parameters · from the Python source: _iclean

vis = ''

Name(s) of input visibility file(s)

more
default: none;
example: vis='ngc5921.ms'
         vis=['ngc5921a.ms','ngc5921b.ms']; multiple MSs
imagename = ''

Pre-name of output images

more
example : imagename='try'

Output images will be (a subset of) :

try.psf           - Point Spread Function (PSF).
try.residual      - Residual image.
try.image         - Restored image.
try.model         - Model image (contains only flux components).
try.sumwt         - Single pixel image containing sum-of-weights.
                          (for natural weighting, sensitivity=1/sqrt(sumwt)).
try.pb            - Primary Beam (PB) model (values depend on the gridder used).

A-projection algorithms (gridder=mosaic,awproject, awp2) will
compute the following images too.

try.weight        - FT of gridded weights or the
                          un-normalized sum of PB-square (for all pointings).
                          Here, PB = sqrt(weight) normalized to a maximum of 1.0.

For multi-term wideband imaging, all relevant images above will
have additional .tt0,.tt1, etc suffixes to indicate Taylor terms,
plus the following extra output images.
try.alpha            - spectral index.
try.alpha.error   - estimate of error on spectral index.
try.beta              - spectral curvature (if nterms \> 2).

Tip : Include a directory name in 'imagename' for all
        output images to be sent there instead of the
        current working directory : imagename='mydir/try'.

Tip : Restarting an imaging run without changing 'imagename'
        implies continuation from the existing model image on disk.
         - If 'startmodel' was initially specified it needs to be set to ""
           for the restart run (or tclean will exit with an error message).
         - By default, the residual image and psf will be recomputed
           but if no changes were made to relevant parameters between
           the runs, set calcres=False, calcpsf=False to resume directly from
           the minor cycle without the (unnecessary) first major cycle.
         To automatically change 'imagename' with a numerical
         increment, set restart=False (see tclean docs for 'restart').

 Note : All imaging runs will by default produce restored images.
           For a niter=0 run, this will be redundant and can optionally
           be turned off via the 'restoration=T/F' parameter.

In a Jupyter notebook

iclean.notebook(...) takes the same parameters and shows the window in the notebook cell. It needs the notebook extra as well: pip install "cubevis[iclean,notebook]".

Data on another computer

When the data is on another computer, name a kernel that was set up there and give vis and imagename as they are on that computer:

iclean( vis="twhya.ms", imagename="twhya", ..., kernel_name="cvpost106-iclean" )

tclean and the image access then run on that computer and only the window runs on yours, which needs no CASA. Setting up the kernel, and what to know when using one, is described in Setting up remote execution.

iclean parameters · from the Python source: _iclean

kernel_name = None

Jupyter kernel to run tclean and the image access on

more
default: None; everything runs in this Python.
With a kernel name, tclean runs and the images are
read and written on the kernel's computer, and only
the window runs here.  vis and imagename are then
paths on that computer, relative to the kernel's
working directory, and this computer needs no CASA.
Kernels are set up with: python -m cubevis.setup
example: kernel_name='cvpost106-iclean'
iclean_backend = 'PROD'

Implementation of the clean cycle to use

more
default: 'PROD', the gclean of the installed casatasks.
Any other value NAME selects a module _gclean_NAME:
an alternate implementation, or a stub for testing.

The parameters used most

These are tclean’s descriptions. Each opens to the full text with more.

The image

iclean parameters · from the Python source: _iclean

imsize = [100]

Number of pixels

more
example:

imsize = [350,250].
imsize = 500 is equivalent to [500,500].

To take proper advantage of internal optimized FFT routines, the
number of pixels must be even and factorizable by 2,3,5 only.
To find the nearest optimal imsize to that desired by the user, please use the following tool method:

from casatools import synthesisutils
su = synthesisutils()
su.getOptimumSize(345)
Output :  360
cell = []

Cell size

more
example: cell=['0.5arcsec,'0.5arcsec'] or
cell=['1arcmin', '1arcmin'].
cell = '1arcsec' is equivalent to ['1arcsec','1arcsec'].
phasecenter = ''

Phase center of the image (string or field id); if the phasecenter is the name known major solar system object (‘MERCURY’, ‘VENUS’, ‘MARS’, ‘JUPITER’, ‘SATURN’, ‘URANUS’, ‘NEPTUNE’, ‘PLUTO’, ‘SUN’, ‘MOON’) or is an ephemerides table then that source is tracked and the background sources get smeared. There is a special case, when phasecenter=’TRACKFIELD’, which will use the ephemerides or polynomial phasecenter in the FIELD table of the MS’s as the source center to track.

more
     Note : If unspecified, tclean will use the phase-center from the first data field of the MS (or list of MSs) selected for imaging.

                       example: phasecenter='6'.
phasecenter='J2000 19h30m00 -40d00m00'.
phasecenter='J2000 292.5deg  -40.0deg'.
phasecenter='J2000 5.105rad  -0.698rad'.
phasecenter='ICRS 13:05:27.2780 -049.28.04.458'.
phasecenter='myComet_ephem.tab'.
phasecenter='MOON'.
phasecenter='TRACKFIELD'.
stokes = 'I'

Stokes Planes to make

more
default='I'; example: stokes='IQUV';
  Options: 'I','Q','U','V','IV','QU','IQ','UV','IQUV','RR','LL','XX','YY','RRLL','XXYY','pseudoI'

              Note : Due to current internal code constraints, if any correlation pair
                         is flagged, by default, no data for that row in the MS will be used.
                         So, in an MS with XX,YY, if only YY is flagged, neither a
                         Stokes I image nor an XX image can be made from those data points.
                         In such a situation, please split out only the unflagged correlation into
                         a separate MS, or use the option 'pseudoI'.

              Note : The 'pseudoI' option is a partial solution, allowing Stokes I imaging
                     when either of the parallel-hand correlations are unflagged.

              The remaining constraints shall be removed (where logical) in a future release.
specmode = 'mfs'

Spectral definition mode (mfs,cube,cubedata, cubesource, mvc)

more
specmode='mfs' : Continuum imaging with only one output image channel.
                               (mode='cont' can also be used here)

specmode='cube' : Spectral line imaging with one or more channels.
                               Parameters start, width,and nchan define the spectral
                              coordinate system and can be specified either in terms
                              of channel numbers, frequency or velocity in whatever
                              spectral frame is specified in 'outframe'.
                              All internal and output images are made with outframe as the
                              base spectral frame. However imaging code internally uses the fixed
                              spectral frame, LSRK for automatic internal software
                              Doppler correction, so that a spectral line observed over an
                              extended time range will line up appropriately.
                              Therefore the output images have additional spectral frame conversion
                               layer in LSRK on the top the base frame.




 specmode='cubedata' : Spectral line imaging with one or more channels.
                                 There is no internal software Doppler correction, so
                                 a spectral line observed over an extended time range
                                 may be smeared out in frequency. There is strictly
                                 no valid spectral frame with which to associate with the
                                 output images, thus the image spectral  frame will
                                 be labelled  "Undefined".


 specmode='cubesource': Spectral line imaging while
                                 tracking moving source (near field or solar system
                                 objects). The velocity of the source is accounted
                                 and the frequency reported is in the source frame.
                                 As there is no "SOURCE" frame defined in CASA,
                                 the frame in the image will be labelled "REST" (but do note the
                                 velocity of a given line reported may be different from the rest frame
                                 velocity if the emission region is moving w.r.t the systemic
                                 velocity frame of the source).

 specmode='mvc' : Multiterm continuum imaging with cube major cycles.
                                 This mode requires deconvolver='mtmfs' with nterms>1
                                 and user-set choices of 'reffreq' and 'nchan'.

                                 The output images and minor cycle are similar to specmode='mfs'
                                 with deconvolver='mtmfs', but the major cycles are done in
                                 cube mode (and require a setting of 'reffreq' and 'nchan').
                                 By default, frequency-dependent primary beam correction is
                                 applied to each channel, before being combined across frequency
                                 to make the inputs to the 'mtmfs' deconvolver.  This results in
                                 implicit wideband pb-correction, with the deconvolver seeing only
                                 the sky spectral structure.

                                 Note : There is currently no option to turn off wideband pb correction
                                 as part of the flat-sky normalization between the major and minor cycles.
                                 Therefore, 'mvc' with the 'standard' and 'wproject' gridders will also apply
                                 pblimits per channel, masking all regions outside of pblimit.
                                 An option to retain sources outside the pblimit will be added in a future release.

                                 Note : Below is some guidance for choosing 'nchan' and 'reffreq' :

                                 The cube produced by the major cycle is used in a linear least square fits for Taylor
                                 polynomials per pixel. Therefore, one only needs as many channels in the cube, as
                                 required for an accurate polynomial fit for sources that have the strongest
                                 spectral structure.

                                 In general, 'nchan' needs to be greater than or equal to 'nterms', and the
                                 frequency range selected by the data will be evenly split into nchan channels.
                                 For a low-order polynomial fit, only a small number (around 10)
                                 channels are typically needed (for VLA/ALMA bandwidth ratios).
                                 'nchan=-1' applies a heuristic that results in a default of 10 cube channels
                                 for a 2:1 bandwidth ratio.

                                 nchan = MAX( bandwidth/(0.1*startfreq) ,  nterms+1 )

                                 Note: When running in parallel, the nchan selected may limit the speedup if it
                                 is smaller than the number of processes used.

                                 The 'reffreq' is the reference frequency used for the Taylor polynomial expansion.
                                 By default, in specmode='mvc', reffreq is set to the middle of the selected
                                 frequency range.
deconvolver = 'hogbom'

Name of minor cycle algorithm (hogbom,clark,multiscale,mtmfs,mem,clarkstokes,asp)

more
Each of the following algorithms operate on residual images and PSFs
from the gridder and produce output model and restored images.
Minor cycles stop and a major cycle is triggered when cyclethreshold
or cycleniter are reached. For all methods, components are picked from
the entire extent of the image or (if specified) within a mask.

hogbom : An adapted version of Hogbom Clean [Hogbom, 1974].
                - Find the location of the peak residual.
                - Add this delta function component to the model image.
                - Subtract a scaled and shifted PSF of the same size as the image
                  from regions of the residual image where the two overlap.
                - Repeat.

clark : An adapted version of Clark Clean [Clark, 1980].
                - Find the location of max(I^2+Q^2+U^2+V^2).
                - Add delta functions to each stokes plane of the model image.
                - Subtract a scaled and shifted PSF within a small patch size
                  from regions of the residual image where the two overlap.
                - After several iterations trigger a Clark major cycle to subtract
                  components from the visibility domain, but without de-gridding.
                - Repeat.

               ( Note : 'clark' maps to imagermode='' in the old clean task.
                            'clark_exp' is another implementation that maps to
                             imagermode='mosaic' or 'csclean' in the old clean task
                             but the behavior is not identical. For now, please
                             use deconvolver='hogbom' if you encounter problems. )

clarkstokes : Clark Clean operating separately per Stokes plane.

           (Note : 'clarkstokes_exp' is an alternate version. See above.)

multiscale : MultiScale Clean [Cornwell, 2008].
                - Smooth the residual image to multiple scale sizes.
                - Find the location and scale at which the peak occurs.
                - Add this multiscale component to the model image.
                - Subtract a scaled,smoothed,shifted PSF (within a small
                  patch size per scale) from all residual images.
                - Repeat from step 2.

mtmfs : Multi-term (Multi Scale) Multi-Frequency Synthesis [Rau and Cornwell, 2011].
                - Smooth each Taylor residual image to multiple scale sizes.
                - Solve a NTxNT system of equations per scale size to compute
                  Taylor coefficients for components at all locations.
                - Compute gradient chi-square and pick the Taylor coefficients
                   and scale size at the location with maximum reduction in
                   chi-square.
                - Add multi-scale components to each Taylor-coefficient
                  model image.
                - Subtract scaled,smoothed,shifted PSF (within a small patch size
                  per scale) from all smoothed Taylor residual images.
                - Repeat from step 2.


mem : Maximum Entropy Method [Cornwell and Evans, 1985].
                - Iteratively solve for values at all individual pixels via the
                  MEM method. It minimizes an objective function of
                   chi-square plus entropy (here, a measure of difference
                  between the current model and a flat prior model).

                  (Note : This MEM implementation is not very robust.
                               Improvements will be made in the future.)

asp : Adaptive Scale Pixel algorithm [Bhatnagar and Cornwell, 2004].
                - Define a set of initial scales defined as 0, W, 2W 4W and 8W.
                  where W is a 2D Gaussian fitting width to the PSF.
                - Smooth the residual image by a Gaussian beam at initial scales.
                - Search for the global peak (F) among these smoothed residual images.
                - form an active Aspen set: amplitude(F), amplitude location(x,y).
                - Optimize the Aspen set by minimizing the objective function RI-Aspen*PSF,
                  where RI is the residual image and * is the convulition operation.
                - Compute the model image and update the residual image
                - Repeat from step 2
weighting = 'natural'

Weighting scheme (natural,uniform,briggs,superuniform,radial, briggsabs, briggsbwtaper).

more
        During gridding of the dirty or residual image, each visibility value is
        multiplied by a weight before it is accumulated on the uv-grid.
        The PSF's uv-grid is generated by gridding only the weights (weightgrid).

        weighting='natural' : Gridding weights are identical to the data weights
                                          from the MS. For visibilities with similar data weights,
                                          the weightgrid will follow the sample density
                                          pattern on the uv-plane. This weighting scheme
                                          provides the maximum imaging sensitivity at the
                                          expense of a PSF with possibly wider main lobes and high sidelobes.
                                          It is most appropriate for detection experiments
                                          where sensitivity is most important.

        weighting='uniform' : Gridding weights per visibility data point are the
                                           original data weights divided by the total weight of
                                           all data points that map to the same uv grid cell :
                                           ' data_weight / total_wt_per_cell '.

                                           The weightgrid is as close to flat as possible resulting
                                           in a PSF with a narrow main lobe and suppressed
                                           sidelobes. However, since heavily sampled areas of
                                           the uv-plane get down-weighted, the imaging
                                           sensitivity is not as high as with natural weighting.
                                           It is most appropriate for imaging experiments where
                                           a well behaved PSF can help the reconstruction.

        weighting='briggs' :  Gridding weights per visibility data point are given by
                                          'data_weight / ( A \* total_wt_per_cell + B ) ' where
                                          A and B vary according to the 'robust' parameter.

                                          robust = -2.0 maps to A=1,B=0 or uniform weighting.
                                          robust = +2.0 maps to natural weighting.
                                          (robust=0.5 is equivalent to robust=0.0 in AIPS IMAGR.)

                                          Robust/Briggs weighting generates a PSF that can
                                          vary smoothly between 'natural' and 'uniform' and
                                          allow customized trade-offs between PSF shape and
                                          imaging sensitivity.
         weighting='briggsabs' : Experimental option.
                                          Same as Briggs except the formula is different A=
                                          robust\*robust and B is dependent on the
                                          noise per visibility estimated. Giving noise='0Jy'
                                          is a not a reasonable option.
                                          In this mode (or formula)  robust values
                                          from -2.0 to 0.0 only make sense (2.0 and
                                          -2.0 will get the same weighting)

        weighting='superuniform' : This is similar to uniform weighting except that
                                                     the total_wt_per_cell is replaced by the
                                                     total_wt_within_NxN_cells around the uv cell of
                                                     interest. N=7 is the default (when the
                                                                   parameter 'npixels' is set to 0 with 'superuniform')

                                                    This method tends to give a PSF with inner
                                                    sidelobes that are suppressed as in uniform
                                                    weighting but with far-out sidelobes closer to
                                                    natural weighting. The peak sensitivity is also
                                                    closer to natural weighting.

        weighting='radial' : Gridding weights are given by ' data_weight \* uvdistance '
                                       This method approximately minimizes rms sidelobes
                                       for an east-west synthesis array.

        weighting='briggsbwtaper' : A modified version of Briggs weighting for cubes where an inverse uv taper,
                                          which is proportional to the fractional bandwidth of the entire cube,
                                          is applied per channel. The objective is to modify cube (perchanweightdensity = True)
                                          imaging weights to have a similar density to that of the continuum imaging weights.
                                          This is currently an experimental weighting scheme being developed for ALMA.

For more details on weighting please see Chapter3
of Dan Briggs' thesis (http://www.aoc.nrao.edu/dissertations/dbriggs)

Iteration control

The values given here are what the window’s controls start with; they can be changed between cycles.

iclean parameters · from the Python source: _iclean

niter = 0

Maximum number of iterations.

more
A stopping criterion based on total iteration count.
Currently the parameter type is defined as an integer therefore the integer value
larger than 2147483647 will not be set properly as it causes an overflow.

Iterations are typically defined as the selecting one flux component
and partially subtracting it out from the residual image.

niter=0 : Do only the initial major cycle (make dirty image, psf, pb, etc).

niter larger than zero : Run major and minor cycles.

Note : Global stopping criteria vs major-cycle triggers.

           In addition to global stopping criteria, the following rules are
           used to determine when to terminate a set of minor cycle iterations
           and trigger major cycles [derived from Cotton-Schwab Clean, 1984].

           'cycleniter' : controls the maximum number of iterations per image
                               plane before triggering a major cycle.
           'cyclethreshold' : Automatically computed threshold related to the
                                       max sidelobe level of the PSF and peak residual.
            Divergence, detected as an increase of 10% in peak residual from the
            minimum so far (during minor cycle iterations).

            The first criterion to be satisfied takes precedence.

Note :  Iteration counts for cubes or multi-field images :
            For images with multiple planes (or image fields) on which the
            deconvolver operates in sequence, iterations are counted across
            all planes (or image fields). The iteration count is compared with
            'niter' only after all channels/planes/fields have completed their
            minor cycles and exited either due to 'cycleniter' or 'cyclethreshold'.
            Therefore, the actual number of iterations reported in the logger
            can sometimes be larger than the user specified value in 'niter'.
            For example, with niter=100, cycleniter=20,nchan=10,threshold=0,
            a total of 200 iterations will be done in the first set of minor cycles
            before the total is compared with niter=100 and it exits.

 Note : Additional global stopping criteria include:
           - no change in peak residual across two major cycles.
           - a 50% or more increase in peak residual across one major cycle.
cycleniter = -1

Maximum number of minor-cycle iterations (per plane) before triggering

more
a major cycle.

For example, for a single plane image, if niter=100 and cycleniter=20,
there will be 5 major cycles after the initial one (assuming there is no
threshold based stopping criterion). At each major cycle boundary, if
the number of iterations left over (to reach niter) is less than cycleniter,
it is set to the difference.

Note : cycleniter applies per image plane, even if cycleniter x nplanes
           gives a total number of iterations greater than 'niter'. This is to
           preserve consistency across image planes within one set of minor
           cycle iterations.
threshold = 0.0

Stopping threshold (number in units of Jy, or string).

more
A global stopping threshold that the peak residual (within clean mask)
across all image planes is compared to.

threshold = 0.005  : 5mJy
threshold = '5.0mJy'

Note : A 'cyclethreshold' is internally computed and used as a major cycle
           trigger. It is related to what fraction of the PSF can be reliably
           used during minor cycle updates of the residual image. By default
           the minor cycle iterations terminate once the peak residual reaches
           the first sidelobe level of the brightest source.

           'cyclethreshold' is computed as follows using the settings in
            parameters 'cyclefactor','minpsffraction','maxpsffraction','threshold' :

          psf_fraction = max_psf_sidelobe_level \* 'cyclefactor'
          psf_fraction = max(psf_fraction, 'minpsffraction');
          psf_fraction = min(psf_fraction, 'maxpsffraction');
          cyclethreshold = peak_residual \* psf_fraction
          cyclethreshold = max( cyclethreshold, 'threshold' )

          If nsigma is set (>0.0), the N-sigma threshold is calculated (see
          the description under nsigma), then cyclethreshold is further modified as,

          cyclethreshold = max( cyclethreshold, nsgima_threshold ).


          'cyclethreshold' is made visible and editable only in the
          interactive GUI when tclean is run with interactive=True.
nsigma = 0.0

Multiplicative factor for rms-based threshold stopping.

more
N-sigma threshold is calculated as nsigma \* rms value per image plane determined
from a robust statistics. For nsigma > 0.0, in a minor cycle, a maximum of the two values,
the N-sigma threshold and cyclethreshold, is used to trigger a major cycle
(see also the descreption under 'threshold').
Set nsigma=0.0 to preserve the previous tclean behavior without this feature.
The top level parameter, fastnoise is relevant for the rms noise calculation which is used
to determine the threshold.

                      The parameter 'nsigma' may be an int, float, or a double.
gain = 0.1

Loop gain.

more
Fraction of the source flux to subtract out of the residual image
for the CLEAN algorithm and its variants.

A low value (0.2 or less) is recommended when the sky brightness
distribution is not well represented by the basis functions used by
the chosen deconvolution algorithm. A higher value can be tried when
there is a good match between the true sky brightness structure and
the basis function shapes.  For example, for extended emission,
multiscale clean with an appropriate set of scale sizes will tolerate
a higher loop gain than Clark clean.
nmajor = -1

The nmajor parameter limits the number of minor and major cycle sets

more
that tclean executes. It is defined as the number of major cycles after the
initial set of minor cycle iterations. In other words, the count of nmajor does
not include the initial residual calculation that occurs when calcres=True.

A setting of nmajor=-1 implies no limit (default -1).
A setting of nmajor=0 implies nothing other than the initial residual calculation
A setting of nmajor>0 imples that nmajor sets of minor and major cycles will
be done in addition to the initial residual calculation.

If the major cycle limit is reached, stopcode 9 will be returned. Other stopping
criteria (such as threshold) could cause tclean to stop in fewer than this
number of major cycles. If tclean reaches another stopping criteria, first
or at the same time as nmajor, then that stopcode will be returned instead.

Note however that major cycle ids in the log messages as well as in the return
dictionary do begin with 1 for the initial residual calculation, when it exists.

Example 1 : A tclean run with 'nmajor=5' and 'calcres=True' will iterate for
5 major cycles (not counting the initial residual calculation). But, the return
dictionary will show 'nmajordone:6'.  If 'calcres=False', then the return
dictionary will show 'nmajordone:5'.

Example 2 : For both the following cases, there will be a printout in the logs
"Running Major Cycle 1" and the return value will include "nmajordone: 1",
however there is a difference in the purpose of the major cycle and the
number of minor cycles executed:
    Case 1; nmajor=0, calcres=True:  The major cycle done is for the creation
                of the residual, and no minor cycles are executed.
    Case 2; nmajor=1, calcres=False: The major cycle is done as part of the
                major/minor cycle loop, and 1 minor cycle will be executed.

Masks

iclean parameters · from the Python source: _iclean

usemask = 'user'

Type of mask(s) to be used for deconvolution.

more
user: (default) mask image(s) or user specified region file(s) or string CRTF expression(s).
  subparameters: mask, pbmask.
pb: primary beam mask.
  subparameter: pbmask.

    Example: usemask="pb", pbmask=0.2.
                      Construct a mask at the 0.2 pb gain level.
                      (Currently, this option will work only with

                      gridders that produce .pb (i.e. mosaic, awp2 and awproject)
                      or if an externally produced .pb image exists on disk)


auto-multithresh : auto-masking by multiple thresholds for deconvolution.
   subparameters : sidelobethreshold, noisethreshold, lownoisethreshold, negativethrehsold,  smoothfactor,
                   minbeamfrac, cutthreshold, pbmask, growiterations, dogrowprune, minpercentchange, verbose.
   Additional top level parameter relevant to auto-multithresh: fastnoise.

   if pbmask is >0.0, the region outside the specified pb gain level is excluded from
   image statistics in determination of the threshold.




Note: By default the intermediate mask generated by automask at each deconvolution cycle
      is over-written in the next cycle but one can save them by setting
      the environment variable, SAVE_ALL_AUTOMASKS="true".
      (e.g. in the CASA prompt, os.environ['SAVE_ALL_AUTOMASKS']="true" )
      The saved CASA mask image name will be imagename.mask.autothresh#, where
      # is the iteration cycle number.
mask = ''

Mask (a list of image name(s) or region file(s) or region string(s).

more
The name of a CASA image or region file or region string that specifies
a 1/0 mask to be used for deconvolution. Only locations with value 1 will
be considered for the centers of flux components in the minor cycle.
If regions specified fall completely outside of the image, tclean will throw an error.

Manual mask options/examples :

mask='xxx.mask'  : Use this CASA image named xxx.mask and containing
                                ones and zeros as the mask.
                                If the mask is only different in spatial coordinates from what is being made
                                it will be resampled to the target coordinate system before being used.
                                The mask has to have the same shape in velocity and Stokes planes
                                as the output image. Exceptions are single velocity and/or single
                                Stokes plane masks. They will be expanded to cover all velocity and/or
                                Stokes planes of the output cube.

                                [ Note : If an error occurs during image resampling or
                                            if the expected mask does not appear, please try
                                            using tasks 'imregrid' or 'makemask' to resample
                                            the mask image onto a CASA image with the target
                                            shape and coordinates and supply it via the 'mask'
                                            parameter. ]


mask='xxx.crtf' : A text file with region strings and the following on the first line
                           ( #CRTFv0 CASA Region Text Format version 0 )
                           This is the format of a file created via the viewer's region
                           tool when saved in CASA region file format.

mask='circle[[40pix,40pix],10pix]'  : A CASA region string.

mask=['xxx.mask','xxx.crtf', 'circle[[40pix,40pix],10pix]']  : a list of masks.





Note : Mask images for deconvolution must contain 1 or 0 in each pixel.
           Such a mask is different from an internal T/F mask that can be
           held within each CASA image. These two types of masks are not
           automatically interchangeable, so please use the makemask task
           to copy between them if you need to construct a 1/0 based mask
           from a T/F one.

Note : Work is in progress to generate more flexible masking options and
           enable more controls.

Every parameter is listed in iclean parameters. The task pages of tclean in CASA Docs describe the algorithms behind them.