deconvolve

deconvolve(imagename='', startmodel='', deconvolver='hogbom', scales='', nterms=2, smallscalebias=0.0, fusedthreshold=0.0, largestscale=-1, restoration=True, restoringbeam='', niter=100, gain=0.1, threshold=0.0, nsigma=0.0, interactive=False, fullsummary=False, fastnoise=True, usemask='user', mask='', pbmask=0.0, sidelobethreshold=3.0, noisethreshold=5.0, lownoisethreshold=1.5, negativethreshold=0.0, smoothfactor=1.0, minbeamfrac=0.3, cutthreshold=0.01, growiterations=75, dogrowprune=True, verbose=False)[source]

Image-domain deconvolution

[Description] [Examples] [Development] [Details]

Parameters

  • imagename ({int, string, stringVec}=’’) - Pre-name of input and output images

  • startmodel (string=’’) - Name of starting model image

  • deconvolver (string=’hogbom’) - Minor cycle algorithm (hogbom,clark,multiscale,mtmfs,mem,clarkstokes,asp)

    deconvolver = multiscale

    • scales ({intVec, doubleVec}=’’) - List of scale sizes (in pixels) for multi-scale algorithms

    • smallscalebias (double=0.0) - Biases the scale selection when using multi-scale or mtmfs deconvolvers

    deconvolver = mtmfs

    • scales ({intVec, doubleVec}=’’) - List of scale sizes (in pixels) for multi-scale algorithms

    • nterms (int=2) - Number of Taylor coefficients in the spectral model

    • smallscalebias (double=0.0) - Biases the scale selection when using multi-scale or mtmfs deconvolvers

    deconvolver = asp

    • fusedthreshold (double=0.0) - Threshold for triggering Hogbom Clean

    • largestscale (int=-1) - Largest scale allowed for the Asp Clean deconvolver

  • restoration (bool=True) - Do restoration steps (or not)

    restoration = True

    • restoringbeam ({string, stringVec}=’’) - Restoring beam shape to use. Default is the PSF main lobe

  • niter (int=100) - Maximum number of iterations

    niter != 0

    • gain (double=0.1) - Loop gain

    • threshold (double=0.0) - Stopping threshold

    • nsigma (double=0.0) - Multiplicative factor for rms-based threshold stopping

    • fastnoise (bool=True) - True: use the faster (old) noise calculation. False: use the new improved noise calculations

  • interactive (bool=False) - Modify masks and parameters at runtime

  • fullsummary (bool=False) - Return dictionary with complete convergence history

  • usemask (string=’user’) - Type of mask(s) for deconvolution: user, pb, or auto-multithresh

    usemask = user

    • mask ({string, stringVec}=’’) - Mask (a list of image name(s) or region file(s) or region string(s) )

    • pbmask (double=0.0) - primary beam mask

    usemask = pb

    • pbmask (double=0.0) - primary beam mask

    usemask = auto-multithresh

    • pbmask (double=0.0) - primary beam mask

    • sidelobethreshold (double=3.0) - sidelobethreshold * the max sidelobe level * peak residual

    • lownoisethreshold (double=1.5) - lownoisethreshold * rms in residual image + location(median)

    • negativethreshold (double=0.0) - negativethreshold * rms in residual image + location(median)

    • smoothfactor (double=1.0) - smoothing factor in a unit of the beam

    • minbeamfrac (double=0.3) - minimum beam fraction for pruning

    • cutthreshold (double=0.01) - threshold to cut the smoothed mask to create a final mask

    • growiterations (int=75) - number of binary dilation iterations for growing the mask

    • dogrowprune (bool=True) - Do pruning on the grow mask

    • verbose (bool=False) - True: print more automasking information in the logger

Description

The deconvolve task performs image-domain deconvolution with options for automasking and restoration. It can be viewed as the minor cycle of the iterative image reconstruction offered by the tclean task. The functionality that it introduces is the ability to just run the deconvolution step alone.

The deconvolve task uses the same minor cycle as tclean. Therefore, the two tasks will evaluate the minor cycle in the exact same way. However, deconvolve operates purely in the image domain and the final residual images are saved to disk at the end of the minor cycle iterations. In tclean, the residual images are saved to disk after an additional major cycle. The results between deconvolve and tclean may therefore differ at a level that varies per dataset and algorithm setup.

This task gathers many of its runtime parameters from the meta data stored within the input images. It also doesn’t have a need for data selection or a measurement set, and therefore requires much fewer input parameters than the tclean task. At the end of a successful deconvolve run, the history of the output images is updated. This is done in the same way as for the tclean task. For every deconvolve command a series of entries is recorded, including the task name “deconvolve”, the CASA version used, and every parameter-value pair of the task, which can then be inspected with the task imhistory.

Images

The imagename parameter determines the name prefix used to find input images and defines output images. For all uses, the .psf and .residual images are always required. See the parameter description for a full list of expected images.

Input/output images may be 4D CASA Image Cubes with the axis ordering set to [ra,dec,pol,chan] as is the default for tclean (see the Correcting Axes example). All input 2D and 3D images must be regridded to a 4D CASA image prior to being supplied as input.

Iteration Control

The niter parameter for deconvolve sets the maximum number of iterations possible per channel/stokes plane being deconvolved. It is equivalent to tclean’s cycleniter parameter.

Note

Each call to deconvolve starts at an iteration count of 0. Multiple successive calls to deconvolve (with the same image names) will start from the model image found on disk, but the iteration counts will always start from zero. Therefore, for a single plane image, deconvolve(niter=10);deconvolve(niter=10) will each report doing 10 iterations, but the image that results from the two successive calls will be equivalent to the result from deconvolve(niter=20).

Note

Niter is the maximum possible per channel/stokes plane, and for cube imaging iterations are counted across all planes of the image. Therefore, the total number of iterations for a cube imaging run can reach a maximum of nchan x niter. This behaviour is similar to that in the tclean task.

More information on the per-call iteration control results can be found in the return dictionary.

For more details about minor cycle stopping criteria, please refer to the tclean iteration control documentation .

Interactive Mask

The interactive parameter allows for modifying the masks and parameters before deconvolution. The interactive GUI starts immediately, and user may draw masks and edit iteration control parameters. If other masking parameters are set, the mask is first evaluated and then displayed in the interactive Clean GUI for additional interactive changes.

Note

If a mask already exists on disk, with a name that matches imagename.mask, it will automatically load that mask when the interactive clean window opens. Prior to running deconvolve, if tclean is run with niter=0 (with no mask supplied) to generate the initial images, please note that a mask filled with ones will be generated on disk and this will get loaded when the deconvolve task interactive clean window opens. Please check the cursor tab on the GUI for the mask image values.

Return Value:

For niter >= 0, the deconvolve task returns a dictionary containing a summary of the run. The fullsummary parameter controls the amount of the information returned in the dictionary. The deconvolve task returns a shorten version of the summary dictionary by omittiong some ‘summaryminor’ inforamation when this parameter is set to False.

Example Return Value:

{
        'cleanstate': 'running',
        'cyclefactor': 1.0,
        'cycleiterdone': 0,
        'cycleniter': 2,
        'cyclethreshold': 0.0,
        'interactiveiterdone': 0,
        'interactivemode': False,
        'interactiveniter': 0,
        'interactivethreshold': 0.0,
        'iterdone': 4,
        'loopgain': 0.1,
        'maxpsffraction': 0.800,
        'maxpsfsidelobe': 0.137,
        'minpsffraction': 0.100,
        'niter': 2,
        'nmajordone': 0,
        'nsigma': 0.0,
        'stopcode': 1,
        'summarymajor': array([], dtype=int64),
        'summaryminor': { 0: {
            0: { 0: {
                'startIterDone': [0.0],
                'iterDone': [2.0],
                'startPeakRes': [1.500],
                'peakRes': [1.215],
                'startModelFlux': [0.0],
                'modelFlux': [0.285],
                'startPeakResNM': [1.500],
                'peakResNM': [1.215],
                'cycleThresh': [0.0],
                'cycleStartIters': [0.0],
                'masksum': [10000.0],
                'mpiServer': [0.0],
                'peakMem': [11.022],
                'runtime': [0.100],
                'stopCode': [1.0]}},
            1: { 0: {
                'startIterDone': [2.0],
                'iterDone': [2.0],
                'startPeakRes': [0.750],
                'peakRes': [0.607],
                'startModelFlux': [0.0],
                'modelFlux': [0.142],
                'startPeakResNM': [0.750],
                'peakResNM': [0.607],
                'cycleThresh': [0.0],
                'cycleStartIters': [0.0],
                'masksum': [10000.0],
                'mpiServer': [0.0],
                'peakMem': [11.022],
                'runtime': [0.100],
                'stopCode': [1.0]
            } }
        } },
        'threshold': 0.0
   }

For more information on the return value from tclean and deconvolve, please refer to the notebook “Synthesis Imaging”.

Examples

Basic Usage

Build the ‘.image’ image from the ‘.residual’ and ‘.psf’ images, as given by tclean or some other task.

from casatools import ctsys
refim_path = ctsys.resolve('unittest/deconvolve/')

# remove the old run, as necessary
os.system("rm -rf try.*")

# create the .residual and .psf images
tclean(vis=refim_path+'refim_point.ms', imagename='try', imsize=100, cell='8.0arcsec', niter=0)

# run deconvolve to generate the .image image
ret=deconvolve(imagename='try', deconvolver='clark', niter=20) # “restoration” defaults to True

This works for all of the common cases, including:

  • All the deconvolvers (hogbom, clark, clarkstokes, multiscale)

  • 2D, 3D, and 4D images/cubes, regridded as appropriate to have axes [ra,dec,pol,chan]

  • Restoration with a common beam or restoringbeam

  • Masking (user, pbmask, automask)

  • With a different start model

Multiple Runs

Run deconvolve multiple times. This can be done with all of the same parameters and the same deconvolver algorithm. This should give the same results as running deconvolve once with the same total number of iterations. With the code below, we should get the same result as when running the Basic Usage example.

from casatools import ctsys
refim_path = ctsys.resolve('unittest/deconvolve/')

# remove the old run, as necessary
os.system("rm -rf try.*")

# create the .residual and .psf images
tclean(vis=refim_path+'refim_point.ms', imagename='try', imsize=100, cell='8.0arcsec', niter=0)

# run deconvolve for 20 total iterations (10x2)
ret1=deconvolve(imagename='try', deconvolver='clark', niter=10, interactive=0)
ret2=deconvolve(imagename='try', deconvolver='clark', niter=10, interactive=0)

Automasking Experimentation

Task deconvolve can be used in conjunction with task tclean to quickly home in on the correct automasking parameters. Running the task many times in a row to watch how the mask evolves is much faster with deconvolve because the slow major cycle of tclean is avoided.

###############################################################################
# autotest_script.py
###############################################################################

import shutil

def setup():
    '''Get the ms and evaluate tclean'''
    os.system('rm -rf try.* *.ms bak')
    os.system('mkdir bak')
    refdatapath = ctsys.resolve('unittest/deconvolve/')
    shutil.copytree(refdatapath+'refim_twochan.ms', 'refim_twochan.ms')

    tclean(vis='refim_twochan.ms', imagename='try', niter=0, imsize=100, cell='8.0arcsec', \
           deconvolver='hogbom', usemask='auto-multithresh', restoration=False, calcres=True)
    os.system("cp -rp try.* bak/")

def restore_files(restore=False):
    '''Get the image files for a clean deconvolution test'''
    os.system('rm -rf try.*')
    os.system('cp -rp bak/* ./')

### Try out different automasking parameters with deconvolve.
### Parameters to play with: sidelobethreshold, noisethreshold, lownoisethreshold, negativethreshold, smoothfactor, minbeamfrac, cutthreshold, growiterations, dogrowprune, fastnoise
### To be run with "casa -c autotest_script.py":
setup() # only need to do this the first time running the script
restore_files()
# Evaluate some number of times with a for loop to watch how the automask evolves.
for n in range(10):
    ret=deconvolve(imagename='try', niter=10, deconvolver='hogbom', interactive=True, usemask='auto-multithresh', verbose=True)

Multiple Clean Methods

Start with one deconvolve method, then switch to a different deconvolve method. For example, the multiscale clean method is slow but makes quick progress in the beginning, so start with multiscale clean and then switch to the much faster hogbom clean.

from casatools import ctsys
g55path = ctsys.resolve('RSRO/SNR/LBand_G55.7+3.4')

def run_G55(cycle, init=False, deconvolver='hogbom', niter=200):
    '''
    Run tclean's major cycle to get multiscale RHS images.
    Run deconvolve separately on this.
    '''
    if (init):
        print("Initializing!!!")

    if cycle=='major':
        if init==True:
            os.system('rm -rf tdec_G55*')
        print("Running a major cycle with tclean")
        vis = g55path+'/G55.7+3.4_cal.ms'
        tclean(vis=vis, imagename='tdec_G55', deconvolver=deconvolver, gridder='wproject', \
               wprojplanes=24, cell='8.0arcsec', imsize=1024, weighting='briggs', niter=0)

    elif cycle=='minor':
        print("Running a minor cycle")
        if deconvolver == 'hogbom':
            ret=deconvolve(imagename='tdec_G55', deconvolver=deconvolver, niter=niter, \
                           interactive=0)
        elif deconvolver == 'multiscale':
            ret=deconvolve(imagename='tdec_G55', deconvolver=deconvolver, niter=niter, \
                           interactive=0, scales=[0,6,10,20,30], smallscalebias=-0.6)
        else:
            print("unrecognized deconvolver \""+deconvolver+"\"")
            return

    else:
        print("Unrecognized cycle argument value \""+cycle+"\"")

for i in range(5):
    run_G55(cycle='major', init=(i==0))
    run_G55(cycle='minor', deconvolver='multiscale', niter=5)
    run_G55(cycle='minor', deconvolver='hogbom', niter=195)

Correcting Axes

The tasks imtrans, importfits, and imregrid (and the image tool) can be used to correct coordinate systems, shape, and axes ordering in images. For example, when importing fits images, the stokes axis might be the third axis instead of the fourth. This code can be used to correct such a situation before running task deconvolve:

# import fits images
importfits('try_residual.fits', imagename='try_orig.residual')
importfits('try_psf.fits', imagename='try_orig.psf')

# fix axes for residual
imhead('try_orig.residual')
# in terminal: 'axisnames':...['Right Ascension', 'Declination', 'Stokes', 'Frequency']...
imtrans('try_orig.residual', outfile='try_slast.residual', order='0132')
imhead('try_slast.residual')
# in terminal: 'axisnames':...['Right Ascension', 'Declination', 'Frequency', 'Stokes']...
#              'refval':...[5.23369701e+00, 7.10938054e-01, 1.49998515e+09, 1.00000000e+00]...

# fix axes for psf
# Note: the image.adddegaxes tool can also be used to add new axes
imhead('try_orig.psf')
# in terminal: 'axisnames':...['Right Ascension', 'Declination']...
importfits('try_psf.fits', imagename='try_orig.psf',
           defaultaxes=True, defaultaxesvalues=['','','1.5GHz','I'], overwrite=True)
imtrans('try_orig.psf', outfile='try_slast.psf', order='0132')
imhead('try_slast.psf')
# in terminal, psf: 'axisnames':...['Right Ascension', 'Declination', 'Frequency', 'Stokes']...

# perform deconvolution
ret=deconvolve('try_slast')

Working with SD Images

Single Dish images can be deconvolved as long as they meet the input requirements (see the imagename parameter for a list of required images). If the SD image is available but not the PSF, a generic Gaussian PSF can be created with a tool from the sdintimaging task. This code creates a PSF for the M100 SD image and deconvolves it.

from casatools import ctsys
m100path = ctsys.resolve('M100_TP')

# Use the SDINT_helper class to create the PSF.
# The SDINT_helper utility class is in the "private" directory of the wrapped python sdintimaging 
# task code. To access the sdint_helper file, we need to tell python EXACTLY where
# sdint_helper.py is.
sys.path.append(casatasks.__path__[0] + "/private/")
from sdint_helper import *
sdintlib = SDINT_helper()

# get/rename the residual image
os.system("cp -rp "+m100path+" M100_SD.residual")

# get/rename, or create, the psf image
# os.system("cp -rp psf_for_m100_tp M100_SD.psf")
# Create a PSF cube with Gaussians derived from restoringbeam information in the residual image
sdintlib.create_sd_psf("M100_SD.residual", "M100_SD.psf")

# deconvolve input: .residual .psf
# output: .image .mask .model .residual
ret=deconvolve(imagename="M100_SD", deconvolver="multiscale", scales=[0,5,15], niter=100,
               threshold='0.0mJ')

Updating Deconvolve Scripts

The parameters differ slightly from the old deconvolve task. If you are updating old scripts from before CASA 6.1.3 to use this new deconvolve task, the following steps should be followed:

  1. Add code that copies the images to be deconvolved to the “model” output image name before deconvolving.

  2. Some of the parameters need to be renamed, from “alg” and “prior” to “deconvolver” and “startmodel”.

  3. The “imagename” parameter now describes the prefix part of the image and PSF names, and any suffixes (such as “.image” or “.residual”) should be removed.

  4. The parameters “targetflux” and “sigma” for MEM cleaning, and using strings to describe the PSF are no longer supported. These parameters must be dropped. If no PSF is available to use, one can be created as described in the Working with SD Images example.

For example, this:

deconvolve(imagename='mydirtyimage.image', model='mycleanimage.image', psf='mydirtyimage.psf',
           alg='multiscale', scales=[0,3,10], niter=10000, gain=0.1, threshold='10mJy')

..becomes this:

import shutil
shutil.copytree('mydirtyimage.image', 'mycleanimage.residual')
shutil.copytree('mydirtyimage.psf', 'mycleanimage.psf')
deconvolve(imagename='mycleanimage', deconvolver='multiscale', scales=[0,3,10], niter=10000, 
           gain=0.1, threshold='10mJy')
Development

The deconvolve python code was copied from and mirrors tclean’s code, including a copy of imager_base.py as imager_deconvolver.py that has many of the parameters for tclean stripped out.

Note

There is a bug with hogbom multirun that causes it to evaluate for 1 more iteration than requested. So to compare the multiple runs results to single run results for hogbom, evaluate deconvolve with 19 and 9x2 iterations, instead of 20 and 10x2 iterations as in these examples (i.e. deconvolve(niter=19) = deconvolve(9)+deconvolve(9) to get 20 iterations in total).

Parameter Details

Detailed descriptions of each function parameter

imagename ({int, string, stringVec}='') - Pre-name of input and output images
example : imagename=’try’

Input images (* = required):

try.psf* - The point spread function
try.residual* - The observed (or residual) image, such as one
generated by tclean
try.model - An existing model image from a previous run of
tclean or deconvolve
try.mask - A pre-defined mask to be either used directly or
combined with additional masking options
try.pb - Primary beam model, if required for masking settings

Output images:

try.model - A new or updated model image
try.residual - An updated residual image
try.image - A restored image, created only when restoration=True
try.mask - The output mask
try.prev.mask - An intermediate by-product of automasking
(when usemask=’auto-multithresh’)

For multi-term wideband imaging, all relevant images above will
have additional .tt0,.tt1, etc suffixes to indicate Taylor terms,
plus the following extra input 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 a deconvolution run without changing ‘imagename’
implies continuation from the existing model image on disk.
By default, the residual image will be recomputed.

Note : All deconvolution 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.

Note : All input/output images should be 4D image cubes with axes
[ra,dec,pol,chan], as is the default for the task tclean. Any input
images without this format must be modified (eg with imregrid,
imtrans, image.adddegaxes) in order to be accepted.
startmodel (string='') - Name of starting model image
The contents of the supplied starting model image will be
copied to the imagename.model before the run begins.
example : startmodel = ‘singledish.im’
For deconvolver=’mtmfs’, one image per Taylor term must be provided.
example : startmodel = [‘try.model.tt0’, ‘try.model.tt1’]
startmodel = [‘try.model.tt0’] will use a starting model only
for the zeroth order term.
startmodel = [‘’,’try.model.tt1’] will use a starting model only
for the first order term.
This starting model can be of a different image shape and size from
what is currently being imaged. If so, an image regrid is first triggered
to resample the input image onto the target coordinate system.

If the startmodel is supplied, but a copy of of the destination
imagename.model already exists, deconvolve will exit with an error.
A common usage is to set this parameter equal to a single dish image
Negative components in the model image will be included as is.
deconvolver (string='hogbom') - Name of minor cycle algorithm (hogbom,clark,multiscale,mem,clarkstokes,asp)
Each of the following algorithms operate on residual images and psfs
from the gridder and produce output model and restored images.
Minor cycles stop when threshold or niter 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
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.)
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
scales ({intVec, doubleVec}='') - List of scale sizes (in pixels) for multi-scale and mtmfs algorithms.
This set of scale sizes should represent the sizes
(diameters in units of number of pixels)
of dominant features in the image being reconstructed.
The smallest scale size is recommended to be 0 (point source),
the second the size of the synthesized beam and the third 3-5
times the synthesized beam, etc. For example, if the synthesized
beam is 10” FWHM and cell=2”,try scales = [0,5,15].
For numerical stability, the largest scale must be
smaller than the image (or mask) size and smaller than or
comparable to the scale corresponding to the lowest measured
spatial frequency (as a scale size much larger than what the
instrument is sensitive to is unconstrained by the data making
it harder to recovery from errors during the minor cycle).
nterms (int=2) - Number of Taylor coefficients in the spectral model
- nterms=1 : Assume flat spectrum source
- nterms=2 : Spectrum is a straight line with a slope
- nterms=N : A polynomial of order N-1
From a Taylor expansion of the expression of a power law, the
spectral index is derived as alpha = taylorcoeff_1 / taylorcoeff_0
Spectral curvature is similarly derived when possible.
The optimal number of Taylor terms depends on the available
signal to noise ratio, bandwidth ratio, and spectral shape of the
source as seen by the telescope (sky spectrum x PB spectrum).
nterms=2 is a good starting point for wideband EVLA imaging
and the lower frequency bands of ALMA (when fractional bandwidth
is greater than 10%) and if there is at least one bright source for
which a dynamic range of greater than few 100 is desired.
Spectral artifacts for the VLA often look like spokes radiating out from
a bright source (i.e. in the image made with standard mfs imaging).
If increasing the number of terms does not eliminate these artifacts,
check the data for inadequate bandpass calibration. If the source is away
from the pointing center, consider including wide-field corrections too.
(Note : In addition to output Taylor coefficient images .tt0,.tt1,etc
images of spectral index (.alpha), an estimate of error on
spectral index (.alpha.error) and spectral curvature (.beta,
if nterms is greater than 2) are produced.
- These alpha, alpha.error and beta images contain
internal T/F masks based on a threshold computed
as peakresidual/10. Additional masking based on
.alpha/.alpha.error may be desirable.
- .alpha.error is a purely empirical estimate derived
from the propagation of error during the division of
two noisy numbers (alpha = xx.tt1/xx.tt0) where the
‘error’ on tt1 and tt0 are simply the values picked from
the corresponding residual images. The absolute value
of the error is not always accurate and it is best to interpret
the errors across the image only in a relative sense.)
smallscalebias (double=0.0) - A numerical control to bias the scales when using multi-scale or mtmfs algorithms.
The peak from each scale’s smoothed residual is
multiplied by ( 1 - smallscalebias * scale/maxscale )
to increase or decrease the amplitude relative to other scales,
before the scale with the largest peak is chosen.
Smallscalebias can be varied between -1.0 and 1.0.
A score of 0.0 gives all scales equal weight (default).
A score larger than 0.0 will bias the solution towards smaller scales.
A score smaller than 0.0 will bias the solution towards larger scales.
The effect of smallscalebias is more pronounced when using multi-scale relative to mtmfs.
fusedthreshold (double=0.0) - Threshold for triggering Hogbom Clean (number in units of Jy)
fusedthreshold = 0.0001 : 0.1 mJy
This is a subparameter of the Asp Clean deconvolver. When peak residual
is lower than the threshold, Asp Clean is “switched to Hogbom Clean” (i.e. only use the 0 scale for cleaning) for
the following number of iterations until it switches back to Asp Clean.
NumberIterationsInHogbom = 50 + 2 * (exp(0.05 * NthHogbom) - 1)
, where NthHogbom is the number of times Hogbom Clean has been triggered.
When the Asp Clean detects it is approaching convergence, it uses only the 0 scale for the following number of iterations for better computational efficiency.
NumberIterationsInHogbom = 500 + 2 * (exp(0.05 * NthHogbom) - 1)
largestscale (int=-1) - Largest scale (in pixels) allowed for the initial guess for the Asp Clean deconvolver.
largestscale = 100
The default initial scale sizes used by Asp Clean is [0, w, 2w, 4w, 8w],
where w is the PSF width. The default largestscale is -1 which indicates
users accept these initial scales. If largestscale is set, the initial scales
would be [0, w, … up to the largestscale]. This is only an initial guess,
and actual fitted scale sizes may evolve from these initial values.
It is recommended not to set largestscale unless Asp Clean picks a large
scale that has no constraints from the data (the UV hole issue).
restoration (bool=True) - Restore the model image.
Construct a restored image : imagename.image by convolving the model
image with a clean beam and adding the residual image to the result.
If a restoringbeam is specified, the residual image is also
smoothed to that target resolution before adding it in.
If a .model does not exist, it will make an empty one and create
the restored image from the residuals ( with additional smoothing if needed ).
With algorithm=’mtmfs’, this will construct Taylor coefficient maps from
the residuals and compute .alpha and .alpha.error.
restoringbeam ({string, stringVec}='') - Restoring beam shape/size to use.
- restoringbeam=’’ or [‘’]
A Gaussian fitted to the PSF main lobe (separately per image plane).
- restoringbeam=’10.0arcsec’
Use a circular Gaussian of this width for all planes
- restoringbeam=[‘8.0arcsec’,’10.0arcsec’,’45deg’]
Use this elliptical Gaussian for all planes
- restoringbeam=’common’
Automatically estimate a common beam shape/size appropriate for
all planes.
Note : For any restoring beam different from the native resolution
the model image is convolved with the beam and added to
residuals that have been convolved to the same target resolution.
niter (int=100) - Maximum number of iterations
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 : Skip the deconvolution step (only do restoration)
niter larger than zero : The minor cycle.
Note : The following additional triggers will also stop minor cycle
iterations. Whichever condition is triggered first stops the minor
cycle.

‘threshold’ : The parameter value, compared to peak residual.
Divergence : As detected by 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 ‘niter’ or ‘threshold’.
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, nchan=10,threshold=0,
a total of 1000 iterations will be done in the first set of minor cycles
before the total is compared with niter=100 and it exits.
gain (double=0.1) - Loop gain
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 (for example).
threshold (double=0.0) - The minor cycle’s stopping threshold (number in units of Jy, or string)
threshold = 0.005 : 5mJy
threshold = ‘5.0mJy’

Note : If nsigma is set (>0.0), the N-sigma threshold is calculated (see
the description under nsigma). Then threshold is modified as:

threshold = max( threshold, nsgima_threshold )
nsigma (double=0.0) - Multiplicative factor for rms-based threshold stopping
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 threshold, is used as a stopping trigger
(see also the descreption under ‘threshold’).
Set nsigma=0.0 to preserve the previous deconvolve behavior without this feature.
The top level parameter, fastnoise is relevant for the rms noise calculation which is used
to determine the threshold.
interactive (bool=False) - Modify masks and parameters at runtime
interactive=True will trigger an interactive GUI after deconvolution finishes.
Options for runtime parameter modification are :
Interactive clean mask : Draw a 1/0 mask (appears as a contour) by hand.
If a mask is supplied at the task interface or if
automasking is invoked, the current mask is
displayed in the GUI and is available for manual
editing.

Note : If a mask contour is not visible, please
check the cursor display at the bottom of
GUI to see which parts of the mask image
have ones and zeros. If the entire mask=1
no contours will be visible.
Operation buttons : – For the task deconvolve, all options stop the minor cycle.
Iteration control : – max cycleniter : For task deconvolve, this contol has no effect.
– iterations left : Sets the limit on the number of iterations
about to be done.
– threshold : Sets the peak residual stopping threshold for
for this execution of deconvolve.
fullsummary (bool=False) - Return dictionary with complete convergence history
fullsummary=True: A full version of the summary dictionary is returned.
Keys include ‘iterDone’,’peakRes’,’modelFlux’,’cycleThresh’ that record the
convergence state at the end of each set of minor cycle iterations
separately for each image plane (i.e. channel/stokes) being
deconvolved. Additional keys report the convergence state at the
start of minor cycle iterations, stopping criteria that triggered major
cycles, and a processor ID per channel, for parallel cube runs.
fullsummary=False (default): A shorten version of the summary dictionary is returned
with only ‘iterDone’,’peakRes’,’modelFlux’, and ‘cycleThresh’.
Detailed information about the return dictionary fields may be found
at CASA Docs > Synthesis Imaging > Iteration Control > Returned Dictionary.
fastnoise (bool=True) - Only relevant when automask (user=’multi-autothresh’) and/or n-sigma stopping threshold
(nsigma>0.0) are/is used. If it is set to True, a simpler but faster noise calucation is used.
In this case, the threshold values are determined based on classic statistics (using all
unmasked pixels for the calculations).
If it is set to False, the new noise calculation
method is used based on pre-existing mask.
Case 1: no exiting mask
Calculate image statistics using Chauvenet algorithm
Case 2: there is an existing mask
Calculate image statistics by classical method on the region
outside the mask and inside the primary beam mask.
In all cases above RMS noise is calculated from MAD.
usemask (string='user') - Type of mask(s) to be used for deconvolution
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 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
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 ({string, stringVec}='') - Mask (a list of image name(s) or region file(s) or region string(s)

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, deconvolve 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.
pbmask (double=0.0) - Sub-parameter for usemask: primary beam mask
Examples : pbmask=0.0 (default, no pb mask)
pbmask=0.2 (construct a mask at the 0.2 pb gain level)
sidelobethreshold (double=3.0) - Sub-parameter for “auto-multithresh”: mask threshold based on sidelobe levels:
sidelobethreshold * max_sidelobe_level * peak residual
noisethreshold (double=5.0) - Sub-parameter for “auto-multithresh”: mask threshold based on the noise level:
noisethreshold * rms + location (=median)
The rms is calculated from MAD with rms = 1.4826*MAD.
lownoisethreshold (double=1.5) - Sub-parameter for “auto-multithresh”: mask threshold to grow previously masked regions via binary dilation:
lownoisethreshold * rms in residual image + location (=median)
The rms is calculated from MAD with rms = 1.4826*MAD.
negativethreshold (double=0.0) - Sub-parameter for “auto-multithresh”: mask threshold for negative features:
-1.0* negativethreshold * rms + location(=median)
The rms is calculated from MAD with rms = 1.4826*MAD.
smoothfactor (double=1.0) - Sub-parameter for “auto-multithresh”: smoothing factor in a unit of the beam
minbeamfrac (double=0.3) - Sub-parameter for “auto-multithresh”: minimum beam fraction in size to prune masks smaller than mimbeamfrac * beam
<=0.0 : No pruning
cutthreshold (double=0.01) - Sub-parameter for “auto-multithresh”: threshold to cut the smoothed mask to create a final mask:
cutthreshold * peak of the smoothed mask
growiterations (int=75) - Sub-parameter for “auto-multithresh”: Maximum number of iterations to perform using binary dilation for growing the mask
dogrowprune (bool=True) - Experimental sub-parameter for “auto-multithresh”: Do pruning on the grow mask
verbose (bool=False) - If it is set to True, the summary of automasking at the end of each automasking process
is printed in the logger. Following information per channel will be listed in the summary.
chan: channel number
masking?: F - stop updating automask for the subsequent iteration cycles
RMS: robust rms noise
peak: peak in residual image
thresh_type: type of threshold used (noise or sidelobe)
thresh_value: the value of threshold used
N_reg: number of the automask regions
N_pruned: number of the automask regions removed by pruning
N_grow: number of the grow mask regions
N_grow_pruned: number of the grow mask regions removed by pruning
N_neg_pix: number of pixels for negative mask regions
Note that for a large cube, extra logging may slow down the process.