CASA Task Analysis Cookbook

_Version: mjc sometime in feb 07

Concise Table of Contents

Introduction

This document describes how to calibrate and image interferometric data using tasks from the CASA (Common Astronomy Software Application) package (single-dish analysis will be incorporated in this document at a later date). CASA is a suite of astronomical data reduction tools and tasks that can be run via the IPython interface to Python. Tools in CASA provide the full capability of the package. Tasks are essentially IPython interface scripts to the tools, but with specific, limited access to them. The idea for having tasks is that they are simpler to use, provide a more familiar interface, and are easier to learn for most astronomers who are familiar with radio interferometric data reduction (and hopefully for novice users as well). Currently, CASA is in an alpha release and this should be taken into account as users begin to learn the package.

For the moment, the audience is assumed to have some basic grasp of the fundamentals of synthesis imaging, so details of how a radio interferometer works and why the data needs to undergo calibration in order to make synthesis images are left to other documentation --- a good place to start might be Synthesis Imaging in Radio Astronomy II (1999, ASP Conference Series Vol. 180, eds. Taylor, Carilli & Perley).

Finally, this document provides some examples of executing tasks in CASA and what might be expected during and at the end of such execution. These examples are found in Appendix 1.

Current CASA documentation consists of:

If you have experience with CLIC, AIPS, or MIRIAD software packages to reduce interferometric data, Appendices 2--4 provide CLIC-CASA, AIPS-CASA, and MIRIAD-CASA dictionaries which map common CLIC, AIPS and MIRIAD tasks/adverbs to their counterparts in CASA.

CASA Basics --- Useful Information for First-Time Users

Starting CASA

After having run the appropriate casainit script, CASA is started by typing casapy on the command line. After startup information, you should see the casapy command prompt: CASA <1>:

Ending CASA

You can exit CASA by typing CTRL-D, %exit, or quit.

Python

Within CASA, you use python to interact with the system. This does not mean an extensive python course is necessary - basic interaction with the system (assigning parameters, running tasks) is straightforward. At the same time, the full potential of python is at the more experienced user's disposal. Some further details about python, ipython, and the interaction between python and CASA can be found here.

Tools and Tasks

Tools

Originally, CASA consisted of a collection of tools, combined in the so-called toolkit. Since the majority of prospective users is far more familiar with the concept of tasks, an effort is underway to replace most - if not all - toolkit functionality by tasks.

Tasks

While running CASA, you will have access to and be interacting with tasks, either indirectly by providing parameters to a task, or directly by running a task. Each task has a well defined purpose, and a number of associated parameters, the values of which are to be supplied by the user. Technically speaking, tasks are built on top of tools - when you are running a task, you are running tools in the toolkit, though this should be transparent.

What does this mean for the normal user?

As more tasks are being written, and the functionality of each task is enhanced, there will be less and less reason to run tools in the toolkit. We are working toward a system in which direct access to the underlying toolkit is unnecessary for all standard data processing.

Data

Measurement set, Images

Interferometric data are stored in a so-called measurement set, which is a generalized description of data from any interferometric telescope. Traditionally, this kind of data has been described as visibility data, or uv data. A Fourier transform to the image plane creates images.

Where are my data ?

Your data are in directories located in the same area you started CASA from. The name of the top level directory is identical to the name of your measurement set or image. Deleting a measurement set or an image means deleting the top level directory, and all underlying directories and files, using the file delete method of the operating system you started CASA from. For example, when running CASA on a Linux system, in order to delete the measurement set named AM675 type:

CASA <5>: !rm -r AM675

from within CASA. The ! tells CASA that a system command follows, and the -r makes sure that all subdirectories are being deleted recursively. Any system command may be executed in this manner from within CASA.

Further Details About Tasks

As mentioned in the introduction, tasks in CASA are python (ipython ?) interfaces to the more basic toolkit. Tasks are executed to perform a single job, such as loading, plotting, flagging, calibrating, and imaging the data.

Basic information on tasks, including the parameters used and their defaults, can be obtained by typing help taskname at the CASA prompt, where taskname is the name of a given task. help taskname provides a description of the task and then lists all parameters, a brief description of the parameter, the parameter default, an example setting the parameter and any options if there are limited allowed values for the parameter.

*NOTE: Your PAGER environment variable determines how help is displayed. export PAGER=LESS will give you a view of the task help (when doing 'help task') but will vanish and return you to the command line when you are done viewing it. export PAGER=more will scroll the help onto your command window and then return you to your prompt (but leaving it on display). Setting PAGER=cat will give you the more equivalent without some extra formatting baggage and is the recommended choice.

Setting Parameters and Invoking Tasks

Tasks require input parameters (sometimes called keywords). One can either 1) assign parameters, one at a time, from the CASA prompt, and then execute the task; 2) execute the task in one line, specifically assigning each parameter within the line; or 3) using the position within the task call to specify the value of the parameter. For example the following are equivalent:

# use parameter order for invoking tasks
plotxy('ngc5921.ms','channel','amp','data')
# specify parameter names for each
plotxy(vis='ngc5921.ms',xaxis='channel',yaxis='amp',datacolumn='data')
# when specifying the parameter name, order doesn't matter
plotxy(xaxis='channel',vis='ngc5921.ms',datacolumn='data',yaxis='amp')

You can also set parameters by performing the assigment within the CASA shell and then inspecting them using the inp command.

CASA <4>: vis
  Out[4]: False

CASA <5>: inp 'listobs'
--------> inp('listobs')

listobs -- List the observations in a data set:

vis         = "False"
verbose     =  False

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

CASA <7>: inp 'listobs'
--------> inp('listobs')

listobs -- List the observations in a data set:

vis         = "ngc5921.ms"
verbose     =  False

All task parameters have global scope within CASA, i.e., the parameter values are common to all tasks and 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 insure proper values are provided).

To inspect a parameter value just type it at the command line:
CASA <16>: alg
  Out[16]: 'clark'

Help on a parameter can be obtained by typing 'help par.parameter_name',e.g.,

CASA <17>: help par.alg
---------> help(par.alg)
Help on function alg in module parameter_dictionary:

alg()
    Imaging algorithm to use. Options: 'clark','hogbom','csclean','multiscale','mfclark',
'mfhogbom','mfmultisc ale':

    Default: 'hogbom'

Saving and Recalling Task Parameters

Parameters for a given task can be saved by using the saveinputs command and restored using the execfile filename command.

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

CASA <2>: inp 'listobs'
--------> inp('listobs')

listobs -- List the observations in a data set:
vis         = "ngc5921.ms"
verbose     =  False

CASA <3>: saveinputs 'listobs' # defaults to 'taskname.saved'
--------> saveinputs('listobs')

CASA <4>: !more 'listobs.saved'
vis         = "ngc5921.ms"
verbose     =  False

CASA <5>: vis='someotherfile.ms'

CASA <6>: inp 'listobs'
--------> inp('listobs')

listobs -- List the observations in a data set:

vis         = "someotherfile.ms"
verbose     =  False

CASA <7>: execfile 'listobs.saved'
--------> execfile('listobs.saved')

CASA <8>: inp 'listobs'
--------> inp('listobs')

listobs -- List the observations in a data set:

vis         = "ngc5921.ms"
verbose     =  False

CASA <9>: saveinputs 'listobs','ngc5921_listobs.par'  #specify a file
--------> saveinputs('listobs','ngc5921_listobs.par')

CASA <10>: !more ngc5921_listobs.par
vis         = "ngc5921.ms"
verbose     =  False

CASA <11>:

Appendices

Obtaining and Installing CASA

Installation Script

Currently you must be able to log into your system as the root user or an administrator user to install CASA.

The easiest way to install CASA on a RedHat Enterprise Linux (or compatible) system is to use our installation script, load-casapy. This script will ftp the CASA RPMs and install them. To use it, first use the link above to download it to your hard disk. Next, make sure execute permission is set for the file.

Install CASA into /usr by logging in as root and running:

load-casapy --root

This option will install CASA into /usr, but it can only be run by the root user.

Alternatively, you can visit our FTP server, download the rpms, and install them by hand. Note: you must be root/administrater to install CASA in this manner.

See the following for more details:

https://safe.nrao.edu/wiki/bin/view/Software/ObtainingCASA

Startup

This section assumes that CASA has been installed on your LINUX or OSX system. _For NRAO-AOC testers, you should do the following on an AOC RHE4 machine:_

> . /home/casa/casainit.sh
or
> source /home/casa/casainit.csh

Python and CASA

CASA uses Python, IPython and matplotlib within the package.

"Python is an interpreted, interactive, object-oriented programming language" (from www.python.org); it is used as the underlying command line interface/scripting language to CASA . Note: since Python is inherently 0-based in its indexing of arrays, vectors, etc, CASA is also 0-based; any Index inputs (e.g., start (for start channel), fieldIndex, antennaID, etc) will start with 0.

IPython is an enhanced, interactive shell to Python which provides many features for efficient command line interaction.

matplotlib is a Python 2-D plotting library for publication quality figures in different hardcopy formats.

Some key links are:

Each of the features of these components behave in the standard way within \casa\ . In the following sections, we outline the key elements for analysis interactions; see the IPython page for the full suite of functionality.

In-line help

  • TAB key

At any time, hitting the TAB key will complete any available commands or variable names and show you a list of the possible completions if there's no unambiguous result. It will also complete filenames in the current directory if no CASA or Python names match.

For example, it can be used to list the available functionality using minimum match; once you have typed enough characters to make the command unique, the TAB key will complete it.

CASA <15>: cle<TAB>
clean     clear     clearcal

  • help (with no arguments) - native Python help facility

Typing 'help' will give you the default Python help and give you the help> prompt for further information; hitting at the help prompt returns you to the CASA prompt. You can also get the short help for a CASA method by typing 'help tool.method' or 'help task'.

CASA [2]: help
---------> help()


Welcome to Python 2.5!  This is the online help utility.

If this is your first time using Python, you should definitely check out
the tutorial on the Internet at http://www.python.org/doc/tut/.

Enter the name of any module, keyword, or topic to get help on writing
Python programs and using Python modules.  To quit this help utility and
return to the interpreter, just type "quit".

To get a list of available modules, keywords, or topics, type "modules",
"keywords", or "topics".  Each module also comes with a one-line summary
of what it does; to list the modules whose summaries contain a given word
such as "spam", type "modules spam".
help> keywords

Here is a list of the Python keywords.  Enter any keyword to get more help.

and                 else                import              raise
assert              except              in                  return
break               exec                is                  try
class               finally             lambda              while
continue            for                 not                 yield
def                 from                or
del                 global              pass
elif                if                  print

help>

# hit <RETURN> to return to CASA prompt

You are now leaving help and returning to the Python interpreter.
If you want to ask for help on a particular object directly from the
interpreter, you can type "help(object)".  Executing "help('string')"
has the same effect as typing a particular string at the help> prompt.

Automatic parentheses

Automatic parenthesis is enabled for calling functions with argument lists; this feature is intended to allow less typing for common situations. IPython will display the interpretation of the line, beneath the one typed, as indicated by the '-------->'. Default behavior in CASA is to have automatic parenthesis enabled.

System shell access

Any input line beginning with a '!' character is passed verbatim (minus the '!', of course) to the underlying operating system (*the sole exception to this is the 'cd' command which must be executed without the '!'*).

Several common commands (ls, pwd, cd, less) may be executed with or without the '!'.

CASA [1]: pwd
/export/home/corsair-vml/jmcmulli/data
CASA [2]: ls n*
ngc5921.ms ngc5921.py
CASA [3]: !cp -r ../test.py .

In addition, filesystem navigation is aided through the use of bookmarks to simplify access to frequently-used directories:

CASA [4]: cd /home/ballista/jmcmulli/other_data
CASA [4]: pwd
/home/ballista/jmcmulli/other_data
CASA [5]: bookmark other_data
CASA [6]: cd /export/home/corsair-vml/jmcmulli/data
CASA [7]: pwd
/export/home/corsair-vml/jmcmulli/data
CASA [8]: cd -b other_data
(bookmark:data) -> /home/ballista/jmcmulli/other_data

Output from shell commands can be captured in two ways:

  1. sx shell_command, !!shell_command - this captures the output to a list

CASA [1]: sx pwd # stores output of 'pwd' in a list
  Out[1]: ['/home/basho3/jmcmulli/pretest']

CASA [2]: !!pwd  # !! is a shortcut for 'sx'
  Out[2]: ['/home/basho3/jmcmulli/pretest']

CASA [3]: sx ls v* # stores output of 'pwd' in a list
  Out[3]:
['vla_calplot.jpg',
 'vla_calplot.png',
 'vla_msplot_cals.jpg',
 'vla_msplot_cals.png',
 'vla_plotcal_bpass.jpg',
 'vla_plotcal_bpass.png',
 'vla_plotcal_fcal.jpg',
 'vla_plotcal_fcal.png',
 'vla_plotvis.jpg',
 'vla_plotvis.png']

CASA [4]: x=_ # remember '_' is a shortcut for the output from the last command

CASA [5]: x
  Out[5]:
['vla_calplot.jpg',
 'vla_calplot.png',
 'vla_msplot_cals.jpg',
 'vla_msplot_cals.png',
 'vla_plotcal_bpass.jpg',
 'vla_plotcal_bpass.png', 'vla_plotcal_fcal.jpg',
 'vla_plotcal_fcal.png',
 'vla_plotvis.jpg',
 'vla_plotvis.png']

CASA [6]: y=Out[2] # or just refer to the enumerated output

CASA [7]: y
  Out[7]: ['/home/basho3/jmcmulli/pretest']

  1. sc - captures the output to a variable; options are '-l' and '-v'

CASA [1]: sc x=pwd # capture output from 'pwd' to the variable 'x'

CASA [2]: x
  Out[2]: '/home/basho3/jmcmulli/pretest'

CASA [3]: sc -l x=pwd # capture the output from 'pwd' to the variable 'x' but
                      # split newlines into a list (similar to sx command)

CASA [4]: x
  Out[4]: ['/home/basho3/jmcmulli/pretest']

CASA [5]: sc -v x=pwd # capture output from 'pwd' to a variable 'x' and
                      # show what you get (verbose mode)
x ==
'/home/basho3/jmcmulli/pretest'

CASA [6]: x
  Out[6]: '/home/basho3/jmcmulli/pretest'

Logging

There are two components to logging within CASA. Logging of all command line inputs is done via IPython.

Upon startup, CASA will log all commands to a file called ipython.log. This file can be changed via the use of the ipythonrc file.

The following line sets up the logging for CASA . There are four options following the specification of the logging file: 1) append, 2) rotate (each session of CASA will create a new log file with a counter incrementing ipython.log.1~, ipython.log.2~ etc, 3) over (overwrite existing file), and 4) backup (renames exising log file to log_name~).

logfile ./ipython.log append

The command logstate will provide details on the current logging setup:

CASA [12]: logstate

File:   ipython.log
Mode:   append
State:  active

Logging can be turned on and off using the logon, logoff commands.

The second component is the output from applications which is directed to the file ./casapy.log.

Your command line history is automatically maintained and stored in the local directory as ipython.log; this file can be edited and re-executed as appropriate using the execfile 'filename' feature. In addition, logging of output from commands is sent to the file casapy.log, also in your local directory; this is brought up automatically.

The logger has a range of features including the ability to filter messages, sort by Priority, Time, etc, and the ability to insert additional comments.

History and Searching

Numbered input/output history is provided natively within IPython. Command history is also maintained on-line.

CASA [11]: x=1

CASA [12]: y=3*x

CASA [13]: z=x**2+y**2

CASA [14]: x
  Out[14]: 1

CASA [15]: y
  Out[15]: 3

CASA [16]: z
  Out[16]: 10

CASA [17]: Out[14]   # Note: The 'Out' vector contains command output
  Out[17]: 1

CASA [18]: _15       # Note: The return value can be accessed by _number
  Out[18]: 3

CASA [19]: ___       # Note: The last three return values can be accessed as:
  Out[19]: 10        #       _, __, ___

Command history can be accessed via the 'hist' command. The history is reset at the beginning of every CASA session, that is, typing 'hist' when you first enter start CASA will not provide any commands from the previous session; however, all of the commands are still available at the command line and can be accessed through the up,down arrow keys, and through searching.

CASA [22]: hist
1 : __IP.system("vi temp.py")  # Note:shell commands are designated in this way
2 : ipmagic("%run -i temp.py") # Note:magic commands are designated in this way
3 : ipmagic("hist ")
4 : more temp.py
5 : __IP.system("more temp.py")
6 : quickhelp()                # Note: autoparenthesis are added in the history
7 : im.open('ngc5921.ms')
8 : im.summary()
9 : ipmagic("pdoc im.setdata")
10: im.close()
11: quickhelp()
12: ipmagic("logstate ")
13: x=1
14: y=3*x
15: z=x**2+y**2
16: x
17: y
18: z
19: Out[16]
20: _17
21: ___

The history can be saved as a script or used as a macro for further use:

CASA [24]: save script.py 13:16
File `script.py` exists. Overwrite (y/[N])? y
The following commands were written to file `script.py`:
x=1
y=3*x
z=x**2+y**2
CASA [25]: !more script.py
x=1
y=3*x
z=x**2+y**2

CASA [26]:

Note that the history commands will be saved up to, but not including the last value (i.e., history commands 13-16 saves commands 13, 14, and 15).

There are two mechanisms for searching command history:

  1. Begin typing and use the Ctrl-p (previous,up) and Ctrl-n (next,down) to search through only
the history items that match what you've typed so far. If you use Ctrl-p,Ctrl-n at a blank prompt, they behave just like the normal arrow keys.

  1. Hit Ctrl-r; this opens a search prompt. Begin typing and the system searches your history for
lines that contain what you've typed so far, completing what it can.

For example:

CASA [37]:

(reverse-i-search)`':

Typing anything after the colon will provide you with the last command matching the characters, for example, typing 'op' finds:

(reverse-i-search)`op': im.open('ngc5921.ms')

Subsequent hitting of Ctrl-r will search for the next command matching the characters.

Macros

Macros can be made for easy re-execution of previous commands. For example to store the commands 13-15 to the macro 'example':

CASA [31]: macro example 13:16
Macro `example` created. To execute, type its name (without quotes).
Macro contents:
x=1
y=3*x
z=x**2+y**2

CASA [32]: z
Out[32]: 6

CASA [33]: z=10

CASA [34]: example
Out[34]: Executing Macro...

CASA [35]: z
Out[35]: 6

CASA [36]:

On-line editing

You can edit files on-line in two ways:

  1. Using the shell access via '!vi'
  2. Using the ed function; this will edit the file but upon closing, it will try to
execute the file; using the 'script.py' example above:

CASA [13]: ed script.py # this will bring up the file in your chosen editor
                        # when you are finished editing the file, it will automatically
                        # execute it (as though you had done a execfile 'script.py'
Editing... done. Executing edited code...

CASA [14]: x
  Out[14]: 1

CASA [15]: y
  Out[15]: 3

CASA [16]: z
  Out[16]: 6

Executing Python scripts

Python scripts are simple text files containing lists of commands as if typed at the keyboard. Note: the autoparentheses feature of IPython can not be used in scripts, that is, you should make sure all function calls have any opening and closing parentheses.

# file is script.py
# My script to plot the observed visibilities
plotxy('ngc5921.ms','uvdist') #yaxis defaults to amplitude

This can be done by:

  1. execfile: this will execute the script as though you had typed the lines at the \casa\ prompt.

CASA [5]: execfile 'script.py'
--------> execfile('script.py')

How do I exit from CASA ?

Hit or type at the CASA command line prompt:

CASA>%Exit

and press return.

-- MarkClaussen - 23 Feb 2007
Topic revision: r3 - 2013-02-13, PatrickMurphy
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding NRAO Public Wiki? Send feedback