richteague / keplerian_mask

Make a Keplerian mask for CLEANing with CASA.

keplerian_mask.py

A script to build a Keplerian mask based to be used for CLEANing or moment map analysis. This will grab the image properties (axes, beam properties and so on) from the provide CASA image.

Basic Usage

First, load up the function into the CASA instance:

CASA <X>: execfile('path/to/keplerian_mask.py')
     ...: Successfully imported `make_mask`.

With this loaded, to make a Keplerian mask you just need to provide some simple geometrical properties of the disk:

CASA <X>: make_mask(image='image_name.image',
     ...:           inc=30.0,
     ...:           PA=75.0,
     ...:           mstar=1.0,
     ...:           dist=140.0,
     ...:           vlsr=5.1e3)         

Hopefully the parameters are obvious, but for clarity, inc is the disk inclination in degrees, PA is the disk position angle in degrees, measured from North to the redshifted major axis in an anti-clockwise fashion. mstar is the stellar mass in solar masses, dist is the source distance in parsec and vlsr is the systemic velocity in meters per second.

This command will produce a new file, image_name.mask.image, which is the mask which can be passed to future tclean calls or exported as a FITS file.

Additional Parameters

There are a few additional options to make a better fitting mask to your data.

Inner and Outer Radii

The r_min and r_max arguments allow you to tailor the masks inner and outer radii to the emission that you observe. Both of these values are given in arcseconds.

For example, to have a ring-like mask between 0.5 and 2.5 arcseconds in (deprojected) radius:

CASA <X>: make_mask(image='image_name.image',
     ...:           inc=30.0,
     ...:           PA=75.0,
     ...:           mstar=1.0,
     ...:           dist=140.0,
     ...:           vlsr=5.1e3,
     ...:           r_min=0.5,
     ...:           r_max=2.5)

Convolution

The mask can be convolved to smooth out the edges and give a bit of a buffer between the mask edge and the emission edge. There are two ways this can be done, either by including a convolution with the rescaled beam with the nbeams parameter:

CASA <X>: make_mask(image='image_name.image',
     ...:           inc=30.0,
     ...:           PA=75.0,
     ...:           mstar=1.0,
     ...:           dist=140.0,
     ...:           vlsr=5.1e3,
     ...:           nbeams=1.0)

Or by convolving with a circular beam with a FWHM in arcseconds given by target_res:

CASA <X>: make_mask(image='image_name.image',
     ...:           inc=30.0,
     ...:           PA=75.0,
     ...:           mstar=1.0,
     ...:           dist=140.0,
     ...:           vlsr=5.1e3,
     ...:           target_res=1.0)

Each one of these will use CASA's imsmooth task to convolve the mask. As the convolution will result in non-boolean values, the threshold parameter dictates what is considered what is masked and what is not. A default of 0.01 is assumed, with values closer to 1 resulting in less conservative masks.

Elevated Emission Surfaces

We can also include a non-zero emission height for molecules like 12CO. This can either by specified by a constant z/r value with the zr argument,

CASA <X>: make_mask(image='image_name.image',
     ...:           inc=30.0,
     ...:           PA=75.0,
     ...:           mstar=1.0,
     ...:           dist=140.0,
     ...:           vlsr=5.1e3,
     ...:           zr=0.3)

If you want a more complex emission surface you can define a function which takes the midplane radius in arcseconds and returns the emission height in arcseconds.

CASA <X>: def z_func(r):
     ...:     return 0.3 * r**1.5

CASA <X>: make_mask(image='image_name.image',
     ...:           inc=30.0,
     ...:           PA=75.0,
     ...:           mstar=1.0,
     ...:           dist=140.0,
     ...:           vlsr=5.1e3,
     ...:           z_func=z_func)

Radially Varying Line Widths

With higher spatial resolutions it is possible to resolve the radially changing line width of emission lines. This manifests as a change in the width of the emission pattern as a function of radius. We assume that the radial profile of the line width (here we are describing the Doppler parameter, so a factor of 1.665 times smaller than the FWHM, is well described by a powerlaw,

where dV0 and dVq are parameters which can control this surface. The default values are 300 m/s for dV0 and -0.5 for dVq.

CASA <X>: make_mask(image='image_name.image',
     ...:           inc=30.0,
     ...:           PA=75.0,
     ...:           mstar=1.0,
     ...:           dist=140.0,
     ...:           vlsr=5.1e3,
     ...:           dV0=500.0,
     ...:           dVq=-0.45)

Author

Written by Richard Teague ([email protected]), 2020.

keplerian_mask's Issues

make_mask is not working when image is not specified

The function make_mask is not working in the case where the user does not specify an image (i.e. image=None). This happens because if image=None, then an error occurs in the function _get_offsets(image, restfreqs) because imhead(image, mode='list') returns False.
The question is then how to calculate the mask in the case where image=None. Currently, the user is just expected to provide x_axis, y_axis, s_axis and v_axis. If the user does not provide restfreqs, or if len(restfreqs) is 1, then the mask might just be calculated centered around vlsr. But if the user provides several rest frequencies, then the meaning of the provided v_axis becomes unclear (which of the provided rest frequencies should be centered at vlsr?). One could define that the first element of restfreqs should be centered at vlsr, but it seems a little clunky. (Note that in the case where an image is provided, the restfreq specified in the header plays this role of a "master restfreq".)
Alternatively, we might request the user to provide a frequency axis instead of v_axis. However, in that case the user needs to be forced to provide restfreqs. This option would also make it easier to later enhance the code to produce a fits image rather than just a numpy array in the cases where no input image is specified.
If we agree on a plan on how to solve this, I might be able to code an open a pull request.

Missing Stokes axis for images without Stokes.