CASA Logo

CASA Documentation Archives

CASA Tasks

CASA Tasks

by Juergen Ott last modified 2017-06-27T10:36:49-04:00
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 <3>: tasklist
--------> tasklist()
Available tasks, organized by category (experimental tasks in parenthesis ()
deprecated tasks in curly brackets {}).


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

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

Visualization      Simulation         Single dish        Utility
------------------ ------------------ ------------------ ------------------
clearplot          simanalyze         asap_init          browsetable
imview             simobserve         importasap         caltabconvert
msview             (simalma)          sdaverage          clearplot
plotants                              sdbaseline         clearstat
plotbandpass                          sdbaseline2        concat
plotcal                               sdcal              conjugatevis
plotms                                sdcal2             find
plotprofilemap                        sdcoadd            help par.parameter
plotuv                                sdfit              help taskname
viewer                                sdflag             imview
(plotweather)                         sdflagmanager      msview
                                      sdgrid             plotms
                                      sdimaging          rmtables
                                      sdimprocess        startup
                                      sdlist             taskhelp
                                      sdmath             tasklist
                                      sdplot             testconcat
                                      sdreduce           toolhelp
                                      sdsave             virtualconcat
                                      sdscale
                                      sdstat
                                      (sdgaincal)
                                      (tsdbaseline)
                                      (tsdcal)
                                      (tsdfit)
                                      (tsdsmooth)

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

CASA <4>:

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 <4>: taskhelp
--------> taskhelp()
Available tasks:

accum             : Accumulate incremental calibration solutions into a calibration table
applycal          : Apply calibrations solutions(s) to data
asdmsummary       : Summarized description of an ASDM dataset.
autoclean         : CLEAN an image with automatically-chosen clean regions.
bandpass          : Calculates a bandpass calibration solution
blcal             : Calculate a baseline-based calibration solution (gain or bandpass)
boxit             : Box regions in image above given threshold value.
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
clearplot         : Clear the matplotlib plotter and all layers
clearstat         : Clear all autolock locks
concat            : Concatenate several visibility data sets.
conjugatevis      : Change the sign of the phases in all visibility columns.
csvclean          : This task does an invert of the visibilities and deconvolve in the image plane.
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
find              : Find string in tasks, task names, parameter names:
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
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
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
importevla        : Convert an Science Data Model observation into a CASA 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
mosaic            : Create a multi-field deconvolved image with selected algorithm
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
oldhanningsmooth  : Hanning smooth frequency channel data to remove Gibbs ringing
oldsplit          : Create a visibility subset from an existing visibility set
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.
plotuv            : Plot the baseline distribution
plotweather       : Plot elements of the weather table; estimate opacity.
polcal            : Determine instrumental polarization calibrations
predictcomp       : Make a component list for a known calibrator
rmfit             : Calculate rotation measure.
rmtables          : Remove tables cleanly, use this instead of rm -rf
sdaverage         : ASAP SD task: averaging and smoothing of spectra
sdbaseline        : Fit/subtract a spectral baseline
sdbaseline2       : Fit/subtract a spectral baseline
sdcal             : ASAP SD calibration task
sdcal2            : ASAP SD calibration task
sdcoadd           : Coadd multiple scantables into one
sdfit             : Fit a spectral line
sdflag            : ASAP SD spectral spectral/row flagging task
sdflagmanager     : ASAP SD task to manipulate flag version files
sdgaincal         : MS SD gain calibration task
sdgrid            : SD gridding task
sdimaging         : SD task: imaging for total power and spectral data
sdimprocess       : Task for single-dish image processing
sdlist            : list summary of single dish data
sdmath            : ASAP SD task for simple arithmetic of spectra
sdplot            : ASAP SD plotting task
sdreduce          : ASAP SD task: do sdcal, sdaverage, and sdbaseline in one task
sdsave            : Save the sd spectra in various format
sdscale           : Scale the sd spectra
sdstat            : list statistics of spectral
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 details of an image spectrum.
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.
ssoflux           : Fills the model column with the visibilities of a calibrator
statwt            : Reweight visibilities according to their scatter (Experimental)
tclean            : Radio Interferometric Image Reconstruction
tclean2           : Radio Interferometric Image Reconstruction
testconcat        : Concatenate the subtables of several visibility data sets, not the MAIN bulk data.
tsdbaseline       : Fit/subtract a spectral baseline
tsdcal            : MS SD calibration task
tsdfit            : Fit a spectral line
tsdsmooth         : Smooth 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 Measurement Set, or from a Multi-MS
visstat2          : Displays statistical information from a Measurement Set, or from a Multi-MS
widebandpbcor     : Wideband PB-correction on the output of the MS-MFS algorithm
widefield         : Wide-field imaging and deconvolution with selected 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
___________________________________________________________________


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','channel','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.

 

© 2016 NRAO

Contact Us