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 or ? at the CASA prompt, where is the name of a given task. As described in "Getting Help in CASA", help  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.

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.

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

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,

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.

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 = arguments, or as a series of comma delimited 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:

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.

or

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,

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

or

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

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:

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:

as we did above.

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

The scope of parameters in CASA

 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:

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,

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.

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

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

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

The go() Command

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

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

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

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

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(’’) or inp(), without parentheses inp ’’ or inp , or using the current taskname variable setting with inp(). For example,

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,

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.

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

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’).

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.

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,

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

For example, starting from default values

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

and we are back.

An example save to a custom named file:

 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 will recover values for the specified task. This is done by searching for 1) a .last file (see below), then for 2) a .saved file (see above), and then executing the Python in these files.

For example,

The tput Command

The tput command will save the current parameter values of a task to its .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 will save the values for the specified task.

For example,

The .last file

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

You can restore the parameter values from the save file using