casashell

CASA shell environment for interactive Python-based analysis using CASA tasks.

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

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.

One may also invoke the tasks as follows:

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

Similar to the input as a function, the above invokation also calls the task with no arguments, and will thus use the global parameter values.

Alternatively, one can use inp/go to manually execute a task using an interface format. For example,

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

will execute plotms with the set values for the parameters, which will appear in the terminal when re-typing ‘inp’.

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.

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

Task Exceptions

If a task encounters an error casashell will raise an exception with the same traceback message as when the task is imported from casatasks and called outside of casashell. This will be the case regardless if the task is executed as a function call or by using go(). Users may prefer to limit the length of these traceback messages, for which we recommend setting:

sys.tracebacklimit=0

or by executing:

%xmode minimal

from within either casashell or IPython. This will greatly limit the size of the traceback while preserving the text of the exception. The above commands can be typed into the casashell terminal after CASA starts, or added to startup.py to run automatically each time CASA starts. Note that to use the IPython magic command xmode in startup.py it would need to be formatted as:

get_ipython().run_line_magic('xmode','minimal')

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()

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

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

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). Some task parameters accept a specific string from a collection of possible strings. These parameters are generally case sensitive, but sometimes both fully upper and fully lower case versions of the same string may be accepted (i.e. datacolumn='data' or 'DATA'). When in doubt, use the case specified in the default setting of that parameter.

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')

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

CASA <36>: combine
Out[14]: 'scan'

The scope of parameters in CASA

By default the scope of CASA parameters is global. 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, 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. 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.

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

CASA <26>: inp tclean
---------> inp(tclean)
---------> inp(tclean)
# tclean -- Radio Interferometric Image Reconstruction
vis = 'ngc5921.demo.src.split.ms.contsub' # Name of input visibility file(s)
selectdata = True # Enable data selection parameters
field = '0' # field(s) to select
spw = '' # spw(s)/channels to select
timerange = '' # Range of time to select from data
uvrange = '' # Select data within uvrange
antenna = '' # Select data based on antenna/baseline
scan = '' # Scan number range
observation  = '' # Observation ID range
intent = '' # Scan Intent(s)
datacolumn = 'corrected' # Data column to image(data,corrected)
imagename = 'ngc5921.demo.cleaning' # Pre-name of output images
imsize = [] # Number of pixels
cell = [15.0, 15.0] # Cell size
...

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

CASA <27>: default()

CASA <28>: inp()
# tclean -- Radio Interferometric Image Reconstruction
vis = '' # Name of input visibility file(s)
selectdata = True # Enable data selection parameters
field = '' # field(s) to select
spw = '' # spw(s)/channels to select
timerange = '' # Range of time to select from data
uvrange = '' # Select data within uvrange
antenna = '' # Select data based on antenna/baseline
scan = '' # Scan number range
observation = '' # Observation ID range
intent = '' # Scan Intent(s)
datacolumn = 'corrected' # Data column to image(data,corrected)
imagename = '' # Pre-name of output images
imsize = [] # Number of pixels
cell = [] # Cell size
...

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

Warning

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

CASA 6 internally promotes integers to doubles, and for tasks CASA 6 ensures that the parameter values are converted to the internally acceptable type.

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>: tget("listobs")

or (since the current active task is listobs)

CASA <19>: tget

or

CASA <20>: run listobs.last

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