#
# stub function definition file for docstring parsing
#
[docs]def deconvolve(imagename='', startmodel='', deconvolver='hogbom', scales='', nterms=2, smallscalebias=0.0, 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):
r"""
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,mem,clarkstokes)
.. raw:: html
<details><summary><i> deconvolver = multiscale </i></summary>
- 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
.. raw:: html
</details>
.. raw:: html
<details><summary><i> deconvolver = mtmfs </i></summary>
- 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
.. raw:: html
</details>
- restoration_ (bool=True) - Do restoration steps (or not)
.. raw:: html
<details><summary><i> restoration = True </i></summary>
- restoringbeam_ ({string, stringVec}='') - Restoring beam shape to use. Default is the PSF main lobe
.. raw:: html
</details>
- niter_ (int=100) - Maximum number of iterations
.. raw:: html
<details><summary><i> niter != 0 </i></summary>
- 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
.. raw:: html
</details>
- 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
.. raw:: html
<details><summary><i> usemask = user </i></summary>
- 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
.. raw:: html
</details>
.. raw:: html
<details><summary><i> usemask = pb </i></summary>
- pbmask_ (double=0.0) - primary beam mask
.. raw:: html
</details>
.. raw:: html
<details><summary><i> usemask = auto-multithresh </i></summary>
- 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
.. raw:: html
</details>
.. _Description:
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 <../casatasks.information.imhistory.html#casatasks.information.imhistory>`__.
.. rubric:: 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 <imagename_>`_ 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 <Correcting_Axes_>`_). All input 2D and 3D images must be regridded to a
4D CASA image prior to being supplied as input.
.. TODO uncomment in CAS-13570 once test_multirun_mtmfs3x passes
.. For deconvolving with the “mtmfs” deconvolver, most of the input images need to be the taylor series components of the
.. images as generated by **tclean**, including the psf, residual, model, and pb.
.. There must be `N` .residual, `N` .model (if included), `2*N-1` .psf, and `1` .pb (if included) images, where N=nterms.
.. This will result in `N` .image output images. Some example image names for the psf are imagename.psf.tt0,
.. imagename.psf.tt1, ..., imagename.psf.ttN.
.. rubric:: Iteration Control
The `niter parameter <niter_>`_ 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 <../../notebooks/synthesis_imaging.html#Iteration-Control>`__ .
.. rubric:: Interactive Mask
The `interactive parameter <interactive_>`_ 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.
.. rubric:: Return Value:
For niter >= 0, the **deconvolve** task returns a dictionary containing a summary of the run. The `fullsummary parameter <fullsummary_>`_ 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:
.. code-block:: python
{
'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
}
.. |nbsp| unicode:: 0xA0
:trim:
For more information on the return value from **tclean** and **deconvolve**, please refer to the notebook "`Synthesis Imaging <../../notebooks/synthesis_imaging.html#Returned-Dictionary>`__".
.. _Examples:
Examples
.. _Basic_Usage:
.. rubric:: Basic Usage
Build the '.image' image from the '.residual' and '.psf' images, as given by tclean or some other task.
.. code-block:: python
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:
.. TODO add mtmfs and asp
.. TODO "2D, 3D, and 4D images/cubes" => "2D, 3D, and 4D images/cubes and multi-term (for mtmfs)"
- 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
.. TODO uncomment in CAS-13570 once test_multirun_mtmfs3x passes
.. .. _Basic_Usage_with_MTMFS_Deconvolver:
.. .. rubric:: Basic Usage with MTMFS Deconvolver
..
.. Build the '.image.tt\*' images from the '.residual.tt\*' and '.psf.tt\*' images, as given by tclean or some other task. This
.. is an expansion on the `Basic Usage example <Basic_Usage_>`_, showing how the 'nterms' parameter affects the taylor terms
.. image generation.
..
.. .. code-block:: python
..
.. from casatools import ctsys
.. refim_path = ctsys.resolve('unittest/deconvolve/')
..
.. # remove the old run, as necessary
.. os.system("rm -rf try.*")
..
.. # Use tclean to generate our taylor term images. This should produce the images:
.. # try.psf.tt0...try.psf.tt4, try.residual.tt0...try.residual.tt2, try.pb.tt0
.. tclean(vis=refim_path + 'refim_point.ms', imagename='try', imsize=10, cell='8.0arcsec',
.. deconvolver='mtmfs', niter=0, restoration=False, calcres=True, nterms=3)
..
.. # Deconvolve with the same deconvolver and nterms. This should produce the images:
.. # try.model.tt0...try.model.tt2, try.image.tt0...try.image.tt2, try.residual.tt0...try.residual.tt2
.. ret=deconvolve(imagename='try', niter=10, deconvolver='mtmfs', nterms=3)
.. _Multiple_Runs:
.. rubric:: 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 <Basic_Usage_>`_.
.. code-block:: python
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:
.. rubric:: 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.
.. code-block:: python
###############################################################################
# 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:
.. rubric:: 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.
.. code-block:: python
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:
.. rubric:: 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:
.. code-block:: python
# 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:
.. rubric:: 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.
.. code-block:: python
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')
.. TODO uncomment in CAS-13570 once test_multirun_mtmfs3x passes
.. Note: the creation of PSFs this way only works for 2D/3D SD images/cubes. It does not work for Taylor-term images, such as
.. those generated by tclean(deconvolver='mtmfs'). The conversion from cube to Taylor-term inputs for use with deconvolve will
.. be demonstrated at a later time.
.. _Updating_Deconvolve_Scripts:
.. rubric:: 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 <Working_with_SD_Images_>`_.
For example, this:
.. code-block:: python
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:
.. code-block:: python
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:
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 <Multiple_Runs_>`_ 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).
.. warning:: The asp deconvolver is not currently considered reliable when used with task
deconvolve and is therefore disabled. Please use a different deconvolver.
.. _Details:
Parameter Details
Detailed descriptions of each function parameter
.. _imagename:
| ``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:
| ``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:
| ``deconvolver (string='hogbom')`` - Name of minor cycle algorithm (hogbom,clark,multiscale,mem,clarkstokes)
| 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
|
| asp : This deconvolver is not currently considered reliable when used with
| task deconvolve and is therefore disabled. Please choose a different
| deconvolver.
.. _scales:
| ``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:
| ``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:
| ``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.
.. _restoration:
| ``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:
| ``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:
| ``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:
| ``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:
| ``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:
| ``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:
| ``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:
| ``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:
| ``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:
| ``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:
| ``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:
| ``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:
| ``sidelobethreshold (double=3.0)`` - Sub-parameter for "auto-multithresh": mask threshold based on sidelobe levels:
| sidelobethreshold * max_sidelobe_level * peak residual
.. _noisethreshold:
| ``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:
| ``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:
| ``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:
| ``smoothfactor (double=1.0)`` - Sub-parameter for "auto-multithresh": smoothing factor in a unit of the beam
.. _minbeamfrac:
| ``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:
| ``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:
| ``growiterations (int=75)`` - Sub-parameter for "auto-multithresh": Maximum number of iterations to perform using binary dilation for growing the mask
.. _dogrowprune:
| ``dogrowprune (bool=True)`` - Experimental sub-parameter for "auto-multithresh": Do pruning on the grow mask
.. _verbose:
| ``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.
"""
pass