CASA Region Format Examples

Regions are used in CASA to identify particular positions or areas in images, and particular volumes in image cubes. Common uses of regions include defining clean boxes, performing image analysis, and cutting out subimages. Additionally, the region format includes annotations, allowing line art and text to be drawn on images.

In CASA, regions are simple ASCII files that use a flexible combination of shapes and coordinate systems to define the desired positions, areas, volumes, etc. A CASA Region Text File (CRTF) can either be written with a text editor, or created interactively with the CASA viewer.

The CRTF can be given directly to CASA tasks, such as clean, using the mask parameter:

# In CASA
inp clean
mask = 'myCRTF.txt'

Note that with clean, <imagename>.mask will also be used as a mask if it exists, in addition to anything input with the mask parameter. Clean can also accept multiple regions, and will take the union of these.

# In CASA
inp clean
mask = ['myCRTF_1.txt', 'myCRTF_2.txt', 'myCRTF_3.txt']

Clean is the only task or tool that accepts a CRTF as the mask parameter. Clean is also the only task or tool that can accept a list of masks -- clean even accepts a mix of different formats in the same list. This makes the clean task extraordinarily flexible in regard to regions, but also very unique; all other tasks and tools will only accept a single CRTF through their region parameter.

Fortunately, multiple CRTFs can be combined into a single CRTF by simply concatenating the text files, so this is not an issue with this region format. Here is one way to concatenate text files in a CASA script. Text files 1 and 2 will be combined and a new file, 3 will be written:

# In CASA
os.system( 'cat ' + 'myCRTF_1.txt' + ' ' + 'myCRTF_2.txt' + ' > ' + 'myCRTF_3.txt' )

Now for some examples of the CRTF used with other tasks (remember to use the region parameter):

We can use immath to cut out and save a subimage defined by a region:

# In CASA
default(immath)
imagename = ['myImage.image']
mode = 'evalexpr'
expr = 'IM0'
region = 'myCRTF.txt'
go()

We can fit a 2-dimensional Gaussian to the pixels within a region, using the task imfit:

# In CASA
default(imfit)
imagename = 'myImage.image'
region = 'myCRTF.txt'
go()

To calculate image statistics using the pixel values within your region, we can use the imstat task. If we call it like a function, it will return a python dictionary containing various calculated values. Each value is indexed by a keyword. We list the available keywords and then print the one:

# In CASA
mystats = imstat( imagename = 'myImage.image', region = 'myCRTF.txt')
print mystats.keys()
print mystats['rms']

To extract pixel values within a region, we can use imval. It will return a dictionary whose keyword 'data' will contain a numpy array with the pixel values.

# In CASA
myVal = imval(imagename='myImage.image', region='myCRTF.txt')
myData = myVal['data']

Other tasks that may accept a CRTF include:

• imcontsub
• widefield
• mosaic
• imcollapse
• immoments
• imsmooth
• specfit

A CRTF can also be given to methods in the CASA image analysis (ia) toolkit, but not directly. This is because the lattice region format accepted by tools needs to be a Regionmanager Object Python Dictionary (ROPD).

The ROPD format combines the information contained in the CRTF with information about the coordinate system of a particular image so that they can be properly used together. While tasks in fact do this behind the scenes, you will need to create the ROPD yourself if you want to pass a region to a toolkit method.

Fortunately, it is easy to create the ROPD from the CRTF, plus the image or image cube of interest. First, one needs to open the image with the image analysis toolkit:

# In CASA
ia.open( 'myImage.image' )

Now, make a ROPD from your CRTF using a method from the regions toolkit:

# In CASA
myRGN = rg.fromtextfile(filename='myCRTF.txt', shape=ia.shape(), csys=ia.coordsys().torecord())

You can now pass this ROPD to different image analysis tools. For example, to calculate various image statistics using only the pixels within your region:

# In CASA
mystats = ia.statistics(region = myRGN)

You can retrieve the image pixel values within your region as a numpy array:

# In CASA
myArray = ia.getregion(region = myRGN)

Or, to cut out and save a subimage containing only the pixels within your region:

# In CASA
ia.subimage(region = myRGN, outfile='subimage.image')

Be sure to close the image when you are done:

# In CASA
ia.close()

Also, here is one method, using the python pickle module, to save a (binary) hardcopy of your ROPD to reuse in another CASA session:

# In CASA
import pickle
out1 = ia.open('myRGN.pkl', 'wb')
pickle.dump(myRGN, out1)
out1.close()

Which can be loaded back into CASA with:

# In CASA
import pickle
in1 = ia.open('myRGN.pkl', 'rb')
myRGN = pickle.load(in1)
in1.close()