Masking images for analysis

How to mask an image for further analysis (e.g. for moment analyses)

Here we describe how to create masked images. This implies to mark pixels as blanked values (different to zeros) at places that shall not be considered further. A typical application is to blank all noise values and sidelobes with the goal to obtain a data cube that has only reliable flux pixels in it.

Versioning note (August 2021): In CASA 6, under the standard NRAO installation, ia is imported as iatool

1) Mask all values below a threshold

Say, you want to blank (mask) all pixels in your image image.im below a value of 126mJy/beam (if your image has the units of mJy/beam). You can do this with ia.calcmask:

ia.open('image.im')
ia.calcmask(mask='image.im > 0.0126', name='mymask1')
ia.done()

this will create a mask with the profane name mymask1 within the image cube image.im. Supported is the full LEL syntax. All values above the 0.0126 threshold are kept, the values below that threshold are blanked. This mask can be manipulated with other tools

2) Create regions and mask the values

A threshold is not always sufficient and one would like to mask values that are supposedly not real or not under consideration (e.g. sidelobes).

First, create a region file for an entire cube containing plane-by-plane regions that encompass the emission features of interest (unfortunately the current viewer only does so on a single plane). We use the im.drawmask tool to do so. As this is an imager tool, we have to give an input visibility when opening, even though we will only be working on the image.

im.open('fantasticvis.ms')
im.drawmask(image='image.im',mask='blank3.mask')

This command should launch the viewer in a familiar looking way - you have the same interface as for interactive cleaning. Use regions to select your object in each channel and it shows up in as you would for interactive clean. You want to use a separate region for each plane as we are trying to very precisely determine where there is source or not. Make sure to adjust the stretch so that the lowest level emission can be clearly seen against the background - you don't want to accidentally include noise because you couldn't see it. When you're done press the blue continue arrow as a way to quit. Then close the imager tools

im.close

You can check that this worked by looking at it in the viewer, looking at the image.im or within the image.im file/directory, by looking at the blank3.mask directly. In the mask, there are 1's for the regions we marked as having signals and 0's elsewhere.

Masks are full of boolean values - True 's and False 's In order to proceed, we need to make a mask of the mask This is done with calcmask again: (see 6.5.2 of CASA guide & toolbox tricks) Open the mask image and create a mask where all values below 0.5 are masked (to distinguish between 0s and 1s):

ia.open('blank3.mask')
ia.calcmask('"blank3.mask">0.5')
ia.close()

This has created something called mask0 We can also see this by:

ls blank3.mask

3) combining a mask with a masked image

Now we want to use immath to apply a mask to an image that already has a mask inside, i.e. we want to combine the masked image created in step 1) with the mask of step 2):

immath(imagename='image.im',mode='evalexpr',
expr='IM0',outfile='imagemasked.im',mask='mask(blank3.mask)')

This evaluates the input image.im (with its clipped mask) and applies the mask blank3.mask, writing out to imagemasked.im

Load this into viewer to check that things worked the way you expected, We should just see the selected signal.

4) copy a mask from one image to another image

If you look at the master image created above, you'll notice that we have a mask0 file within it - we want to apply this mask to other images of the exact same dimensions as image.im (e.g. from a smoothed to an unsmoothed version, or to one that was differently weighted). The way to do this is to use the maskhandler tool.

ia.open('otherimage.im')
ia.maskhandler('copy',['imagemasked.im:mask0', 'newmask'])
ia.maskhandler('set','newmask')
ia.done()

You may now use this image for further analysis, e.g. to create moment maps that are not contaminated by noise or sidelobes, or objects that you manually removed earlier.