The tclean task forms images from visibilities and reconstructs a sky model.

tclean handles continuum images and spectral line cubes, supports outlier fields, contains point-source CLEAN based algorithms as well as options 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). Parallelization of the major cycle is also available.

Image reconstruction in CASA typically comprises an outer loop of major cycles and an inner loop of minor cycles. The major cycle implements transforms between the data and image domains and the minor cycle operates purely in the image domain. Together, they implement an iterative weighted $\chi^2$ minimization that solves the measurement equation. Minor cycle algorithms can have their own (different) optimization schemes and the imaging framework and task interface allow for considerable freedom in choosing options separately for each step of the process.


Operating Modes

The tclean task can be configured to perform either full iterative image reconstructions (see synthesis-imaging) to run each step separately. Parameters for data selection, image definition, gridding and deconvolution algorithms, restoration and primary beam setup are shared between all operational modes.

Examples are provided for each of the following usage modes.

Imaging and Deconvolution Iterations:

Construct the PSF and Dirty image and apply a deconvolution algorithm to reconstruct a Sky model. A series of major and minor cycle iterations are usually performed. The output sky model is then restored and optionally PB-corrected. The Sky model can optionally be saved in the MS during the last major cycle.

Make PSF and PB:

Make only the Point Spread Function and the Primary Beam, along with auxiliary weight images (a single pixel image containing sum-of-weight per plane, and (for mosaic and aprojection) a weight image containing the weighted sum of PB square).

Make a Residual/Dirty Image:

Make a dirty image, or a new residual image using an existing or specified model image. This step requires the presence of the sum-of-weight and weight images (for normalization) constructed during the PSF and PB generation step.

Model Prediction:

Save a sky model in the MeasurementSet for later use in calibration (virtual model or by actual prediction into a model column).


Divide out the Primary Beam from the restored Sky image.


The pblimit is a parameter used to define the value of the antenna primary beam gain, below which wide-field gridding algorithms such as 'mosaic' and 'awproject' will not apply normalization (and will therefore set to zero).  For gridder='standard', there is no pb-based normalization during gridding and so the value of this parameter is ignored.

The sign of the pblimit parameter is used for a different purpose. If positive, it defines a T/F pixel mask that is attached to the output residual and restored images.  If negative, this T/F pixel mask is not included.  Please note that this pixel mask is different from the deconvolution mask used to control the region where CLEAN based algorithms will search for source peaks.  In order to set a deconvolution mask based on pb level, please use the 'pbmask' parameter.

Based on the above, please note that certain values of pblimit to avoid, are 1, -1, and 0. When the pblimit is set to 1 the entire image is masked as the user is specifying that no normalization or deconvolution happens if the PB gain is lower than 1, which leads to the entire image being masked. Setting the pblimit to -1 also results in no deconvolution as mentioned in the case where pblimit is 1 but there is no masking of the image. Finally a pblimit of zero is not feasible but rather a small value such as 1e-6 is used instead to make a really large wide field image.


Specify a restoring beam and re-restore the model image.


Automatically mask emission during clean; see Masks for Deconvolution for more information.


Other Options

Handling Large Data and Image Sizes

Parallelization of the major cycle is available for continuum imaging and of both major and minor cycles for cube imaging. To manage memory use for very large image cubes, a channel chunking option is also provided.

User Interaction

Options for user interaction include interactive masking and editing of iteration control parameters and the output log files can be used to diagnose some problems.

Several convenience features are also available, such as operating on the MS in read-only mode (which does not require write permissions), the ability to restart and continue imaging runs without incuring the unnecessary cost of an inital major cycle or PSF construction and the optional return of a python dictionary that contains the convergence history of the run.

Scripting Controls

Finer control can be achieved using the PySynthesisImager tools  to run (for example) only image domain deconvolution or to insert methods for automatic mask generation (for example) in between the existing major/minor cycle loops or to connect external methods or algorithms for either the minor or major cycles.


Functional Blocks of Parameters

The tclean parameters are arranged in the following functional blocks. As a general rule, sub-parameters will appear (and be used) only when a parent parameter has a specific value. This means that for a given set of choices (e.g. deconvolution or gridding algorithm) only parameters that are relevant to that choice will be visible to the user when " inp() " is invoked. It is advised that this task interface be used even when constructing tclean scripts that call the task as a python call " tclean(....) " to understand which parameters are relevant to the run and which are not.


Data Selection

Selection parameters allow the definition of a subset of the supplied MS (or list of MSs) on which the imaging is to operate. 


Image Definition

The image coordinate system(s) and shape(s) can be set up to form single images (from a single field or from multiple fields forming a mosaic) or multiple fields to include smaller outlier fields, facetted images, single plane wideband images (with 1 or more Taylor terms to model spectra), 3D spectral cubes with multiple channels, 3D images with multiple Stokes planes, 4D images with frequency channels and Stokes planes. Various combinations of all these options are also supported.


Gridding Options

Options for convolutional resampling include standard gridding using a prolate spheroidal function, the use of FTs of Fresnel kernels for W-Projection and the use of baseline aperture illumination functions for A-Projection and Mosaicing. Combinations of these options are also available.  For some options, primary beams may be specified externally too.


Deconvolution Options

All our algorithms follow the Cotton-Schwab CLEAN style of major and minor cycles with the details of the deconvolution algorithm usually contained within the minor cycle and operating in the image domain. Options include Hogbom CLEAN, Clark CLEAN, Multi-Scale CLEAN and Multi-Term CLEAN (with Multi-Scale support).   Several options for making masks, including automasking, are also provided.


Data Weighting

Options for data weighting for imaging include Natural, Uniform and Robust weighting schemes along with an optional UV taper.


When doing Brigg's style weighting (including uniform) in tclean, the mosweight subparameter of the mosaic gridder determines whether to weight each field in a mosaic independently (mosweight = True), or to calculate the weight density  from the average uv distribution of all the fields combined (mosweight = False). The underlying issue with more uniform robust weighting is how the weight density maps onto the uv-grid, which can give high weight to areas of the uv-plane that are not actually more sensitive. The setting mosweight = True has long been known as potentially useful in cases where a mosaic has non-uniform sensitivity, but it was found that it is also very important for more uniform values of robust Briggs weighting in the presence of relatively poor uv-coverage. For example, snap-shot ALMA mosaics with mosweight = False typically show an increase in noise in the corners or in the areas furthest away from the phase-center. Therefore, as of CASA 5.4, the mosweight sub-parameter has been added to tclean with default value mosweight = True.

WARNING: the default setting of mosweight=True under the mosaic gridder in tclean has the following disadvantages: (1) it may potentially cause memory issues for large VLA mosaics; (2) the major and minor axis of the synthesized beam may be ~10% larger than with mosweight=False. Please change to mosweight=False to get around these issues.


Iteration Control

Iterations are controlled by user parameters (gain, niter, etc..) as well as stopping criteria that decide when to exit minor cycle iterations and trigger the next major cycle, and also when to terminate the major-minor loop. These stopping criteria include reaching iteration limits, convergence thresholds, and signs of divergence with appropriate messages displayed in the log.



Output Images

Depending on the operation being run, a subset of the following output images will be written to disk.

imagename = 'try'

try.psf Point Spread Function
try.pb Primary Beam
try.residual Residual Image (or initial Dirty Image)
try.model Model Image after deconvolution
try.image Restored output image
try.image.pbcor Primary Beam corrected image
try.mask Deconvolution mask
try.sumwt A single pixel image containing sum of weights per plane
try.weight Image of un-normalized sum of PB-square (for mosaics and A-Projection)

try.psf.tt0, try.psf.tt1, try.psf.tt2, try.model.tt0, try.model.tt1, try.residual.tt0, try.residual.tt1, try.image.tt0, try.image.tt1, etc...

Multi-term images representing Taylor coefficients (of polynomials that model the sky spectrum)


( try.n1.psf, try.n2.psf, try.n3.psf, try.n1.residual, try.n2.residual, try.n3.residual, try.n1.weight, try.n2.weight, try.n3.weight, try.n1.gridwt, try.n2.gridwt, etc... )

Scratch images written within a 'work directory' for parallel imaging runs. For continuum imaging, they are automatically gathered to produce the output images without the "nX" in the names. For cube imaging, they are reference-concatenated at the end to produce single output cubes.


Tracking moving sources or sources with ephemeris tables

If the phasecenter is a 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 (which is useful especially for long observations or multi epoch data). There is a special case, when phasecenter='TRACKFIELD', which will use the ephemerides or polynomial phasecenter in the FIELD table of the MeasurementSets as the source center to track. When in tracking mode,  the image center will be the direction of the source at the first time in the user selected data. At all other times, the source will be shifted by the amount it has moved in the frame of the image to that initial time. Examples of usage are presented in the tclean examples tab.