Previous Upbody > Next

Chapter 1  Introduction

This document describes how to calibrate and image interferometric and single-dish radio astronomical data using the CASA (Common Astronomy Software Application) package. CASA is a suite of astronomical data reduction tools and tasks that can be run via the IPython interface to Python. CASA is being developed in order to fulfill the data post-processing requirements of the ALMA and EVLA projects, but also provides basic and advanced capabilities useful for the analysis of data from other radio, millimeter, and submillimeter telescopes.

You have in your hands the latest release of CASA. This package is under active development, and thus there are a number of caveats and limitations for the use of this package. See the release notes (§ 1.1) below for more information, and pay heed to the numerous ALERTs placed throughout this reference. You can expect regular updates and patches, as well as increasing functionality.

Inside the Toolkit:

Throughout this user reference, we will occasionally intersperse boxed-off pointers to parts of the toolkit that power users might want to explore.

This user reference and cookbook is a task-based walk-through of interferometric data reduction and analysis. In CASA, tasks represent the more streamlined operations that a typical user would carry out. The idea for having tasks is that they are simple to use, provide a more familiar interface, and are easy to learn for most astronomers who are familiar with radio interferometric data reduction (and hopefully for novice users as well). In CASA, the tools provide the full capability of the package, and are the atomic functions that form the basis of data reduction. These tools augment the tasks, or fill in gaps left by tasks that are under development but not yet available. See the CASA Toolkit Manual for more details on the tools (available from casa.nrao.edu). Note that in most cases, the tasks are Python interface scripts to the tools, but with specific, limited access to them and a standardized interface for parameter setting. The tasks and tools can be used together to carry out more advanced data reduction operations.

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 or telescope 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).

This reference is broken down by the main phases of data analysis:

These are included for users that will be doing EVLA and ALMA telescope commissioning and software development.

The general appendices provide more details on what’s happening under the hood of CASA, as well as supplementary material on tasks, scripts, and relating CASA to other packages. These appendices include:

The CASA User Documentation includes:

The CASA home page can be found at:

http://casa.nrao.edu

From there you can find documentation and assistance for the use of the package, including the User Documentation. You will also find information on how to obtain the latest release and receive user support.

There is also a CASAGuides Wiki

http://casaguides.nrao.edu

that contains helpful information on CASA startup, AIPS-to-CASA cheat sheet, example scripts of processing your data in CASA, along with hints and tricks to best use this package.

1.0.1  Reference for Publications

If you use CASA for any of your data reduction or analysis, you may use the following reference:
McMullin, J. P., Waters, B., Schiebel, D., Young, W., & Golap, K. 2007, Astronomical Data Analysis Software and Systems XVI (ASP Conf. Ser. 376), ed. R. A. Shaw, F. Hill, & D. J. Bell (San Francisco, CA: ASP), 127

1.1  About This Release

ALERT

Boxes like this will bring to your attention some of the features (or lack thereof) in the current release of CASA. There are also ALERT notes in the text.

CASA 4.7.2 is a second patch for 4.7.0 that fixes a CASA 4.7.1 bug concerning the restoration of mosaics in tclean. The primary beam correction was inadvertently applied to the model image, which causes problems during cleaning and causes the output restored image to have the primary beam corrected model added to uncorrected residuals, which is incorrect. This behavior is independent of the value of the pbcor parameter (for mosaics the pbcor=True option is not yet implemented). The issue only occurred in CASA 4.7.1.; 4.7.0 is not affected.

CASA 4.7.1 includes the most recent official VLA data calibration pipeline (including a correction for the online tropospheric delay bug, see below). It also contains the candidate ALMA Cycle 4 pipeline patch, although this has not yet been accepted for operations use.

Important bug fixes in CASA 4.7.1 and the featurs that were introduced in 4.7.0 are listed below. We occasionally issue patches and ’pre-release’ versions of CASA. To get notified, please subscribe to the ’casa-users’ mailing list. All CASA versions are available at http://casa.nrao.edu. Releases will be announced via the ’casa-announce’ mailing list. To subscribe, please visit http://casa.nrao.edu. For feedback, and help please go to the NRAO helpdesk http://help.nrao.edu; for ALMA questions please use the ALMA helpdesk http://help.almascience.org.

Note that in its current incarnation CASA is designed to support Karl G. Jansky VLA, ALMA, and older VLA data, as well as single dish data from ALMA as well as Nobeyama. Data from other telescopes, be it single dish or interferometers can be imported from uvfits, FITS-IDI , or sdfits formats into Measurements Sets (MS) or scantables in CASA. Given the variety of non-standard fits formats, we cannot guarantee that CASA will fully support data from all telescopes. However, efforts are made to support data formats from other facilities.

1.2  Obtaining CASA

CASA is available for the following operating systems:

The above OSs are the ones that we use to test the CASA package. Other flavors of Linux may work, too. We now support Mac OS 10.11 but discontinued support for 10.9 (although the 10.10 dmg may work). RedHat 5 will be discontinued next release when we plan to support RedHat 7.

The latest and previous releases can be downloaded from our CASA home page: http://casa.nrao.edu, following the ’Obtaining CASA’ link (direct link: http://casa.nrao.edu/casa_obtaining.shtml.

1.2.1  What’s New in Release 4.7.2

1.2.1.1  CASA 4.7.2 bug fixes

1.2.1.2  CASA 4.7.1 bug fixes

In addition to delivering updated ALMA and VLA pipelines, we fixed the following bugs in CASA:

1.2.1.3  Valid for CASA Release 4.7.0 and later:

Major feature improvements over the previous version of CASA include:

For known issues with this release please visit the CASA webpages:
http://casa.nrao.edu/release_ki.shtml

1.3  CASA Basics — Information for First-Time Users

This section assumes that CASA has been installed on your LINUX or OSX system. See Appendix A for instructions on how to obtain and install CASA.

1.3.1  Before Starting CASA

First, you will most likely be starting CASA running from a working directory that has your data in it, or at least where you want your output to go. It is easiest to start from there rather than changing directories inside casa. ALERT: There is at least one task (plotxy) that fails if the path to your working directory contains spaces in its name, e.g. /users/smyers/MyTest/ is fine, but /users/smyers/My Test/ is not! Please use our new task plotms whenever possible and we may work on a better handling of spaces in path names.

If you have done a default installation under Linux using rpms, or on the Mac with the CASA application, then there should be a sh script called casa in the /usr/bin area which is in your path. This shell will set up its environment and run the version of casa that it points to. If this is how you set up the system, then you need to nothing further and can run casa.

For internal NRAO users we keep different version of CASA, the latest “casa” release, the “casa-stable” “Stable” version that is more developed than the Release but without the full documentation (and no GUI testing). We also offer the “Test” version, “casa-test”, which is produced on a roughly weekly basis with all the latest code but it underwent much less rigorous testing. Instructions how to run the different versions at NRAO can be found on our http://casa.nrao.edu webpages under the “CASA at NRAO” link for the different NRAO sites.

1.3.1.1  Environment Variables

Before starting up casa, you should set or reset any environment variables needed, as CASA will adopt these on startup. For example, the PAGER environment variable determines how help is displayed in the CASA terminal window (see § 1.3.8.3). The choices are less, more, and cat.

In bash, pick one of

   PAGER=less
   PAGER=more
   PAGER=cat

followed by

   export PAGER

In csh or tcsh, pick one of

   setenv PAGER less
   setenv PAGER more
   setenv PAGER cat

The actions of these are as if you were using the equivalent Unix shell command to view the help material. See § 1.3.8.3 for more information on these choices. We recommend using the cat option for most users, as this works smoothly both interactively and in scripts.

Some CASA processes will work on a large number of temporary files. The OS, however, may have a built-in limit on the number of such files. We recommend to increase the limit to >1024. A command like

ulimit -n 2048 

should give CASA enough accessible files to run successfully.

1.3.1.2  Where is CASA?

Note that the path to the CASA installation, which contains the scripts and data repository, will also depend upon the installation. With a default installation under Linux this will probably be in

   /usr/lib64/casa/

If the unpacked tarball is placed somewhere else, one may add the PATH variable to include, e.g.

export PATH=$PATH:/<path>/casa-<version>/bin

for bash and

set path = ($path /<path>/casa-<version>/bin)

in csh shell.

In a Mac OSX default install it will likely be an application in the Applications folder.

You can find the location after initialized by looking at the CASAPATH environment variable. You can find it within casa by

   pathname=os.environ.get('CASAPATH').split()[0]
   print pathname

1.3.2  Starting CASA

After having run the appropriate casainit script, CASA is started by typing
casa
on the UNIX command line, e.g.

   casa

After startup information, you should get an IPython
CASA <1>:
command prompt in the xterm window where you started CASA. CASA will take approximately 10 seconds to initialize at startup in a new working directory; subsequent startups are faster. CASA is active when you get a
CASA <1>
prompt in the command line interface. You will also see a
logger GUI appear on your Desktop (usually near the upper left).

You also have the option of starting CASA with various logger options (see § 1.5.2.1). For example, if you are running remotely in a terminal window without an X11 connection, or if you just do not want to see the logger GUI, and want the logger messages to come to your terminal, do

   casa --nologger --log2term

See § 1.5.2 for information on the logger in general.

1.3.3  Ending CASA

You can exit CASA by typing quit. This will bring up the query

Do you really want to exit ([y]/n)?

to give you a chance in case you did not mean to exit. You can also quit using %exit or CTRL-D.

If you don’t want to see the question "Do you really want to exit [y]/n?", then just type Exit or exit and CASA will stop right then and there.

1.3.4  What happens if something goes wrong?

ALERT: Please check the CASA Home Page for Release Notes and FAQ information including a list of known problems. If you think you have encountered an unknown problem, please consult the CASA HelpDesk (contact information on the CASA Home Page). See also the caveats to this Release (§ 1.1 for pointers to our policy on User Support.

First, always check that your inputs are correct; use the

   help <taskname>

(§ 1.3.8.2) or

   help par.<parameter name>

(§ 1.3.8.4) to review the inputs/output.

1.3.5  Aborting CASA execution

If something has gone wrong and you want to stop what is executing, then typing CTRL-C (Control and C keys simultaneously) will usually cleanly abort the application. This will work if you are running a task synchronously. If this does not work on your system then try CTRL-Z to put the task or shell in the background, and then follow up with a kill -9 <PID> where you have found the relevant casa process ID (PID) using ps (see § 1.3.6 below).

If the problem causes CASA to crash, see the next sub-section.

See § 1.4.2 for more information on running tasks.

Alert: CTRL-C while a tasks runs can corrupt your input data file, e.g. when a scratch column is filled while aborting. If in doubt, wait until the task has finished, delete the new files produced, and start again.

1.3.6  What happens if CASA crashes?

Usually, restarting casa is sufficient to get you going again after a crash takes you out of the Python interface. Note that there may be spawned subprocesses still running, such as the casaviewer or the logger. These can be dismissed manually in the usual manner. After a crash, there may also be hidden processes. You can find these by listing processes, e.g. in linux:

   ps -elf | grep casa

or on MacOSX (or other BSD Unix):

   ps -aux | grep casa

You can then kill these, for example using the Unix kill or killall commands. This may be necessary if you are running remotely using ssh, as you cannot logout until all your background processes are terminated. For example,

   killall ipcontroller

or

   killall Python

will terminate the most common post-crash zombies.

1.3.7  Python Basics for CASA

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 in Appendix B.

The following are some examples of helpful hints and tricks on making Python work for you in CASA.

1.3.7.1  Variables

Python variables are set using the <parameter> = <value> syntax. Python assigns the type dynamically as you set the value, and thus you can easily give it a nonsensical value, e.g.

   vis = 'ngc5921.ms'
   vis = 1

The CASA parameter system will check types when you run a task or tool, or more helpfully when you set inputs using inp (see below). CASA will check and protect the assignments of the global parameters in its namespace.

Note that Python variable names are case-sensitive:

CASA <109>: Foo = 'bar'
CASA <110>: foo = 'Bar'
CASA <111>: foo
  Out[111]: 'Bar'
CASA <112>: Foo
  Out[112]: 'bar'

so be careful.

Also note that misspelling a variable assignment will not be noticed (as long as it is a valid Python variable name) by the interface. For example, if you wish to set correlation=’RR’ but instead type correlation=’RR’ you will find correlation unset and a new correlation variable set. Command completion (see § 1.3.8.1) should help you avoid this.

1.3.7.2  Lists and Ranges

Sometimes, you need to give a task a list of indices. If these are consecutive, you can use the Python range function to generate this list:

CASA <1>: iflist=range(4,8)
CASA <2>: print iflist
[4, 5, 6, 7]
CASA <3>: iflist=range(4)
CASA <4>: print iflist
[0, 1, 2, 3]

See Appendix B.4 for more information.

1.3.7.3  Indexes

As in C, Python indices are 0-based. For example, the first element in a list antlist would be antlist[0]:

CASA <113>: antlist=range(5)
CASA <114>: antlist
  Out[114]: [0, 1, 2, 3, 4]
CASA <115>: antlist[0]
  Out[115]: 0
CASA <116>: antlist[4]
  Out[116]: 4

CASA also uses 0-based indexing internally for elements in the Measurement Set (MS – the basic construct that contains visibility and/or single dish data; see Chapter 2). Thus, we will often talk about Field or Antenna “ID”s which will be start at 0. For example, the first field in an MS would have FIELD_ID==0 in the MSselect syntax, and can be addressed as be indexed as field=’0’ in most tasks, as well as by name field=’0137+331’ (assuming that’s the name of the first field). You will see these indices in the MS summary from the task listobs.

1.3.7.4  Indentation

Python pays attention to the indentation of lines, as it uses indentation to determine the level of nesting in loops. Be careful when cutting and pasting: if you get the wrong indentation, then unpredictable things can happen (usually it just gives an error).

See Appendix B.3 for more information.

1.3.7.5  System shell access

If you want to access system commands from a script, use the os.system command (Appendix B.7.1).

In interactive mode, any input line beginning with a ’!’ character is passed verbatim (minus the ’!’, of course) to the underlying operating system. Also, several common commands (ls, pwd, less) may be executed with or without the ’!’, although the cp command must use ’!’ and cd must be executed without the ’!’. For example:

  CASA <5>: !rm -r mydata.ms

Note that if you want to access a Unix environment variable, you will need to prefix with a double $$ instead of a single $ — for example, to print the value of the $PAGER variable, you would use

  CASA <6>: !echo $$PAGER

See Appendix B.7 for more information.

1.3.7.6  Executing Python scripts

You can execute Python scripts (ASCII text files containing Python or casa commands) using the execfile command. For example, to execute the script contained in the file myscript.py (in the current directory), you would type

  CASA <7>: execfile('myscript.py')

or

  CASA <8>: execfile 'myscript.py'

which will invoke the IPython auto-parenthesis feature.

NOTE: in some cases, you can use the IPython run command instead, e.g.

  CASA <9>: run myscript.py

In this case, you do not need the quotes around the filename. This is most useful for re-initializing the task parameters, e.g.

  CASA <10>: run clean.last

(see § 1.4.5.8).

See Appendix B.12 for more information.

1.3.8  Getting Help in CASA

1.3.8.1  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, <TAB> will complete it.

  CASA <15>: cle<TAB>
clean       clean.last  clear       clearcal    clearplot   clearsta

1.3.8.2  help <taskname>

Basic information on an application, including the parameters used and their defaults, can be obtained by typing pdoc task, help task, help ’task’ or task?. The pdoc task currently gives the cleanest documentation format with the smallest amount of object-oriented (programmer) output. This inline help provides a one line 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.

For example:

      Imports an arbitrary number of VLA archive-format data sets into
      a casa measurement set.  If more than one band is present, they
      will be put in the same measurement set but in a separate spectral
      window.  The task will handle old style and new style VLA (after
      July 2007) archive data and apply the tsys to the data and to
      the weights.

      Keyword arguments:
      archivefiles -- Name of input VLA archive file(s)
              default: none.  Must be supplied
              example: archivefiles = 'AP314_A959519.xp1'
              example: archivefiles=['AP314_A950519.xp1','AP314_A950519.xp2']
      vis -- Name of output visibility file
              default: none.  Must be supplied.
              example: vis='NGC7538.ms'
              Will not over-write existing ms of same name.
              A backup flag-file version 'Original' will be made in
                vis.flagversions.  See help flagmanager
      bandname -- VLA Frequency band
              default: => '' = all bands
              example: bandname='K'
              Options: '4'=48-96 MHz,'P'=298-345 MHz,'L'=1.15-1.75 GHz,
              'C'=4.2-5.1 GHz,'X'=6.8-9.6 GHz,'U'=13.5-16.3 GHz,
              'K'=20.8-25.8 GHz,'Q'=38-51 GHz
      frequencytol -- Tolerance in frequency shift in making spectral windows
              default: => 150000 (Hz).  For Doppler shifted data, <10000 Hz may
              may produce too many unnecessary spectral windows.
              example: frequencytol = 1500000.0 (units = Hz)
      project -- Project name to import from archive files:
              default: '' => all projects in file
              example: project='AL519'
              project = 'al519' or AL519 will work.  Do not include
              leading zeros; project = 'AL0519' will not work.
      starttime -- Time after which data will be considered for importing
              default: '' => all:  Date must be included.
              syntax: starttime = '2003/1/31/05:05:23'
      stoptime --  Time before which data will be considered for importing
              default: '' => all:  Date must be included.
              syntax: stoptime = '2003/1/31/08:05:23'
      applytsys -- Apply data scaling and weight scaling by nominal
              sensitivity (~Tsys)
              default: True.  Strongly recommended
      autocorr --  import autocorrelations to ms
              default:  => False (no autocorrelations)
      antnamescheme -- 'old' or 'new' antenna names.
              default => 'new' gives antnenna names
                'VA04' or 'EA13 for VLA telescopse 04 and 13 (EVLA)
                'old' gives names '04' or '13'
      keepblanks -- Should sources with blank names be filled into the data base
              default => false.  Do not fill
              These scans are tipping scans (as of June 1, 2009) and should not
              be filled in the visibility data set.

You can also get the short help for a CASA tool method by typing ’help tool.method’.

CASA <46>: help ia.subimage

    Summary
            Create a (sub)image from a region of the image
    
    Description
            
    
    This function copies all or
    part of the image to another on-the-fly Image tool. Both float and complex
    valued images are supported.
    
    If {\stfaf outfile} is given, the subimage is written to the specified
    disk file.  If {\stfaf outfile} is unset, the returned Image    ool\ actually
    references the input image file (i.e.  that associated with the Image
            ool\ to which you are applying this function).  So if you deleted the
    input image disk file, it would render this     ool\ useless.  When you
    destroy this    ool\ (with the done function)
    the reference connection is broken. 
    
    Sometimes it is useful to drop axes of length one (degenerate axes).
    Use the {\stfaf dropdeg} argument if you want to do this.
    
    The output mask is the combination (logical OR) of the default input
    \pixelmask\ (if any) and the OTF mask.  Any other input \pixelmaskswill not be copied.  Use function maskhandler if you
    need to copy other masks too.
    
    If the mask has fewer dimensions than the image and if the shape
    of the dimensions the mask and image have in common are the same,
    the mask will automatically have the missing dimensions added so
    it conforms to the image.
    
    If stretch is true and if the number of mask dimensions is less than
    or equal to the number of image dimensions and some axes in the
    mask are degenerate while the corresponding axes in the image are not,
    the mask will be stetched in the degenerate dimensions. For example,
    if the input image has shape [100, 200, 10] and the input
    mask has shape [100, 200, 1] and stretch is true, the mask will be
    stretched along the third dimension to shape [100, 200, 10]. However if
    the mask is shape [100, 200, 2], stretching is not possible and an
    error will result.
    
    
    
    
    
    Input Parameters:
            outfile          Output image file name. Default is unset. 
            region           Region of interest. Default is whole image. 
            mask             Mask to use. See help par.mask. Default is none. 
            dropdeg          Drop degenerate axes false 
            overwrite        Overwrite (unprompted) pre-existing output file? false 
            list             List informative messages to the logger true 
            stretch          Stretch the mask if necessary and possible? false 
            wantreturn       Return an image analysis tool attached to the created subimage true 
            
    Example:
            
    
    '''
    #
    print ' ----     subimage Ex 1  ----'
    ia.maketestimage('myfile',overwrite=true)
    im2 = ia.subimage()                # a complete copy
    r1 = rg.box([10,10],[30,40],[5,5]) # A strided pixel box region
    im3 = ia.subimage(outfile='/tmp/foo', region=r1, overwrite=true)
                                       # Explicitly named subimage
    im2.done()
    im3.done()
    ia.close()
    #
    '''

For a full list of keywords associated with the various tools, see the CASA User Reference Manual.

1.3.8.3  help and PAGER

Your PAGER environment variable (§ 1.3.1) determines how help is displayed in the terminal window where you start CASA. If you set your bash environment variable PAGER=less (setenv PAGER less in csh) then typing help <taskname> will show you the help but the text will vanish and return you to the command line when you are done viewing it. Setting PAGER=more (setenv 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 (setenv PAGER cat) will give you the more equivalent without some extra formatting baggage and is the recommended choice.

If you have set PAGER=more or PAGER=less, the help display will be fine, but the display of ’taskname?’ will often have confusing formatting content at the beginning (lots of ESC surrounding the text). This can be remedied by exiting casa and doing an ’unset PAGER’ (unsetenv PAGER in [t]csh) at the Unix command line.

You can see the current value of the PAGER environment variable with CASA by typing:

  !echo $$PAGER

(note the double $$). This will show what command paging is pointed to.

1.3.8.4  help par.<parameter>

Typing help par.<parameter> provides a brief description of a given parameter <parameter>.

  CASA <46>: help par.robust
  Help on function robust in module parameter_dictionary:

  robust()
    Brigg's robustness parameter.

    Options: -2.0 (close to uniform) to 2.0 (close to natural)

1.3.8.5  Python help

Typing help at the casa prompt with no arguments will bring up the native Python help facility, and give you the help> prompt for further information; hitting <RETURN> at the help prompt returns you to the CASA prompt.

CASA <39>: help
---------> help()

Welcome to Python 2.7!  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://docs.python.org/2.7/tutorial/.

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> 

To exit Python’s help, just hit ENTER. Further help in working within the Python shell is given in Appendix B.

1.4  Tasks and Tools in CASA

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.

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.

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.

1.4.1  What Tasks are Available?

As mentioned in the introduction, 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.

Basic information on tasks, including 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 above in § 1.3.8.2, 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.

To see what tasks are available in CASA, use tasklist, e.g.

CASA <21>: 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
------------------

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 <22>: 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
    help par.parametername - Full help for parameter name
___________________________________________________________________


1.4.2  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('plotxy')
    vis='ngc5921.ms'
    xaxis='channel'
    yaxis='amp'
    datacolumn='data'
    go

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

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

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: 
    plotxy(vis='ngc5921.ms',xaxis='channel',yaxis='amp',datacolumn='data')
  # when specifying the parameter name, order doesn't matter, e.g.:
    plotxy(xaxis='channel',vis='ngc5921.ms',datacolumn='data',yaxis='amp')
  # use parameter order for invoking tasks
    plotxy('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 (§ 1.4.6). Tools never use the global parameters and the related mechanisms of inp and go.

1.4.2.1  Aborting Synchronous Tasks

If you are running CASA tasks synchronously, then 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 § 1.3.5 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.

1.4.3  Getting Return Values

Some tasks and tools return a record (usually a Python dictionary) to the interface. For example, the imstat task (§ 6.10) 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 (§ 1.4.6).

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.

1.4.4  Running Tasks Asynchronously

By default, most tasks run synchronously in the foreground. Many tasks, particularly those that can take a long time to execute, have the async parameter. This allows the user to send the task to the background for execution.

1.4.5  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 § 1.4.5.4 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 (§ 1.4.5.2). 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 (see § 1.4.5.5) 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 § 1.4.5.8).

We now describe the individual CASA task parameter interface commands and features in more detail.

1.4.5.1  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 (§ 1.4.5.2), 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.

1.4.5.2  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 currently can only reset ALL of the parameters for a given task to their defaults. In an upcoming update we will allow the default command to take a second argument with a specific parameter to default its value.

1.4.5.3  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.

1.4.5.4  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

Figure 1.1 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.


Figure 1.1: Screen shot of the default CASA inputs for task clean.

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

Parameter and Values in CASA inp
 Text FontText ColorHighlightIndentationMeaning
Parameters:
 plainblacknonenonestandard parameter
 boldblackgreynoneexpandable parameter
 plaingreennoneyessub-parameter
Values:
 plainblacknonenonedefault value
 plainbluenonenonenon-default value
 plainrednonenoneinvalid value

Figure 1.2 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. Figure 1.3 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’).


Figure 1.2: 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).


Figure 1.3: 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.

1.4.5.5  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:

CASA <6>: saveinputs('listobs','ngc5921_listobs.par')

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

1.4.5.6  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 § 1.4.5.8 below), then for 2) a <taskname>.saved file (see § 1.4.5.5 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

1.4.5.7  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

1.4.5.8  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.

1.4.6  Tools in CASA

The CASA toolkit is the foundation of the functionality in the package, and consists of a suite of functions that are callable from Python. The tools are used by the tasks, and can be used by advanced users to perform operations that are not available through the tasks.

It is beyond the scope of this reference to describe the toolkit in detail. Occasionally, examples will be given that utilize the tools (e.g. § 6.28). In short, tools are always called as functions, with any parameters that are not to be defaulted given as arguments. For example:

   ia.open('ngc5921.chan21.clean.cleanbox.mask')
   ia.calcmask('"ngc5921.chan21.clean.cleanbox.mask">0.5','mymask')
   ia.summary()
   ia.close()

uses the image tool (ia) to turn a clean mask image into an image mask. Tools never use the CASA global parameters.

To find what tools are available, use the toolhelp command:

CASA <23>: toolhelp
---------> toolhelp()
 
Available tools: 

 af : Agent flagger utilities
 at : Juan Pardo ATM library
 ca : Calibration analysis utilities
 cb : Calibration utilities
 cl : Component list utilities
 cp : Cal solution plotting utilities
 cs : Coordinate system utilities
 cu : Class utilities
 dc : Deconvolver utilities
 fi : Fitting utilities
 fn : Functional utilities
 ia : Image analysis utilities
 im : Imaging utilities
 lm: linear mosaic 
 me : Measures utilities
 ms : MeasurementSet (MS) utilities
 msmd : MS metadata accessors
 mt : MS transformer utilities
 qa : Quanta utilities
 pm : PlotMS utilities
 po : Imagepol utilities
 rg : Region manipulation utilities
 sl : Spectral line import and search
 sm : Simulation utilities
 tb : Table utilities (selection, extraction, etc)
 tp : Table plotting utilities
 vp : Voltage pattern/primary beam utilities
 ---
 pl : pylab functions (e.g., pl.title, etc)
 sd : Single dish utilities
 ---

You can find much more information about the toolkit in the CASA User Reference Manual:

http://casa.nrao.edu/docs/casaref/CasaRef.html

1.5  Getting the most out of CASA

There are some other general things you should know about using CASA in order to make things go smoothly during your data reduction.

1.5.1  Your command line history

Your command line history is automatically maintained and stored as ipython.log in your local directory . This file can be edited and re-executed as appropriate using the execfile ’<filename>’ feature.

You can also use the “up-arrow” and “down-arrow” keys for command line recall in the casa interface. If you start typing text, and then use “up-arrow”, you will navigate back through commands matching what you typed.

1.5.2  Logging your session

The output from CASA commands is sent to the file casapy-YYYYMMDD-HHMMSS.log in your local directory, where YYYYMMDD-HHMMSS are the UT date and time when CASA was started up. New starts of CASA create new log files.


Figure 1.4: The CASA Logger GUI window under Linux. Note that under MacOSX a stripped down logger will instead appear as a Console.

The output contained in casapy-YYYYMMDD-HHMMSS.log is also displayed in a separate window using the casalogger. Generally, the logger window will be brought up when casa is started. If you do not want the logger GUI to appear, then start casa using the --nologger option,

   casa --nologger

which will run CASA in the terminal window. See § 1.5.2.1 for more startup options.


Figure 1.5: Using the Search facility in the casalogger. Here we have specified the string ’apply’ and it has highlighted all instances in green.

ALERT: Due to problems with Qt under MacOSX, we had to replace the GUI qtcasalogger with a special stripped down one that uses the Mac Console. This still has the important capabilities such as showing the messages and cut/paste. The following description is for the Linux version and thus should mostly be disregarded on OSX. On the Mac, you treat this as just another console window and use the usual mouse and hot-key actions to do what is needed.

The CASA logger window for Linux is shown in Figure 1.4. The main feature is the display area for the log text, which is divided into columns. The columns are:


Figure 1.6: Using the casalogger Filter facility. The log output can be sorted by Priority, Time, Origin, and Message. In this example we are filtering by Origin using ’clean’, and it now shows all the log output from the clean task.


Figure 1.7: CASA Logger - Insert facility: The log output can be augmented by adding notes or comments during the reduction. The file should then be saved to disk to retain these changes.

The casalogger GUI has a range of features, which include:

Other operations are also possible from the menu or buttons. Mouse “flyover” will reveal the operation of buttons, for example.

It is possible to change the file that the logging is directed to. Per default it is ’casapy-YYYYMMDD-HHMMSS.log’. But starting CASA with the option --logfile

casa --logfile otherfile.log

will redirect the output of the logger to the file ’otherfile.log’ (see also Sect. 1.5.2.1). The log file can also be changed during a CASA session. Type

CASA <15>: casalog.setlogfile('otherfile.log')

and you will redirect the output to the ’otherfile.log’ file. However, the logger GUI will still be monitoring the previous ’casapy-YYYYMMDD-HHMMSS.log’ file. To change it to the new file, go on File - Open and select the new log file, in our case ’otherfile.log’.

1.5.2.1  Startup options for the logger

One can specify logger options at the startup of casa on the command line:

   casa <logger option>

The options are described in Appendix A.3. For example, to not bring up a GUI but send the message to your terminal, do

   casa --nologger --log2term

while

   casa --logfile mynewlogfile.log

will start casa with logger messages going to the file mynewlogfile.log.

1.5.2.2  Setting priority levels in the logger

Logger messages are assigned a Priority Level when generated within CASA. The current levels of Priority are:

  1. SEVERE — errors;
  2. WARN — warnings;
  3. INFO — basic information every user should be aware of or has requested;
  4. INFO1 — information possibly helpful to the user;
  5. INFO2 — details the power user might want to see;
  6. INFO3 — even more details;
  7. INFO4 — lowest level of non-debugging information;
  8. DEBUGGING — most “important” debugging messages;
  9. DEBUG1 — more details;
  10. DEBUG2 — lowest level of debugging messages.

The “debugging” levels are intended for the developers use.

Inside the Toolkit:

The casalog tool can be used to control the logging. In particular, the casalog.filter method sets the priority threshold. This tool can also be used to change the output log file, and to post messages into the logger.

There is a threshold for which these messages are written to the casapy-YYYYMMDD-HHMMSS.log file and are thus visible in the logger. By default, only messages at level INFO and above are logged. The user can change the threshold using the casalog.filter method. This takes a single string argument of the level for the threshold. The level sets the lowest priority that will be generated, and all messages of this level or higher will go into the casapy-YYYYMMDD-HHMMSS.log file.

Some examples:

   casalog.filter('INFO')           # the default
   casalog.filter('INFO2')          # should satisfy even advanced users
   casalog.filter('INFO4')          # all INFOx messages
   casalog.filter('DEBUG2')         # all messages including debugging

WARNING: Setting the threshold to DEBUG2 will put lots of messages in the log!

1.5.3  Where are my data in CASA?

Interferometric data are filled into a so-called Measurement Set (or MS). In its logical structure, the MS looks like a generalized description of data from any interferometric or single dish telescope. Physically, the MS consists of several tables in a directory on disk.

Tables in CASA are actually directories containing files that are the sub-tables. For example, when you create a MS called AM675.ms, then the name of the directory where all the tables are stored will be called AM675.ms/. See Chapter 2 for more information on Measurement Set and Data Handling in CASA.

The data that you originally get from a telescope can be put in any directory that is convenient to you. Once you "fill" the data into a Measurement Set that can be accessed by CASA, it is generally best to keep that MS in the same directory where you started CASA so you can get access to it easily (rather than constantly having to specify a full path name).

When you generate calibration solutions or images (again these are in table format), these will also be written to disk. It is a good idea to keep them in the directory in which you started CASA.

1.5.3.1  How do I get rid of my data in CASA?

Note that when you delete a Measurement Set, calibration table, or image, which are in fact directories, you must delete this and all underlying directories and files. If you are not running casa, this is most simply done by 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.ms type:

  CASA <5>: !rm -r AM675.ms

from within CASA. The ! tells CASA that a system command follows (see § 1.3.7.5), and the -r makes sure that all subdirectories are deleted recursively.

It is convenient to prefix all MS, calibration tables, and output files produced in a run with a common string. For example, one might prefix all files from VLA project AM675 with AM675, e.g. AM675.ms, AM675.cal, AM675.clean. Then,

  CASA <6>: !rm -r AM675*

will clean up all of these.

In scripts, the ! escape to the OS will not work. Instead, use the os.system() function (Appendix B.7.1) to do the same thing:

   os.system('rm -r AM675*')

If you are within casa, then the CASA system is keeping a cache of tables that you have been using and using the OS to delete them will confuse things. For example, running a script that contains rm commands multiple times will often not run or crash the second time as the cache gets confused. The clean way of removing CASA tables (MS, caltables, images) inside casa is to use the rmtables task:

  rmtables('AM675.ms')

and this can also be wildcarded

  rmtables('AM675*')

(though you may get warnings if it tries to delete files or directories that fit the name wildcard that are not CASA tables).

ALERT: Some CASA processes lock the file and forget to give it up when they are done (plotxy is usually the culprit). You will get WARNING messages from rmtables and your script will probably crash second time around as the file isn’t removed. The safest thing is still to exit casa and start a new session for multiple runs.

1.5.4  What’s in my data?

The actual data is in a large MAIN table that is organized in such a way that you can access different parts of the data easily. This table contains a number of “rows”, which are effectively a single timestamp for a single spectral window (like an IF from the VLA) and a single baseline (for an interferometer).

There are a number of “columns” in the MS, the most important of which for our purposes is the DATA column — this contains the original visibility data from when the MS was created or filled. There are other helpful “scratch” columns which hold useful versions of the data or weights for further processing: the CORRECTED_DATA column, which is used to hold calibrated data and an optional MODEL_DATA column, which may hold the Fourier inversion of a particular model image. The creation and use of the scratch columns is generally done behind the scenes, but you should be aware that they are there (and when they are used). We will occasionally refer to the rows and columns in the MS.

More on the contents of the MS can be found in § 2.1.

1.5.5  Data Selection in CASA

We have tried to make the CASA task interface as uniform as possible. If a given parameter appears in multiple tasks, it should, as far as is possible, mean the same thing and be used in the same way in each. There are groups of parameters that appear in a number of tasks to do the same thing, such as for data selection.

The parameters field, spw, and selectdata (which if True expands to a number of sub-parameters) are commonly used in tasks to select data on which to work. These common data selection parameters are described in § 2.3.

1.6  From Loading Data to Images

The subsections below provide a brief overview of the steps you will need to load data into CASA and obtain a final, calibrated image. Each subject is covered in more detail in Chapters 2 through 6.

An end-to-end workflow diagram for CASA data reduction for interferometry data is shown in Figure 1.8. This might help you chart your course through the package. In the following sub-sections, we will chart a rough course through this process, with the later chapters filling in the individual boxes.


Figure 1.8: Flow chart of the data processing operations that a general user will carry out in an end-to-end CASA reduction session.

Note that single-dish data reduction (for example with the ALMA single-dish system) follows a similar course. This is detailed in Chapter 8.

1.6.1  Loading Data into CASA

The key data and image import tasks are:

These are used to bring in your interferometer data, to be stored as a CASA Measurement Set (MS), and any previously made images or models (to be stored as CASA image tables).

The data import tasks will create a MS with a path and name specified by the vis parameter. See § 1.5.3 for more information on MS in CASA. The Measurement Set is the internal data format used by CASA, and conversion from any other native format is necessary for most of the data reduction tasks.

Once data is imported, there are other operations you can use to manipulate the datasets:

Data import, export, concatenation, and selection detailed in Chapter 2.

1.6.1.1  VLA: Filling data from VLA archive format

VLA data in “archive” format are read into CASA from disk using the importvla task (see § 2.2.3). This filler supports the new naming conventions of EVLA antennas when incorporated into the old VLA system.

Note that future data from the EVLA in ASDM format will use a different filler. This will be made available in a later release.

1.6.1.2  Filling data from UVFITS format

For UVFITS format, use the importuvfits task. A subset of popular flavors of UVFITS (in particular UVFITS as written by AIPS) is supported by the CASA filler. See § 2.2.7 for details.

1.6.1.3  Loading FITS images

For FITS format images, such as those to be used as calibration models, use the importfits task. Most, though not all, types of FITS images written by astronomical software packages can be read in.

See § 6.27 for more information.

1.6.1.4  Concatenation of multiple MS

Once you have loaded data into Measurement Sets on disk, you can use the tasks concat or virtualconcat to combine them.

See § 2.2.14 for details.

1.6.2  Data Examination, Editing, and Flagging

The main data examination and flagging tasks are:

These tasks allow you to list, plot, and/or flag data in a CASA MS.

There will eventually be tasks for “automatic” flagging to data based upon statistical criteria. Stay tuned.

Examination and editing of synthesis data is described in Chapter 3.

Visualization and editing of an MS using the casaviewer is described in Chapter 7.

1.6.2.1  Interactive X-Y Plotting and Flagging

The principal tool for making X-Y plots of visibility data is plotms (see § 3.3.1). Amplitudes and phases (among other things) can be plotted against several x-axis options.

Interactive flagging (i.e., “see it – flag it”) is possible on the plotms X-Y displays of the data (§ 3.3.1.6). Since flags are inserted into the Measurement Set, it is useful to backup (or make a copy) of the current flags before further flagging is done, using flagmanager (§ 3.2). Copies of the flag table can also be restored to the MS in this way.

1.6.2.2  Flag the Data Non-interactively

The flagdata task (§ 3.4) will flag the visibility data set based on the specified data selections. The listobs task (§ 2.2.9) may be run (e.g. with verbose=True) to provide some of the information needed to specify the flagging scope. flagdata also contains autoflagging routines.

1.6.2.3  Viewing and Flagging the MS

The CASA viewer can be used to display the data in the MS as a (grayscale or color) raster image. The MS can also be edited. Use of the viewer on an MS is detailed in § 7.5.

1.6.3  Calibration

The major calibration tasks are:

During the course of calibration, the user will specify a set of calibrations to pre-apply before solving for a particular type of effect, for example gain or bandpass or polarization. The solutions are stored in a calibration table (subdirectory) which is specified by the user, not by the task: care must be taken in naming the table for future use. The user then has the option, as the calibration process proceeds, to accumulate the current state of calibration in a new cumulative table. Finally, the calibration can be applied to the dataset.

Synthesis data calibration is described in detail in Chapter 4.

1.6.3.1  Prior Calibration

The setjy task calculates absolute fluxes for Measurement Set base on known calibrator sources. This can then be used in later calibration tasks. Currently, setjy knows the flux density as a function of frequency for several standard EVLA flux calibrators and solar system objects, and the value of the flux density can be manually inserted for any other source. If the source is not well-modeled as a point source, then a model image of that source structure can be used (with the total flux density scaled by the values given or calculated above for the flux density). Models are provided for the standard VLA calibrators.

Antenna gain-elevation curves (e.g. for the EVLA antennas) and atmospheric optical depth corrections (applied as an elevation-dependent function) may be pre-applied before solving for the bandpass and gains. CASA v4.1 was the last version where these specialized calibration were supported by explicit parameters in the calibration tasks (gaincurve and opacity). As of v4.2, these parameters have been removed, and gain curves and opacity are supported via gencal, which will generate standard calibration tables describing these effects, much as other a priori effects (Tsys, switched power, etc.) are supported.

See § 4.3 for more details.

1.6.3.2  Bandpass Calibration

The bandpass task calculates a bandpass calibration solution: that is, it solves for gain variations in frequency as well as in time. Since the bandpass (relative gain as a function of frequency) generally varies much more slowly than the changes in overall (mean) gain solved for by gaincal, one generally uses a long time scale when solving for the bandpass. The default ’B’ solution mode solves for the gains in frequency slots consisting of channels or averages of channels.

A polynomial fit for the solution (solution type ’BPOLY’) may be carried out instead of the default frequency-slot based ’B’ solutions. This single solution will span (combine) multiple spectral windows.

Bandpass calibration is discussed in detail in § 4.4.2.

If the gains of the system are changing over the time that the bandpass calibrator is observed, then you may need to do an initial gain calibration (see next step).

1.6.3.3  Gain Calibration

The gaincal task determines solutions for the time-based complex antenna gains, for each spectral window, from the specified calibration sources. A solution interval may be specified. The default ’G’ solution mode solves for antenna-based gains in each polarization in specified time solution intervals. The ’T’ solution mode is the same as ’G’ except that it solves for a single solution shared by both polarizations.

A spline fit for the solution (solution type ’GSPLINE’) may be carried out instead of the default time-slot based ’G’ solutions.

See § 4.4.3 for more on gain calibration.

1.6.3.4  Polarization Calibration

The polcal task will solve for any unknown polarization leakage and cross-hand phase terms (’D’ and ’X’ solutions). The ’D’ leakage solutions will work on sources with no polarization and sources with known (and supplied, e.g., using smodel) polarization. For sources with unknown polarization tracked through a range in parallactic angle on the sky, using poltype ’D+QU’, which will first estimate the calibrator polarization for you.

The solution for the unknown cross-hand polarization phase difference ’X’ term requires a polarized source with known linear polarization (Q,U).

Frequency-dependent (i.e., per channel) versions of all of these modes are also supported (poltypes ’Df’, ’Df+QU’, and ’Xf’.

See § 4.4.5 for more on polarization calibration.

1.6.3.5  Examining Calibration Solutions

The plotcal task (§ 4.5.1) will plot the solutions in a calibration table. The xaxis choices include time (for gaincal solutions) and channel (e.g. for bandpass calibration). The plotcal interface and plotting surface is similar to that in plotxy. Eventually, plotcal will allow you to flag and unflag calibration solutions in the same way that data can be edited in plotxy.

The listcal task (§ 4.5.3) will print out the calibration solutions in a specified table.

1.6.3.6  Bootstrapping Flux Calibration

The fluxscale task bootstraps the flux density scale from “primary” standard calibrators to the “secondary” calibration sources. Note that the flux density scale must have been previously established on the “primary” calibrator(s), typically using setjy, and of course a calibration table containing valid solutions for all calibrators must be available.

See § 4.4.4 for more.

1.6.3.7  Correcting the Data

The final step in the calibration process, applycal may be used to apply several calibration tables (e.g., from gaincal or bandpass, along with prior calibration tables). The corrections are applied to the DATA column of the visibility, writing the CORRECTED_DATA column which can then be plotted (e.g. in plotxy), split out as the DATA column of a new MS, or imaged (e.g. using clean). Any existing corrected data are overwritten.

See § 4.6.1 for details.

1.6.3.8  Splitting the Data

After a suitable calibration is achieved, it may be desirable to create one or more new Measurement Sets containing the data for selected sources. This can be done using the split task (§ 4.7.1).

Further imaging and calibration (e.g. self-calibration) can be carried out on these split Measurement Sets.

1.6.3.9  UV Continuum subtraction

For spectral line data, continuum subtraction can be performed in the image domain (imcontsub) or in the uv domain. For the latter, there are two tasks available: uvcontsub subtracts polynomial of desired order from each baseline, defined by line-free channels.

1.6.3.10  Transforming the Data to a new frame

If you want to transform your dataset to a different frequency and velocity frame than the one it was observed in, then you can use the cvel task (§ 4.7.7). Alternatively, you can do the regridding during the imaging process in clean without running cvel before.

1.6.4  Synthesis Imaging

The key synthesis imaging tasks are:

Most of these tasks are used to take calibrated interferometer data, with the possible addition of a single-dish image, and reconstruct a model image of the sky. Alert: The clean task is now even more powerful and incorporates the functionality of previous specialized tasks such as mosaic and widefield.

See Chapter 5 for more on synthesis imaging.

1.6.4.1  Cleaning a single-field image or a mosaic

The CLEAN algorithm is the most popular and widely-studied method for reconstructing a model image based on interferometer data. It iteratively removes at each step a fraction of the flux in the brightest pixel in a defined region of the current “dirty” image, and places this in the model image. The clean task implements the CLEAN algorithm for single-field data. The user can choose from a number of options for the particular flavor of CLEAN to use.

Often, the first step in imaging is to make a simple gridded Fourier inversion of the calibrated data to make a “dirty” image. This can then be examined to look for the presence of noticeable emission above the noise, and to assess the quality of the calibration by searching for artifacts in the image. This is done using clean with niter=0.

The clean task can jointly deconvolve mosaics as well as single fields, and also has options to do wide-field and wide-band multi-frequency synthesis imaging.

See § 5.3 for an in-depth discussion of the clean task.

1.6.4.2  Feathering in a Single-Dish image

If you have a single-dish image of the large-scale emission in the field, this can be “feathered” in to the image obtained from the interferometer data. This is carried out using the feather tasks as the weighted sum in the uv-plane of the gridded transforms of these two images. While not as accurate as a true joint reconstruction of an image from the synthesis and single-dish data together, it is sufficient for most purposes.

See § 5.6 for details on the use of the feather task.

1.6.5  Self Calibration

Once a calibrated dataset is obtained, and a first deconvolved model image is computed, a “self-calibration” loop can be performed. Effectively, the model (not restored) image is passed back to another calibration process (on the target data). This refines the calibration of the target source, which up to this point has had (usually) only external calibration applied. This process follows the regular calibration procedure outlined above.

Any number of self-calibration loops can be performed. As long as the images are improving, it is usually prudent to continue the self-calibration iterations.

This process is described in § 5.11.

1.6.6  Data and Image Analysis

The key data and image analysis tasks are:

1.6.6.1  What’s in an image?

The imhead task will print out a summary of image “header” keywords and values. This task can also be used to retrieve and change the header values.

See § 6.2 for more.

1.6.6.2  Image statistics

The imstat task will print image statistics. There are options to restrict this to a box region, and to specified channels and Stokes of the cube. This task will return the statistics in a Python dictionary return variable.

See § 6.10 for more.

1.6.6.3  Image values

The imval task will values from an image. There are options to restrict this to a box region, and to return specified channels and Stokes of the cube as a spectrum. This task will return these values in a Python dictionary return variable which can then be operated on in the casa environment.

See § 6.10 for more.

1.6.6.4  Moments of an image cube

The immoments task will compute a “moments” image of an input image cube. A number of options are available, from the traditional true moments (zero, first, second) and variations thereof, to other images such as median, minimum, or maximum along the moment axis.

See § 6.8 for details.

1.6.6.5  Image math

The immath task will allow you to form a new image by mathematical combinations of other images (or parts of images). This is a powerful, but tricky, task to use.

See § 6.7 for more.

1.6.6.6  Regridding an Image

It is occasionally necessary to regrid an image onto a new coordinate system. The imregrid task can be used to regrid an input image onto the coordinate system of an existing template image, creating a new output image.

See § 6.14 for a description of this task.

1.6.6.7  Displaying Images

To display an image use the viewer task. The viewer will display images in raster, contour, or vector form. Blinking and movies are available for spectral-line image cubes. To start the viewer, type:

  viewer

Executing the viewer task will bring up two windows: a viewer screen showing the data or image, and a file catalog list. Click on an image or ms from the file catalog list, choose the proper display, and the image should pop up on the screen. Clicking on the wrench tool (second from left on upper left) will obtain the data display options. Most functions are self-documenting.

The viewer can be run outside of casa by typing casaviewer.

See § 7 for more on viewing images.

1.6.7  Getting data and images out of CASA

The key data and image export tasks are:

These tasks can be used to export a CASA MS or image to UVFITS or FITS respectively. See the individual sections referred to above for more on each.


Previous Up Next