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), gdV (ndarray), dgdV (ndarray), gFnu (ndarray), dgFnu (ndarray):

The Gaussian center, gv0, the Doppler line width, gdV and line peak, gFnu, 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), gtdV (ndarray), dgtdV (ndarray), gtFnu (ndarray), dgtFnu (ndarray), gttau (ndarray), dgttau` (ndarray):

The Gaussian center, gtv0, the Dopler width, gtdV, the line peak, gtFnu, 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*.