CASA Tools and Utilities (pwkit.environments.casa.util)

This module provides low-level tools and utilities for interacting with the casac module provided by CASA.

This module provides:

The tools object

pwkit.environments.casa.util.tools

This object is a singleton instance of a hidden class that assists in the creation of CASA “tools” objects. For instance, you can create and use a standard CASA “tool” for reading and manipulating data tables with code like this:

from pwkit.environments.casa import util
tb = util.tools.table()
tb.open('myfile.ms')
tb.close()

Documentation for the individual CASA “tools” is beyond the scope of pwkit … although maybe it will be added, since the documentation provided by CASA is pretty weak.

Here’s a list of CASA tool names. They can all be created in the same way: by calling the function tools.<toolname>(). This will work even for any tools not appearing in this list, so long as they’re provided by the underlying CASA libraries:

  • agentflagger

  • atmosphere

  • calanalysis

  • calibrater

  • calplot

  • componentlist

  • coordsys

  • deconvolver

  • fitter

  • flagger

  • functional

  • image

  • imagepol

  • imager

  • logsink

  • measures

  • msmetadata

  • ms

  • msplot

  • mstransformer

  • plotms

  • regionmanager

  • simulator

  • spectralline

  • quanta

  • table

  • tableplot

  • utils

  • vlafiller

  • vpmanager

Useful Constants

The following useful constants are provided:

pwkit.environments.casa.util.INVERSE_C_SM

The inverse of the speed of light, c, measured in seconds per meter. This is useful for converting between wavelength and light travel time.

pwkit.environments.casa.util.INVERSE_C_NSM

The inverse of the speed of light, c, measured in nanoseconds per meter. This is useful for converting between wavelength and light travel time.

pwkit.environments.casa.util.pol_names

A dictionary mapping CASA polarization codes to their textual names. For instance, pol_names[9] is "XX" and pol_names[7] is "LR".

pwkit.environments.casa.util.pol_to_miriad

A dictionary mapping CASA polarization codes to MIRIAD polarization codes, such that:

miriad_pol_code = pol_to_miriad[casa_pol_code]

CASA defines many more polarization codes than MIRIAD, although it is unclear whether CASA’s additional ones are ever used in practice. Trying to map a code without a MIRIAD equivalent will result in a KeyError as you might expect.

pwkit.environments.casa.util.pol_is_intensity

A dictionary mapping CASA polarization codes to booleans indicating whether the polarization is of “intensity” type. “Intensity-type” polarizations cannot have negative values; they are II, RR, LL, XX, YY, PP, and QQ.

pwkit.environments.casa.util.msselect_keys

A set of the keys supported by the CASA “MS-select” subsystem.

Useful Functions

sanitize_unicode(item)

Safely pass string values to the CASA tools.

datadir(*subdirs)

Get a path within the CASA data directory.

logger([filter])

Set up CASA to write log messages to standard output.

forkandlog(function[, filter, debug])

Fork a child process and read its CASA log output.
pwkit.environments.casa.util.sanitize_unicode(item)[source]

Safely pass string values to the CASA tools.

item

A value to be passed to a CASA tool.

In Python 2, the bindings to CASA tasks expect to receive all string values as binary data (str) and not Unicode. But pwkit often uses the from __future__ import unicode_literals statement to prepare for Python 3 compatibility, and other Python modules are getting better about using Unicode consistently, so more and more module code ends up using Unicode strings in cases where they might get exposed to CASA. Doing so will lead to errors.

This helper function converts Unicode into UTF-8 encoded bytes for arguments that you might pass to a CASA tool. It will leave non-strings unchanged and recursively transform collections, so you can safely use it just about anywhere.

I usually import this as just b and write tool.method(b(arg)), in analogy with the b'' byte string syntax. This leads to code such as:

from pwkit.environments.casa.util import tools, sanitize_unicode as b

tb = tools.table()
path = u'data.ms'
tb.open(path) # => raises exception
tb.open(b(path)) # => works
pwkit.environments.casa.util.datadir(*subdirs)[source]

Get a path within the CASA data directory.

subdirs

Extra elements to append to the returned path.

This function locates the directory where CASA resource data files (tables of time offsets, calibrator models, etc.) are stored. If called with no arguments, it simply returns that path. If arguments are provided, they are appended to the returned path using os.path.join(), making it easy to construct the names of specific data files. For instance:

from pwkit.environments.casa import util

cal_image_path = util.datadir('nrao', 'VLA', 'CalModels', '3C286_C.im')
tb = util.tools.image()
tb.open(cal_image_path)
pwkit.environments.casa.util.logger(filter='WARN')[source]

Set up CASA to write log messages to standard output.

filter

The log level filter: less urgent messages will not be shown. Valid values are strings: “DEBUG1”, “INFO5”, … “INFO1”, “INFO”, “WARN”, “SEVERE”.

This function creates and returns a CASA ”log sink” object that is configured to write to standard output. The default CASA implementation would always create a file named casapy.log in the current directory; this function safely prevents such a file from being left around. This is particularly important if you don’t have write permissions to the current directory.

pwkit.environments.casa.util.forkandlog(function, filter='INFO5', debug=False)[source]

Fork a child process and read its CASA log output.

function

A function to run in the child process

filter

The CASA log level filter to apply in the child process: less urgent messages will not be shown. Valid values are strings: “DEBUG1”, “INFO5”, … “INFO1”, “INFO”, “WARN”, “SEVERE”.

debug

If true, the standard output and error of the child process are not redirected to /dev/null.

Some CASA tools produce important results that are only provided via log messages. This is a problem for automation, since there’s no way for Python code to intercept those log messages and extract the results of interest. This function provides a framework for working around this limitation: by forking a child process and sending its log output to a pipe, the parent process can capture the log messages.

This function is a generator. It yields lines from the child process’ CASA log output.

Because the child process is a fork of the parent, it inherits a complete clone of the parent’s state at the time of forking. That means that the function argument you pass it can do just about anything you’d do in a regular program.

The child process’ standard output and error streams are redirected to /dev/null unless the debug argument is true. Note that the CASA log output is redirected to a pipe that is neither of these streams. So, if the function raises an unhandled Python exception, the Python traceback will not pollute the CASA log output. But, by the same token, the calling program will not be able to detect that the exception occurred except by its impact on the expected log output.