CASA Tasks

Summary of CASA tasks

What Tasks are Available?

Tasks in CASA are python interfaces to the more basic toolkit. Tasks are executed to perform a single job, such as loading, plotting, flagging, calibrating, and imaging the data.

The parameters used and their defaults can be obtained by typing help <taskname> or <taskname>? at the CASA prompt, where <taskname> is the name of a given task. As described in "Getting Help in CASA", help <taskname> lists all parameters, a brief description of the parameter, the parameter default, and any options if there are limited allowed values for the parameter. For more information the CASAdocs helpsystem (what you are browsing right now) should be used. 

To see what tasks are available in CASA, see the Global Task List. In CASA, one can use the tasklist command for a listing by category, e.g.

CASA <4>: tasklist
--------> tasklist()
Available tasks, organized by category (experimental tasks in parenthesis ()
deprecated tasks in curly brackets {}).


Import/export      Information        Editing            Manipulation
------------------ ------------------ ------------------ ------------------
exportasdm         asdmsummary        fixplanets         concat
exportfits         imhead             fixvis             conjugatevis
exportuvfits       imreframe          flagcmd            cvel
importasap         imstat             flagdata           fixvis
importasdm         imval              flagmanager        hanningsmooth
importatca         listcal            msview             imhead
importfits         listfits           plotms             mstransform
importfitsidi      listhistory                           oldstatwt
importmiriad       listobs                               partition
importnro          listpartition                         plotms
importuvfits       listsdm                               split
importvla          listvis                               testconcat
(importgmrt)       makemask                              uvcontsub
                   plotms                                virtualconcat
                   vishead                               vishead
                   visstat                               (cvel2)
                                                         (uvcontsub3)

Calibration        Modeling           Imaging            Analysis
------------------ ------------------ ------------------ ------------------
accum              predictcomp        clean              imcollapse
applycal           setjy              deconvolve         imcontsub
bandpass           uvcontsub          feather            imdev
blcal              uvmodelfit         ft                 imfit
calstat            uvsub              imcontsub          imhead
clearcal.          (uvcontsub3)       tclean             imhistory
delmod                                (widebandpbcor)    immath
fixplanets                                               immoments
fluxscale                                                impbcor
ft                                                       impv
gaincal                                                  imrebin
gencal                                                   imreframe
initweights                                              imregrid
listcal                                                  imsmooth
plotants                                                 imstat
plotbandpass                                             imsubimage
plotcal                                                  imtrans
polcal                                                   imval
predictcomp                                              listvis
rerefant                                                 rmfit
setjy                                                    slsearch
smoothcal                                                specfit
uvmodelfit                                               specsmooth
uvsub                                                    splattotable
wvrgcal                                                  spxfit
(accor)                                                  (specflux)
(fringefit)
(msuvbin)

Visualization      Simulation         Single dish        Utility
------------------ ------------------ ------------------ ------------------
imview             simalma            importasap         browsetable
msview.            simanalyze         importnro.         caltabconvert
plotants           simobserve         sdbaseline         clearstat
plotbandpass                          sdcal              concat
plotcal                               sdfit              conjugatevis
plotms                                sdfixscan          help par.parameter
plotprofilemap                        sdgaincal          help taskname
plotweather                           sdimaging          imview
viewer                                sdsmooth.          msview
                                      (sdsidebandsplit)  plotms
                                      (tsdimaging)       rmtables
                                                         startup
                                                         taskhelp
                                                         tasklist
                                                         testconcat
                                                         toolhelp
                                                         virtualconcat

User defined tasks
------------------

CASA <5>:

The tasks with name in parentheses () are experimental, those in curly brackets {} are deprecated and will be removed in future releases. The functionality of deprecated tasks is usually available in some other task (e.g., instead of mosaic one should use clean). In the above case, the user has not defined any task him/herself.

 

Typing taskhelp provides a one line description of all available tasks.

CASA <6>: taskhelp
--------> taskhelp()
Available tasks:

accor           : Normalize visibilities based on auto-correlations
accum           : Accumulate incremental calibration solutions into a calibration table
applycal        : Apply calibrations solutions(s) to data
asdmsummary     : Summarized description of an ASDM dataset.
bandpass        : Calculates a bandpass calibration solution
blcal           : Calculate a baseline-based calibration solution (gain or bandpass)
browsetable     : Browse a table (MS, calibration table, image)
calstat         : Displays statistical information on a calibration table
caltabconvert   : Convert old-style caltables into new-style caltables.
clean           : Invert and deconvolve images with selected algorithm
clearcal        : Re-initializes the calibration for a visibility data set
clearstat       : Clear all autolock locks
concat          : Concatenate several visibility data sets.
conjugatevis    : Change the sign of the phases in all visibility columns.
cvel            : regrid an MS to a new spectral window / channel structure or frame
cvel2           : Regrid an MS or MMS to a new spectral window, channel structure or frame
deconvolve      : Image based deconvolver
delmod          : Deletes model representations in the MS
exportasdm      : Convert a CASA visibility file (MS) into an ALMA or EVLA Science Data Model
exportfits      : Convert a CASA image to a FITS file
exportuvfits    : Convert a CASA visibility data set to a UVFITS file:
feather         : Combine two images using their Fourier transforms
fixplanets      : Changes FIELD and SOURCE table entries based on user-provided direction or POINTING table, optionally fixes the UVW coordinates
fixvis          : Recalculates (u, v, w) and/or changes Phase Center
flagcmd         : Flagging task based on batches of flag-commands
flagdata        : All-purpose flagging task based on data-selections and flagging modes/algorithms.
flagmanager     : Enable list, save, restore, delete and rename flag version files.
fluxscale       : Bootstrap the flux density scale from standard calibrators
fringefit       : Fringe fit delay and rates
ft              : Insert a source model  a visibility set:
gaincal         : Determine temporal gains from calibrator observations
gencal          : Specify Calibration Values of Various Types
hanningsmooth   : Hanning smooth frequency channel data to remove Gibbs ringing
imcollapse      : Collapse image along one axis, aggregating pixel values along that axis.
imcontsub       : Estimates and subtracts continuum emission from an image cube
imdev           : Create an image that can represent the statistical deviations of the input image.
imfit           : Fit one or more elliptical Gaussian components on an image region(s)
imhead          : List, get and put image header parameters
imhistory       : Retrieve and modify image history
immath          : Perform math operations on images
immoments       : Compute moments from an image
impbcor         : Construct a primary beam corrected image from an image and a primary beam pattern.
importasap      : Convert ASAP Scantable data  into a CASA visibility file (MS)
importasdm      : Convert an ALMA Science Data Model observation into a CASA visibility file (MS)
importatca      : Import ATCA RPFITS file(s) to a measurement set
importfits      : Convert an image FITS file into a CASA image
importfitsidi   : Convert a FITS-IDI file to a CASA visibility data set
importgmrt      : Convert a UVFITS file to a CASA visibility data set
importmiriad    : Convert a Miriad visibility file into a CASA MeasurementSet
importnro       : Convert NOSTAR data into a CASA visibility file (MS)
importuvfits    : Convert a UVFITS file to a CASA visibility data set
importvla       : Import VLA archive file(s) to a measurement set
impv            : Construct a position-velocity image by choosing two points in the direction plane.
imrebin         : Rebin an image by the specified integer factors
imreframe       : Change the frame in which the image reports its spectral values
imregrid        : regrid an image onto a template image
imsmooth        : Smooth an image or portion of an image
imstat          : Displays statistical information from an image or image region
imsubimage      : Create a (sub)image from a region of the image
imtrans         : Reorder image axes
imval           : Get the data value(s) and/or mask value in an image.
imview          : View an image
initweights     : Initializes weight information in the MS
listcal         : List antenna gain solutions
listfits        : List the HDU and typical data rows of a fits file:
listhistory     : List the processing history of a dataset:
listobs         : List the summary of a data set in the logger or in a file
listpartition   : List the summary of a multi-MS data set in the logger or in a file
listsdm         : Lists observation information present in an SDM directory.
listvis         : List measurement set visibilities.
makemask        : Makes and manipulates image masks
mstransform     : Split the MS, combine/separate/regrid spws and do channel and time averaging
msuvbin         : grid the visibility data onto a defined uniform grid (in the form of an ms); multiple MS's can be done onto the same grid
msview          : View a visibility data set
oldsplit        : Create a visibility subset from an existing visibility set
oldstatwt       :  Reweight visibilities according to their scatter (Experimental)
partition       : Task to produce Multi-MSs using parallelism
plotants        : Plot the antenna distribution in the local reference frame:
plotbandpass    : Makes detailed plots of Tsys and bandpass solutions.
plotcal         : An all-purpose plotter for calibration results
plotms          : A plotter/interactive flagger for visibility data.
plotprofilemap  : Makes profile map.
plotweather     : Plot elements of the weather table; estimate opacity.
polcal          : Determine instrumental polarization calibrations
predictcomp     : Make a component list for a known calibrator
rerefant        : Re-apply refant to a caltable
rmfit           : Calculate rotation measure.
rmtables        : Remove tables cleanly, use this instead of rm -rf
sdbaseline      : Fit/subtract a spectral baseline
sdcal           :  MS SD calibration task
sdfit           : Fit a spectral line
sdfixscan       : Task for single-dish image processing
sdgaincal       :  MS SD gain calibration task
sdimaging       : SD task: imaging for total power and spectral data
sdsidebandsplit : [EXPERIMENTAL] invoke sideband separation using FFT
sdsmooth        : Smooth spectral data
setjy           : Fills the model column with the visibilities of a calibrator
simalma         : Simulation task for ALMA
simanalyze      : image and analyze measurement sets created with simobserve
simobserve      : visibility simulation task
slsearch        : Search a spectral line table.
smoothcal       : Smooth calibration solution(s) derived from one or more sources:
specfit         : Fit 1-dimensional gaussians and/or polynomial models to an image or image region
specflux        : Report spectral profile and calculate spectral flux over a user specified region
specsmooth      : Smooth an image region in one dimension
splattotable    : Convert a downloaded Splatalogue spectral line list to a casa table.
split           : Create a visibility subset from an existing visibility set
spxfit          : Fit a 1-dimensional model(s) to an image(s) or region for determination of spectral index.
statwt          : Compute and set weights based on variance of data.
tclean          : Radio Interferometric Image Reconstruction
tclean2         : Radio Interferometric Image Reconstruction
testconcat      : Concatenate the subtables of several visibility data sets, not the MAIN bulk data.
tsdimaging      : SD task: imaging for total power and spectral data
uvcontsub       : Continuum fitting and subtraction in the uv plane
uvcontsub3      : An experimental clone of uvcontsub
uvmodelfit      : Fit a single component source model to the uv data
uvsub           : Subtract/add model from/to the corrected visibility data.
viewer          : View an image or visibility data set
virtualconcat   : Concatenate several visibility data sets into a multi-MS
vishead         : List, summary, get, and put metadata in a measurement set
visstat         : Displays statistical information from a MeasurementSet, or from a Multi-MS
widebandpbcor   : Wideband PB-correction on the output of the MS-MFS algorithm
wvrgcal         : Generate a gain table based on Water Vapour Radiometer data

 

Typing startup will provide the startup page displayed when entering CASA. The startup screen lists the various options to obtain help within CASA.

CASA <26>: startup
---------> startup()
___________________________________________________________________
For help use the following commands:
tasklist - Task list organized by category
taskhelp - One line summary of available tasks
help taskname - Full help for task
toolhelp - One line summary of available tools
help par.parametername - Full help for parameter name
___________________________________________________________________


Running Tasks and Tools

Tools are functions linked to the Python interface which must be called by name with arguments. Tasks have higher-level capabilities than tools. Tasks require input parameters which maybe be specified when you call the task as a function, or be set as parameters in the interface. A task, like a tool, is a function under Python and may be written in Python, C, or C++ (the CASA toolkit is made up of C++ functions).

There are two distinct ways to run tasks. You can either set the global CASA parameters relevant to the task and tell the task to go(), or you can call the task as a function with one or more arguments specified. These two invocation methods differ in whether the global parameter values are used or not.

For example,

default('plotms')
vis='ngc5921.ms'
xaxis='channel'
yaxis='amp'
datacolumn='data'
go()

will execute plotms with the set values for the parameters (see "Plotms"). Instead of using the go() command to invoke the task, you can also call the task with no arguments, e.g.

default('plotms')
vis='ngc5921.ms'
xaxis='channel'
yaxis='amp'
datacolumn='data'
plotms()

which will also use the global parameter values.

Second, one may call tasks and tools by name with parameters set on the same line. Parameters may be set either as explicit <parameter>=<value> arguments, or as a series of comma delimited <value>s in the correct order for that task or tool. Note that missing parameters will use the default values for that task. For example, the following are equivalent:

#Specify parameter names for each keyword input:
plotms(vis='ngc5921.ms',xaxis='channel',yaxis='amp',datacolumn='data')
# when specifying the parameter name, order doesn't matter, e.g.:
plotms(xaxis='channel',vis='ngc5921.ms',datacolumn='data',yaxis='amp')
# use parameter order for invoking tasks
plotms('ngc5921.ms',1,1,0,0,0,'channel','data','amp','data')


This non-use of globals when calling as a function is so that robust scripts can be written. One need only cut-and-paste the calls and need not worry about the state of the global variables or what has been run previously. It is also more like the standard behavior of function calls in Python and other languages.

Tools can only be called in this second manner by name, with arguments ("CASA Tools"). Tools never use the global parameters and the related mechanisms of inp() and go().

 

Aborting Tasks

If you are running CASA tasks, you can usually use CTRL-C to abort execution of the task. If this does not work, try CTRL-Z followed by a kill. See ("Starting CASA") for more on these methods to abort CASA execution.

You may have to quit and restart CASA after an abort, as the internal state can get mixed up.

 

Getting Return Values

Some tasks and tools return a record (usually a Python dictionary) to the interface. For example, the imstat task returns a dictionary with the image statistics in it. To catch these return values into a Python variable, you MUST assign that variable to the task call, e.g.

xstat = imstat('ngc5921.clean.image')

or

default('imstat')
imagename = 'ngc5921.clean.image'
xstat = imstat()

Note that tools that return values work in the same way ("CASA Tools").

You can print or use the return value in Python for controlling scripts. For example,

CASA <1>: xstat = imstat('ngc5921.clean.image')
CASA <2>: xstat
Out[2]:
{'blc': array([0, 0, 0, 0]),
'blcf': '15:24:08.404, +04.31.59.181, I, 1.41281e+09Hz',
'flux': array([ 4.15292207]),
'max': array([ 0.05240594]),
'maxpos': array([134, 134, 0, 38]),
'maxposf': '15:21:53.976, +05.05.29.998, I, 1.41374e+09Hz',
'mean': array([ 1.62978083e-05]),
'medabsdevmed': array([ 0.00127287]),
'median': array([ -1.10467618e-05]),
'min': array([-0.0105249]),
'minpos': array([160, 1, 0, 30]),
'minposf': '15:21:27.899, +04.32.14.923, I, 1.41354e+09Hz',
'npts': array([ 3014656.]),
'quartile': array([ 0.00254587]),
'rms': array([ 0.00201818]),
'sigma': array([ 0.00201811]),
'sum': array([ 49.1322855]),
'sumsq': array([ 12.27880404]),
'trc': array([255, 255, 0, 45]),
'trcf': '15:19:52.390, +05.35.44.246, I, 1.41391e+09Hz'}
CASA <3>: myrms = xstat['rms'][0]
CASA <4>: print 10.0*myrms
0.0201817648485

If you do not catch the return variable, it will be lost

imstat('ngc5921.clean.image')

or

default('imstat')
imagename = 'ngc5921.clean.image'
imstat()

and spewed to terminal. Note that go() will trap and lose the return value, e.g.

default('imstat')
imagename = 'ngc5921.clean.image'
go()

will not dump the return to the terminal either.

 

 

Setting Parameters and Invoking Tasks

Inside the Toolkit:
In the current version of CASA, you cannot use the task parameter setting features, such as the inp(), default(), or go() commands, for the tools.

One can set parameters for tasks (but not for tools) by performing the assignment within the CASA shell and then inspecting them using the inp() command:

CASA <30>: default(bandpass)
CASA <31>: vis = 'ngc5921.demo.ms'
CASA <32>: caltable = 'ngc5921.demo.bcal'
CASA <33>: field = '0'
CASA <34>: refant = '15'
CASA <35>: inp('bandpass')

# bandpass :: Calculates a bandpass calibration solution
vis = 'ngc5921.demo.ms'        # Name of input visibility file
caltable = 'ngc5921.demo.bcal' # Name of output gain calibration table
field = '0'                    # Select field using field id(s) or field
                               # name(s)
spw = ''                       # Select spectral window/channels
intent = ''                    # Select observing intent
selectdata = True              # Other data selection parameters
timerange = ''                 # Select data based on time range
uvrange = ''                   # Select data within uvrange (default units
                               # meters)
antenna = ''                   # Select data based on antenna/baseline
scan = ''                      # Scan number range
observation = ''               # Select by observation ID(s)
msselect = ''                  # Optional complex data selection (ignore for
                               # now)

solint = 'inf'                 # Solution interval in time[,freq]
combine = 'scan'               # Data axes which to combine for solve (obs,
                               # scan, spw, and/or field)
refant = '15'                  # Reference antenna name(s)
minblperant = 4                # Minimum baselines _per antenna_ required for
                               # solve
minsnr = 3.0                   # Reject solutions below this SNR (only applies
                               # for bandtype = B)
solnorm = False                # Normalize average solution amplitudes to 1.0
bandtype = 'B'                 # Type of bandpass solution (B or BPOLY)
fillgaps = 0                   # Fill flagged solution channels by
                               # interpolation

smodel = []                    # Point source Stokes parameters for source
                               # model.
append = False                 # Append solutions to the (existing) table
docallib = False               # Use callib or traditional cal apply
                               # parameters
gaintable = []                 # Gain calibration table(s) to apply on the fly
gainfield = []                 # Select a subset of calibrators from
                               # gaintable(s)
interp = []                    # Interpolation mode (in time) to use for each
                               # gaintable
spwmap = []                    # Spectral windows combinations to form for
                               # gaintables(s)

parang = False                 # Apply parallactic angle correction

 

See below for more details on the use of the inputs command.

All task parameters have global scope within CASA: the parameter values are common to all tasks and also at the CASA command line. This allows the convenience of not changing parameters that are shared between tasks but does require care when chaining together sequences of task invocations (to ensure proper values are provided).

If you want to reset the input keywords for a single task, use the default() command. For example, to set the defaults for the bandpass task, type:

CASA <30>: default('bandpass')

as we did above.

To inspect a single parameter value just type it at the command line. Continuing the above example:

CASA <36>: combine
Out[14]: 'scan'
CASA parameters are just Python variables.

Parameters for a given task can be saved by using the saveinputs command and restored using the execfile ’<filename>’ command. Note that if the task is successfully executed, then a <taskname>.last file is created in the working directory containing the parameter values (see below).
 
We now describe the individual CASA task parameter interface commands and features in more detail.

 

The scope of parameters in CASA

Advanced Tip
By default, the scope of CASA parameters is global, as stated here. However, if you call a task as a function with one or more arguments specified, e.g. task(arg1=val1,...), then non-specified parameters will be defaulted and no globals used. This makes scripting more robust. Tasks DO NOT change the value of globals. All task parameters have global scope within CASA: the parameter values are common to all tasks and also at the CASA command line. This allows the convenience of not changing parameters that are shared between tasks but does require care when chaining together sequences of task invocations (to ensure proper values are provided). Tasks DO NOT change the values of the global parameters, nor does the invocation of tasks using the functional call with arguments change the globals.

 This does mean that unless you do an explicit default of the task (see next section), previously set values may be unexpectedly used if you do not inspect the inp() carefully. For example, good practice is:

default('imhead')
imagename = 'ngc5921.demo.cleanimg.image'
mode = 'list'
imhead()

If you supply the task call with arguments, then these will be used for the values of those parameters (see above). However, if some but not all arguments are supplied, then those parameters not given as arguments will default and NOT use the current global values. Thus,

imhead('ngc5921.demo.cleanimg.image',mode='list')
will reproduce the above.
 

The default() Command 

Each task has a special set of default parameters defined for its parameters. You can use the default() command to reset the parameters for a specified task (or the current task as defined by the taskname variable) to their default.

Important Note: The default() command resets the values of the task parameters to a set of “defaults” as specified in the task code. Some defaults are blank strings ’’ or empty lists [], others are specific numerical values, strings, or lists. It is important to understand that just setting a string parameter to an empty string ’’ is not setting it to its default! Some parameters do not have a blank as an allowed value. See the help for a particular task to find out its default. If ’’ is the default or an allowed value, it will say so explicitly.

For example, suppose we have been running CASA on a particular dataset, e.g.

CASA <40>: inp clean
---------> inp('clean')
# clean :: Deconvolve an image with selected algorithm
vis = 'ngc5921.demo.src.split.ms.contsub' # name of input visibility file
imagename = 'ngc5921.demo.cleanimg'       # Pre-name of output images
field = '0'                               # Field Name
spw = ''                                  # Spectral windows:channels: '' is all
selectdata = False                        # Other data selection parameters
mode = 'channel'                          # Type of selection (mfs, channel, velocity, frequency)
nchan = 46                                # Number of channels (planes) in output image
start = 5                                 # first input channel to use
width = 1                                 # Number of input channels to average
interpolation = 'nearest'                 # Spectral interpolation (nearest, linear, cubic)
niter = 6000                              # Maximum number of iterations
...

and now we wish to switch to a different one. We can reset the parameter values using default():

CASA <41>: default()
---------> default()

CASA <42>: inp()
---------> inp()
# clean :: Deconvolve an image with selected algorithm
vis = ''           # name of input visibility file
imagename = ''     # Pre-name of output images
field = ''         # Field Name
spw = ''           # Spectral windows:channels: '' is all
selectdata = False # Other data selection parameters
mode = 'mfs'       # Type of selection (mfs, channel, velocity, frequency)
niter = 500        # Maximum number of iterations
...


It is good practice to use default() before running a task if you are unsure what state the CASA global variables are in.

ALERT: You can only reset ALL of the parameters for a given task to their defaults. 

 

The go() Command

 You can execute a task using the go() command, either explicitly

CASA <44>: go listobs
---------> go(listobs)
Executing: listobs()
...

or implicitly if taskname is defined (e.g. by previous use of default() or inp() )

CASA <45>: taskname = 'clean'
CASA <46>: go()
---------> go()
Executing: clean()
...


You can also execute a task simply by typing the taskname.

CASA <46>: clean
---------> clean()
Executing: clean()
...


The go() command can also be used to launch a different task without changing the current taskname, without disrupting the inp() process on the current task you are working on. For example

default 'gaincal'   # set current task to gaincal and default
vis = 'n5921.ms'    # set the working ms
...                 # set some more parameters
go listobs          # launch listobs w/o changing current task
inp()               # see the inputs for gaincal (not listobs!)

ALERT: Doing go listobs(vis=’foo.ms’) will currently change the taskname, and will change vis, which might not be what is desired.

 

The inp() Command

You can set the values for the parameters for tasks (but currently not for tools) by performing the assignment within the CASA shell and then inspecting them using the inp() command. This command can be invoked in any of three ways: via function call inp(’<taskname>’) or inp(<taskname>), without parentheses inp ’<taskname>’ or inp <taskname>, or using the current taskname variable setting with inp(). For example,

CASA <1>: inp('clean')
...
CASA <2>: inp 'clean'
----------> inp('clean')
...
CASA <3>: inp(clean)
...
CASA <4>: inp clean
----------> inp(clean)
...
CASA <5>: taskname = 'clean'
CASA <6>: inp()
----------> inp()

all do the same thing.

When you invoke the task inputs via inp(), you see a list of the parameters, their current values, and a short description of what that parameters does. For example, starting from the default values,

CASA <18>: inp('clean')
# clean :: Deconvolve an image with selected algorithm
vis = ''                          # name of input visibility file
imagename = ''                    # Pre-name of output images
field = ''                        # Field Name
spw = ''                          # Spectral windows:channels: '' is all
selectdata = False                # Other data selection parameters
mode = 'mfs'                      # Type of selection (mfs, channel, velocity, frequency)
niter = 500                       # Maximum number of iterations
gain = 0.1                        # Loop gain for cleaning
threshold = '0.0mJy'              # Flux level to stop cleaning. Must include units
psfmode = 'clark'                 # method of PSF calculation to use during minor cycles
imagermode = ''                   # Use csclean or mosaic. If '', use psfmode
multiscale = []                   # multi-scale deconvolution scales (pixels)
interactive = False               # use interactive clean (with GUI viewer)
mask = []                         # cleanbox(es), mask image(s), and/or region(s)
imsize = [256, 256]               # x and y image size in pixels
cell = ['1.0arcsec', '1.0arcsec'] # x and y cell size. default unit arcsec
phasecenter = ''                  # Image phase center: position or field index
restfreq = ''                     # rest frequency to assign to image (see help)
stokes = 'I'                      # Stokes params to image (eg I,IV, QU,IQUV)
weighting = 'natural'             # Weighting of uv (natural, uniform, briggs, ...)
uvtaper = False                   # Apply additional uv tapering of visibilities.
modelimage = ''                   # Name of model image(s) to initialize cleaning
restoringbeam = ['']              # Output Gaussian restoring beam for CLEAN image
pbcor = False                     # Output primary beam-corrected image
minpb = 0.1                       # Minimum PB level to use

The Figure below shows how this will look to you on your terminal. Note that some parameters are in boldface with a gray background. This means that some values for this parameter will cause it to expand, revealing new sub-parameters to be set.

Type Figure
ID casatasks-fig-default
Caption Screen shot of the default CASA inputs for task clean.


CASA uses color and font to indicate different properties of parameters and their values:

Text Font

Text Color

Highlight

Indentation

Meaning

Parameters:

       
plain black none none standard parameter
bold black grey none expandable parameter
plain green none yes sub-parameter

Values:

       
plain black none none default value
plain blue none none non-default value
plain red none none invalid value
Type Table
ID casatasks-tab-colors
Caption Parameter and Values in CASA

The Figure below shows what happens when you set some of the clean parameters to non-default values. Some have opened up sub-parameters, which can now be seen and set. The Figure thereafter shows what happens when you set a parameter, in this case vis and mode, to an invalid value. Its value now appears in red. Reasons for invalidation include incorrect type, an invalid menu choice, or a filename that does not exist. For example, since vis expects a filename, it will be invalidated (red) if it is set to a non-string value, or a string that is not the name of a file that can be found. The mode=’happy’ is invalid because it’s not a supported choice (’mfs’, ’channel’, ’velocity’, or ’frequency’).

Type Figure
ID casatsks-fig-setvalues
Caption The clean inputs after setting values away from their defaults (blue text). Note that some of the boldface ones have opened up new dependent sub-parameters (indented and green).


Type Figure
ID casatasks-fig-setwrong
Caption The clean inputs where one parameter has been set to an invalid value. This is drawn in red to draw attention to the problem. This hapless user probably confused the ’hogbom’ clean algorithm with Harry Potter.

 

The saveinputs Command 

The saveinputs command will save the current values of a given task parameters to a Python (plain ascii) file. It can take up to two arguments, e.g.

saveinputs(taskname, outfile)

The first is the usual taskname parameter. The second is the name for the output Python file. If there is no second argument, for example,

saveinputs('clean')

a file with name <taskname>.saved (in this case ’clean.saved’ will be created or overwritten if extant. If invoked with no arguments, e.g.
saveinputs


it will use the current values of the taskname variable (as set using inp <taskname> or default <taskname>). You can also use the taskname global parameter explicitly,

saveinputs(taskname, taskname+'_1.save')

For example, starting from default values

CASA <1>: default('listobs')
CASA <2>: vis='ngc5921.demo.ms'
CASA <3>: saveinputs
CASA <4>: !more 'listobs.saved'
taskname = "listobs"
vis = "ngc5921.demo.ms"
selectdata = True
spw = ""
field = ""
antenna = ""
uvrange = ""
timerange = ""
correlation = ""
scan = ""
intent = ""
feed = ""
array = ""
observation = ""
verbose = True
listfile = ""
#listobs(vis="ngc5921.demo.ms",selectdata=True,spw="",field="",
antenna="",uvrange="",timerange="",correlation="",scan="",intent="",
feed="",array="",observation="",verbose=True,listfile="")

 

To read these back in, use the Python execfile command. For example,

CASA <5>: execfile('listobs.saved')

and we are back.

An example save to a custom named file:

saveinputs('listobs','ngc5921_listobs.par')

 You can also use the CASA tget command (see next section) instead of the Python execfile to restore your inputs.

 

The tget Command

The tget command will recover saved values of the inputs of tasks. This is a convenient alternative to using the Python execfile command (see above).

Typing tget without a taskname will recover the saved values of the inputs for the current task as given in the current value of the taskname parameter.

Adding a task name, e.g. tget <taskname> will recover values for the specified task. This is done by searching for 1) a <taskname>.last file (see below), then for 2) a <taskname>.saved file (see above), and then executing the Python in these files.

For example,

default('gaincal') # set current task to gaincal and default
tget               # read saved inputs from gaincal.last (or gaincal.saved)
inp()              # see these inputs!
tget bandpass      # now get from bandpass.last (or bandpass.saved)
inp()              # task is now bandpass, with recovered inputs

 

The tput Command

The tput command will save the current parameter values of a task to its <taskname>.last file. This is a shorthand to saveinputs and is a counterpart to tget.

Typing tput without a taskname will save the values of the inputs for the current task as given in the current value of the taskname parameter.

Adding a task name, e.g. tget <taskname> will save the values for the specified task.

For example,

default('gaincal') # set current task to gaincal and default
tget               # read saved inputs from gaincal.last (or gaincal.saved)
inp()              # see these inputs!
vis = 'new.ms'     # change the vis parameter
tput               # save back to the gaincal.last file for later use


The .last file

Whenever you successfully execute a CASA task, a Python script file called <taskname>.last will be written (or over-written) into the current working directory. For example, if you ran the listobs task as detailed above, then

CASA <14>: vis = 'ngc5921.ms'

CASA <15>: verbose = True

CASA <16>: listobs()

CASA <17>: !more 'listobs.last'
IPython system call: more listobs.last
taskname = "listobs"
vis = "ngc5921.ms"
verbose = True
listfile = ""
#listobs(vis="ngc5921.ms",verbose=False,listfile="")

You can restore the parameter values from the save file using

CASA <18>: execfile('listobs.last')
or
CASA <19>: run listobs.last

Note that the .last file in generally not created until the task actually finished (successfully), so it is often best to manually create a save file beforehand using the saveinputs command if you are running a critical task that you strongly desire to have the inputs saved for.