TCLEAN and ALMA CASA 5

From CASA Guides
Jump to navigationJump to search

As introduced in the "First Look at Imaging" guide here, starting with CASA 4.7, the imaging capabilities of CLEAN have been refactored and improved in a task called TCLEAN, which is called by the user in largely the same way as clean.

In this guide, the differences in syntax between CLEAN and TCLEAN (called hereafter "clean" and "tclean") are made more explicit. At any time, please see the CASA Task Reference Manual here for more information about tclean.

Major Syntax Changes

Updates to the task input syntax are called out here with notes below.

clean tclean
mode specmode
resmooth=True restoringbeam='common'
gridmode, imagermode gridder
psfmode deconvolver
modelimage startmodel
.flux (output) .pb (output)

General data selection:

  • The ability to select "field" and "spw" has been moved under selectdata = True in tclean; the default for selectdata is True.
  • It is now possible to select the datacolumn to image (data or observed, corrected); the default is "corrected".

Specifying spectral gridding mode:

  • Specifying the the spectral gridding type in clean with "mode" (mfs, channel, velocity, frequency) is now available in tclean as "specmode" (mfs, cube, cubedata).
  • To restore a cube to a common beam size in every channel, clean uses mode = 'channel' and resmooth = True; in tclean, this has become "restoringbeam = 'common'".
  • In tclean, specmode='cube'
    • restfreq, veltype are available as before for cubes
    • an additional parameter is chanchunks which controls how memory is allocated for cubes. In 4.7, tclean assumes that 80% of the computers memory is available for cube creation, if chanchunks=1, all of the imaging products (.residual, .psf, .model, etc) must fit into this memory allocation. With chanchunks=-1, a cube will be internally processed in chunks of channels according to size of the available memory (80% of the computers RAM).

Specifying gridding convolution function and deconvolver:

  • The gridding parameters "gridmode" (widefield, aprojection; and their respective expandable parameter lists) and "imagermode" (csclean, mosaic; and their respective expandable parameter lists) are now available as "gridder" (standard, wproject, widefield, mosaic, imagemosaic, awproject).
  • The deconvolver parameter "psfmode" (clark, clarkstokes, hogbom) is now available as "deconvolver" (hogbom, clark, multiscale, mtmfs, mem, clarkstokes).
  • Various sub-parameters under each of the gridder and deconvolver options have changed names as these tasks have been expanded.

Model images:

  • In clean, starting with a model image on disk required modelimage = 'model.image'; in tclean, use "startmodel" instead. Use care with setting "startmodel" and overwrite = True.
  • Note that in tclean, restarting an imaging run with restart = True and an existing image name in "imagename" will continue with that model, in which case "startmodel" must be set to ' '.

Output images:

  • In clean, the image of the sky sensitivity is called output_name.flux; in tclean, this image is called output_name.pb. If tclean is run with pbcor = True, then the output primary beam-corrected image is called output_name.image.pbcor (equal to output_name.image / output_name.pb).

Examples

The following are sample tclean calls for a variety of use cases. In each one, 'myvis.ms' is the visibility data, and 'myimage' is the desired output imagename prefix. In every case, we specify chanchunks=-1 since "chunking" cubes to reduce the memory required by the gridder is still experimental and assumes that 80% of your machine's memory is available to tclean.

Single field, continuum case

In this example, we create a single field (gridder='standard') continuum (deconvolver='mtmfs', specmode='mfs', nterms=2) image. Note that we use deconvolver='mtmfs' when the aggregate continuum fractional bandwidth is > 10%; otherwise use deconvolver='hogbom'. Note also that nterms > 1 is only available when deconvolver = 'mtmfs'. We primary beam correct the image with a primary beam cutoff at 0.2*PB. In this case, the data is called from the 'data' column, which would be the case if calibrations were applied and the 'corrected' column had been split off into a new MS. The cleaning is run with 1000 iterations (niter=1000) or until the threshold is reached (threshold='0.001mJy') in non-interactive mode (interactive=0), and the weights are set in the same way as clean (robust=0.5, weighting='briggs'). 

# In CASA 4.7 or later
tclean(vis='myvis.ms',
    imagename='myimage',
    spw=['17,19,21,23'],
    nterms=2, 
    threshold='0.001mJy', 
    robust=0.5,
    imsize=[100, 100], 
    niter=1000, 
    deconvolver='mtmfs', 
    weighting='briggs',
    pbcor=True, 
    pblimit=0.2, 
    cell=['0.1arcsec'], 
    datacolumn='data',
    specmode='mfs', 
    chanchunks=-1, 
    gridder='standard', 
    interactive=0)

Single field, line cube case

In this example, we create a single field (gridder='standard') spectral line (deconvolver='multiscale' for multiscale cleaning, specmode='cube' with width/start/nchan set appropriately and outframe='LSRK') image cube. We primary beam correct the image with a primary beam cutoff at 0.2*PB. In this case, the data is called from the 'corrected' column, which would be the case if calibrations were applied and the 'corrected' column is not split off. The cleaning is run with 1000 iterations (niter=1000) or until the threshold is reached (threshold='0.01mJy') in interactive mode (interactive=T), and the weights are set in the same way as clean (robust=0.5, weighting='briggs'). There will be a consistent beam size for the whole cube (restoringbeam='common'). 

# In CASA 4.7 or later
tclean(vis='myvis.ms',
    imagename='myimage',
    spw=['25'],
    threshold='0.01mJy', 
    robust=0.5,
    imsize=[100, 100], 
    niter=1000, 
    width='0.5km/s',
    start='550km/s',
    outframe='LSRK',
    nchan=100,
    deconvolver='multiscale', 
    weighting='briggs',
    pbcor=True, 
    pblimit=0.2, 
    cell=['0.1arcsec'], 
    datacolumn='corrected',
    specmode='cube', 
    restoringbeam='common',
    chanchunks=-1, 
    gridder='standard', 
    interactive=T)

Mosaic, continuum case

In this example, we create a mosaic (gridder='mosaic') continuum (deconvolver='hogbom', specmode='mfs') image. Note that we use deconvolver='hogbom' when the aggregate continuum fractional bandwidth is < 10%; otherwise use deconvolver='mtmfs'. We primary beam correct the image with a primary beam cutoff at 0.2*PB. In this case, the data is called from the 'data' column, which would be the case if calibrations were applied and the 'corrected' column had been split off into a new MS. The cleaning is run with 10000 iterations (niter=10000) or until the threshold is reached (threshold='0.001mJy') in interactive mode (interactive=T), and the weights are set in the same way as clean (robust=0.5, weighting='briggs'). 

# In CASA 4.7 or later
tclean(vis='myvis.ms',
    imagename='myimage',
    spw=['17,19,21,23'],
    threshold='0.001mJy', 
    robust=0.5,
    imsize=[1000, 500], 
    niter=10000, 
    deconvolver='hogbom', 
    weighting='briggs',
    pbcor=True, 
    pblimit=0.2, 
    cell=['0.1arcsec'], 
    datacolumn='data',
    specmode='mfs', 
    chanchunks=-1, 
    gridder='mosaic', 
    interactive=T)

Mosaic, line cube case

In this example, we create a mosaic (gridder='mosaic') spectral line (deconvolver='hogbom', specmode='cube' with width/start/nchan set appropriately and outframe='LSRK') image cube. Here we also image two separate MS files (called 'myvis1.ms' and 'myvis2.ms') simultaneously. We primary beam correct the image with a primary beam cutoff at 0.2*PB. In this case, the data is called from the 'corrected' column, which would be the case if calibrations were applied and the 'corrected' column is not split off. The cleaning is run with 100000 iterations (niter=100000) or until the threshold is reached (threshold='0.05mJy') in interactive mode (interactive=T), and the weights are set in the same way as clean (robust=0.5, weighting='briggs'). There will be a consistent beam size for the whole cube (restoringbeam='common'). 

# In CASA 4.7 or later
tclean(vis=['myvis1.ms','myvis2.ms'],
    imagename='myimage',
    spw=['25'],
    threshold='0.05mJy', 
    robust=0.5,
    imsize=[1500, 500], 
    niter=100000, 
    width='0.5km/s',
    start='550km/s',
    outframe='LSRK',
    nchan=100,
    deconvolver='hogbom', 
    weighting='briggs',
    pbcor=True, 
    pblimit=0.2, 
    cell=['0.1arcsec'], 
    datacolumn='corrected',
    specmode='cube', 
    restoringbeam='common',
    chanchunks=-1, 
    gridder='mosaic', 
    interactive=T)

Further Notes

  • In each example here, we specify chanchunks=-1 since "chunking" cubes to reduce the memory required by the gridder is still experimental. Any setting other than chanchunks=-1 (or 1) assumes that 80% of your machine's memory is available to tclean; memory allocation issues and segmentation faults will result if this is not the case.
  • The 4.7 implementation of tclean includes some heuristics to help prevent divergence. If tclean detects:
 -- divergence within minor cycle iterations 
   -> as an increase of 10% from the minimum peak residual so far 
       -> it will stop minor cycle iterations for this plane.
 -- divergence across major cycle boundaries  
   -> as an increase of 50% before/after a major cycle indicating that the model in the minor cycle really doesn't fit the data any more
       -> it will stop the entire run after that major cycle.
Retrieved from "https://casaguides.nrao.edu/index.php?title=TCLEAN_and_ALMA_CASA_5&oldid=20364"