Getting Help in CASA

How to get help while running CASA

The doc() command

The new CASA documentation system introduced with CASA 5.0 is packaged with CASA and is accessible from the CASA command line by means of a new command: doc().  Typing doc() will open the packaged documentation in your browser.  The doc() command can also invoke documentation on select CASA tasks when given the task name as a string parameter.  For example:

doc('applycal')

doc('plotms')

doc('tclean')

The doc command will only invoke documentation for tasks that have been included in the new CASA documentation system.  To see a list of included tasks, open the Global Task List chapter.  For help with tasks not yet included, see below.

The doc() command will always open the documentation packaged with your CASA installation.  The latest version of the CASA Documentation is available at https://casa.nrao.edu/casadocs/ for each official CASA release beginning with CASA 5.0 and also for the latest CASA prerelease.

Task and Tool Listing Commands

There are several commands that can be used at the CASA command line to list available tasks and tools.  taskhelp will print a list of every CASA task along with a one-line description of each.  tasklist will print every CASA task categorized by task purpose (e.g. imaging, calibration, visualization).  Both taskhelp and tasklist are described on the CASA Tasks page.  The command toolhelp will print all CASA tools with a one-line description and is documented on the CASA Tools page.

Terminal-based Task and Tool Help

As part of the on going CASA documentation upgrade, the terminal-based task and tool help will be moved into the online browser-based CASA documentation system, described above.  Eventually, the commands described in this section will display only brief information concerning input parameters.

Task help

Task help can be obtained by typing one of the following

pdoc TASK

help TASK

help ’TASK’

TASK?

where TASK is replaced with the name of a CASA task.  The pdoc command currently gives the cleanest documentation format with the smallest amount of object-oriented (programmer) output. 

For example:

CASA <1>: pdoc importvla
Class docstring:
    Import VLA archive file(s) to a MeasurementSet

      Detailed Description:

    Imports an arbitrary number of VLA archive-format data sets into
    a casa MeasurementSet.  If more than one band is present, they
    will be put in the same MeasurementSet 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.

      Arguments :
              archivefiles:   Name of input VLA archive file(s)
                 Default Value:

              vis:    Name of output visibility file
                 Default Value:

              bandname:       VLA frequency band name:''=>obtain all bands in the archive file
                 Default Value:
                 Allowed Values:
                              4
                              P
                              L
                              S
                              C
                              X
                              U
                              K
                              Ka
                              Q


              frequencytol:   Frequency shift to define a unique spectra window (Hz)
                 Default Value: 150000.0

              project:        Project name: '' => all projects in files
                 Default Value:

              starttime:      start time to search for data
                 Default Value:

              stoptime:       end time to search for data
                 Default Value:

              applytsys:      apply nominal sensistivity scaling to data and weights
                 Default Value: True

              autocorr:       import autocorrelations to ms, if set to True
                 Default Value: False

              antnamescheme:  'old' or 'new'; 'VA04' or '04' for VLA ant 4
                 Default Value: new
                 Allowed Values:
                              old
                              new

              keepblanks:     Fill scans with blank (empty) source names (e.g. tipping scans)
                 Default Value: False

              evlabands:      Use updated eVLA frequencies and bandwidths for bands and wavelengths
                 Default Value: False

Tool help

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

CASA <6>: help im.restore
--------> help(im.restore)
Help on method restore in module __casac__.imager:

restore(self, *args, **kwargs) method of __casac__.imager.imager instance
    restore(self, model, complist, image, residual, async=False) -> bool



    Summary
            Calculate the restored image with restored model, component list, and  residuals

    Description

    Restore the residuals to a smoothed version of the model. The model
    images are convolved with the specified Gaussian beam and then the
    residual images are added.  { Note that the model visibilities are
    updated and thus reflect the model and componentlist that was
    used.}. Use setbeam to set the beam
    parameters.


    Input Parameters:
            model            Names of input model
            complist         Name of component list
            image            Names of output restored images
            residual         Names of residual images
            async            Run asynchronously in the background false

    Example:


    - im.setbeam(bmaj='2.0arcsec', bmin='2.0arcsec')
    - im.restore(model='3C273XC1.clean', image='3C273XC1.clean.restored',


    --------------------------------------------------------------------------------

The PAGER Environment Variable

Your PAGER environment variable 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.

The 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 is no unambiguous result. This works for both tasks and tool methods.  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          clearcal
              cleanup_ephems clearplot
              %clear         clearstat

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 Python Basics for CASA.