Command Line Interface¶
This is the preferred way to interact with bettermoments. If the install
has gone successfully, you should be able to run bettermoments from any
directory using,
bettermoments path/to/cube.fits
Which, by default, will use the collapse_quadratic()
function to calculate line center and line peak maps. This will automatically
extract the data array and spectral axis from the cube and provide them to the
appropriate functions.
Warning
The command line interface will automatically overwrite any files with the
same name. Make sure that you move or rename old files which you want to
keep or use the --nooverwrite flag.
Different Methods¶
To change the method applied to collapse the cube, use the -method [name]
flag, where the names of the functions are found in the API.
For example, to calculate the zeroth moment map,
bettermoments path/to/cube.fits -method zeroth
which will produce a *M0.fits file with the uncertainties in *dM0.fits.
Smoothing¶
It is sometimes useful to smooth along the spectral axis of the data prior to calculating the requested moment map. While this can remove high frequency noise and usually lead to a better determination of the desired statistic, any level of smoothing will reduce peak values of a spectrum, so any statistic based on the absolute value of the data will be under-estimated.
Smoothing is achieved with the -smooth [window] flag, where the window
size as the number of channels is given. By default this is a top hat function
which is applied along the spectral axis prior to any other calculations
(including the estimation of the RMS).
It is possible to request a Savitzky-Golay filter using the additional
-polyorder [order] flag which denotes the order of the polynomal used
in the filter. Note that this needs to be greater than 1, but also two less than
the window size.
bettermoments path/to/cube/fits -smooth 5
will smooth the data with a top-hat kernel with a width of 5 channels while
bettermoments path/to/cube/fits -smooth 5 -polyorder 2
will smooth the data with Savitzky-Golay filter with a window size of 5 channels and use a polynomial of order 2.
Masking¶
When making a moment map it is often useful, sometimes necessary, to mask the
data to reduce the noise in the resulting image. There are a couple of different
options in bettermoments to do this.
Channel Selection¶
The most straight forward is a simple channel selection using the -firstchannel [chan]
and -lastchannel [chan] arguments. By default these span the entire cube range.
For example,
bettermoments path/to/cube.fits -method zeroth -firstchannel 5 -lastchannel 10
would create a zeroth moment map using the channels 5 to 10 inclusively.
Threshold Clipping¶
One of the most common approaches is to apply a ‘sigma clip’, essentially
masking any pixels below some user-specified threshold, usual in untis of the
background RMS. In bettermoments this is applied with the -clip [value]
argument. For example,
bettermoments path/to/cube.fits -method zeroth -clip 2
would calculate a zeroth moment map out of all the pixels which have an absolute
value of greater than or equal to 2 * RMS. The background RMS is automatically
calculated using the central 50% of the pixels in the first and last 5 channels.
The number of channels used for this estimation can be changed with the
-noisechannels argument. Rather than calculating the RMS automatically, you
can specify their own value with the -rms argument. Note that internally
the RMS is assumed to be homogeneous, both spatially and spectrally.
If you want include asymmetric bounds you can include two -clip values. For
example,
bettermoments path/to/cube.fits -method zeroth -clip -3 2
would mask out all pixel values between -3 * RMS and 2 * RMS.
A threshold mask like the above can sometimes leave sharp boundaries if you have
large spatial gradients in the intensity. To counter this it is possible to
convolve the threshold mask with a 2D Gaussian kernel to smooth these edges
with the -smooththreshold [width] argument where the width is given in units
of the beam FWHM (or pixel scale if a beam isn’t provided). Internally this will
make a copy of the data, convolve with the appropriate kernel, then generate
a boolean mask where the convolved map meets the specified -clip criteria.
Warning
If you choose to smooth the threshold map, remember that the RMS in this
image will be reduced due to the smoothing. The automatic calculation of
the RMS is done before the smoothing of the map so it will be appropriate
to provide a user-specified one with -rms [value].
User-Defined Masks¶
Sometimes you may want to include a user-defined mask, such at the CLEAN mask used when imaging interferometric data. As long as the mask has the same shape as the data in the image cube you can include this with,
bettermoments path/to/cube.fits -mask path/to/mask.fits
Combing Masks¶
If you’ve specified both a user-defined mask and provided a clip value then
bettermoments will combine the two masks by default using AND. If you
would rather choose a less conservative OR combination then you can include
the -combine or argument.
Returning Masks¶
It is often useful to have a copy of the mask used to generate the moment map
such that you can overplot it in channel maps to help make sense of what you’re
seeing. To do this, use the --returnmask flag.