API

Here we describe all the functions used to collapse the spectral cube which are typically called by the command line interface. However, importing these into your workflow may be useful.

In general, for the generated moment maps, MX, where X is an integer denotes a statistical moment. For the non-traditional methods, v0, dV and Fnu represent the line center, width and peak, respectively.

Note

The convolution for smooththreshold is currently experimental and is work in progress. If things look suspicious, please raise an issue.

Moment Maps

Implementation of traditional moment-map methods. See the CASA documentation for more information.

bettermoments.methods.collapse_zeroth(velax, data, rms)

Collapses the cube by integrating along the spectral axis. It will return the integrated intensity along the spectral axis, M0, and the associated uncertainty, dM0. Following Teague (2019) these are calculated by,

M_0 = \sum_{i}^N I_i \, \Delta v_{{\rm chan},\,i}

and

M_0 = \sqrt{\sum_{i\,(I_i > 0)}^N \sigma_i^2 \cdot \Delta v_{{\rm chan},\,i}^2}

where \Delta v_i and I_i are the chanenl width and flux density at the i^{\rm th} channel, respectively and the sum goes over the whole axis.

Parameters:
  • velax (ndarray) – Velocity axis of the cube.
  • data (ndarray) – Flux densities or brightness temperature array. Assumes that the first axis is the velocity axis.
  • rms (float) – Noise per pixel in same units as data.
Returns:

M0, the integrated intensity along provided axis and dM0, the uncertainty on M0 in the same units as M0.

Return type:

M0 (ndarray), dM0 (ndarray)

bettermoments.methods.collapse_first(velax, data, rms)

Collapses the cube using the intensity weighted average velocity (or first moment map). For a symmetric line profile this will be the line center, however for highly non-symmetric line profiles, this will not give a meaningful result. Following Teague (2019), the line center is given by,

M_1 = \frac{\sum_i^N I_i v_i}{\sum_i^N I_i}

where v_i and I_i are the velocity and flux density at the i^{\rm th} channel, respectively and the sum goes over the whole axis. In addition, the uncertainty is given by,

\delta M_1 = \sqrt{\sum_{i\,(I_i > 0)}^N \sigma_i^2 \cdot (v_i - M_1)^2}

where \sigma_i is the rms noise.

Parameters:
  • velax (ndarray) – Velocity axis of the cube.
  • data (ndarray) – Flux densities or brightness temperature array. Assumes that the zeroth axis is the velocity axis.
  • rms (float) – Noise per pixel in same units as data.
Returns:

M1, the intensity weighted average velocity in units of velax and dM1, the uncertainty in the intensity weighted average velocity with same units as v0.

Return type:

M1 (ndarray), dM1 (ndarray)

bettermoments.methods.collapse_second(velax, data, rms)

Collapses the cube using the intensity-weighted average velocity dispersion (or second moment). For a symmetric line profile this will be a measure of the line width. Following Teague (2019) this is calculated by,

M_2 = \sqrt{\frac{\sum_i^N I_i (v_i - M_1)^2}{{\sum_i^N I_i}}}

where M_1 is the first moment and v_i and I_i are the velocity and flux density at the i^{\rm th} channel, respectively. The uncertainty is given by,

\delta M_2 &= \frac{1}{2 M_2} \cdot \sqrt{\sum_{i\,(I_i > 0)}^N \sigma_i^2 \cdot \big[(v_i - M_1)^2 - M_2^2\big]^2}

where \sigma_i is the rms noise in the i^{\rm th} channel.

Parameters:
  • velax (ndarray) – Velocity axis of the cube.
  • data (ndarray) – Flux densities or brightness temperature array. Assumes that the first axis is the velocity axis.
  • rms (float) – Noise per pixel in same units as data.
Returns:

M2 is the intensity weighted velocity dispersion with units of velax. dM2 is the unceratinty of M2 in the same units.

Return type:

M2 (ndarray), dM2 (ndarray)

bettermoments.methods.collapse_eighth(velax, data, rms)

Take the peak value along the provided axis. The uncertainty is the RMS noise of the image.

Parameters:
  • velax (ndarray) – Velocity axis of the cube. Not needed.
  • data (ndarray) – Flux densities or brightness temperature array. Assumes that the first axis is the velocity axis.
  • rms (float) – Noise per pixel in same units as data.
Returns:

The peak value, M8, and the associated uncertainty, dM8.

Return type:

M8 (ndarray), dM8 (ndarray)

bettermoments.methods.collapse_ninth(velax, data, rms)

Take the velocity of the peak intensity along the provided axis. The uncertainty is half the channel width.

Parameters:
  • velax (ndarray) – Velocity axis of the cube.
  • data (ndarray) – Flux densities or brightness temperature array. Assumes that the first axis is the velocity axis.
  • rms (float) – Noise per pixel in same units as data.
Returns:

The velocity value of the peak value, M9, and the associated uncertainty, dM9.

Return type:

M9 (ndarray), dM9 (ndarray)

bettermoments.methods.collapse_maximum(velax, data, rms)

A wrapper returning the result of both bettermoments.collapse_cube.collapse_eighth() and bettermoments.collapse_cube.collapse_ninth().

Parameters:
  • velax (ndarray) – Velocity axis of the cube.
  • data (ndarray) – Flux densities or brightness temperature array. Assumes that the first axis is the velocity axis.
  • rms (float) – Noise per pixel in same units as data.
Returns:

The peak value, M8, and the associated uncertainty, dM8. The velocity value of the peak value, M9, and the associated uncertainty, dM9.

Return type:

M8 (ndarray), dM8 (ndarray), M9 (ndarray), dM9 (ndarray)

Non-Traditional Methods

bettermoments.methods.collapse_quadratic(velax, data, rms)

Collapse the cube using the quadratic method presented in Teague & Foreman-Mackey (2018). Will return the line center, v0, and the uncertainty on this, dv0, as well as the line peak, Fnu, and the uncertainty on that, dFnu. This provides the sub-channel precision of bettermoments.collapse_cube.collapse_first() with the robustness to noise from bettermoments.collapse_cube.collapse_ninth().

Parameters:
  • velax (ndarray) – Velocity axis of the cube.
  • data (ndarray) – Flux density or brightness temperature array. Assumes that the zeroth axis is the velocity axis.
  • rms (float) – Noise per pixel in same units as data.
Returns:

v0, the line center in the same units as velax with dv0 as the uncertainty on v0 in the same units as velax. Fnu is the line peak in the same units as the data with associated uncertainties, dFnu.

Return type:

v0 (ndarray), dv0 (ndarray), Fnu (ndarray), dFnu (ndarray)

bettermoments.methods.collapse_width(velax, data, rms)

Returns an effective width, a rescaled ratio of the integrated intensity and the line peak. For a Gaussian line profile this would be the Doppler width as the total intensity is given by,

M_0 = \sum_{i}^N I_i \, \Delta v_{{\rm chan},\,i}

where \Delta v_i and I_i are the chanenl width and flux density at the i^{\rm th} channel. If the line profile is Gaussian, then equally

M_0 = \sqrt{\pi} \times F_{\nu} \times \Delta V

where F_{\nu} is the peak value of the line and \Delta V is the Doppler width of the line. As M_0 and F_{\nu} are readily calculated using bettermoments.collapse_cube.collapse_zeroth() and bettermoments.collapse_cube.collapse_quadratic(), respectively, \Delta V can calculated through \Delta V = M_{0} \, / \,
(\sqrt{\pi} \, F_{\nu}). This should be more robust against noise than second moment maps.

Parameters:
  • velax (ndarray) – Velocity axis of the cube.
  • data (ndarray) – Flux densities or brightness temperature array. Assumes that the first axis is the velocity axis.
  • rms (float) – Noise per pixel in same units as data.
Returns:

The effective velocity dispersion, dV and ddV, the associated uncertainty.

Return type:

dV (ndarray), ddV (ndarray)

(Higher Order) Gaussian Fits

bettermoments.methods.collapse_gaussian(velax, data, rms, indices=None, chunks=1, **kwargs)

Collapse the cube by fitting a Gaussian line profile to each pixel. This function is a wrapper of collapse_analytical which provides more details about the arguments.

Parameters:
  • velax (ndarray) – Velocity axis of the cube.
  • data (ndarray) – Maksed intensity or brightness temperature array. The first axis must be the velocity axis.
  • rms (float) – Noise per pixel in same units as data.
  • indices (Optional[list]) – A list of pixels described by (y_idx, x_idx) tuples to fit. If none are provided, will fit all pixels.
  • chunks (Optional[int]) – Split the cube into chunks sections and run the fits with separate processes through multiprocessing.pool.
Returns:

gv0 (ndarray), dgv0 (ndarray), gFnu (ndarray), dgFnu (ndarray), gdV (ndarray), dgdV (ndarray):

The Gaussian center, gv0, the line peak, gFnu and the Doppler width, gdV, all with associated uncertainties, dg*.

bettermoments.methods.collapse_gaussthick(velax, data, rms, indices=None, chunks=1, **kwargs)

Collapse the cube by fitting a Gaussian line profile with an optically thick core to each pixel. This function is a wrapper of collapse_analytical which provides more details about the arguments.

Parameters:
  • velax (ndarray) – Velocity axis of the cube.
  • data (ndarray) – Maksed intensity or brightness temperature array. The first axis must be the velocity axis.
  • rms (float) – Noise per pixel in same units as data.
  • indices (Optional[list]) – A list of pixels described by (y_idx, x_idx) tuples to fit. If none are provided, will fit all pixels.
  • chunks (Optional[int]) – Split the cube into chunks sections and run the fits with separate processes through multiprocessing.pool.
Returns:

gtv0 (ndarray), dgtv0 (ndarray), gtFnu (ndarray), dgtFnu (ndarray), gtdV (ndarray), dgtdV (ndarray), gttau (ndarray), dgttau (ndarray):

The Gaussian center, gtv0, the line peak, gtFnu, the Dopler width, gtdV, and the effective optical depth, gttau, all with associated uncertainties, dgt*.

bettermoments.methods.collapse_gausshermite(velax, data, rms, indices=None, chunks=1, **kwargs)

Collapse the cube by fitting a Gaussian line profile with an optically thick core to each pixel. This function is a wrapper of collapse_analytical which provides more details about the arguments.

Parameters:
  • velax (ndarray) – Velocity axis of the cube.
  • data (ndarray) – Maksed intensity or brightness temperature array. The first axis must be the velocity axis.
  • rms (float) – Noise per pixel in same units as data.
  • indices (Optional[list]) – A list of pixels described by (y_idx, x_idx) tuples to fit. If none are provided, will fit all pixels.
  • chunks (Optional[int]) – Split the cube into chunks sections and run the fits with separate processes through multiprocessing.pool.
Returns:

ghv0 (ndarray), dghv0 (ndarray), ghFnu (ndarray), dghFnu (ndarray), ghdV (ndarray), dghdV (ndarray), ghh3 (ndarray), dghh3 (ndarray), ghh4 (ndarray), dghh4 (ndarray):

The Gaussian center, ghv0, the line peak, ghFnu, the Dopler width, ghdV, with additional expansion terms ghh3`, the assymetry of the line and ``ghh4, the saturation of the line core., All values come with their associated uncertainties, dgt*.