calculate_moments#

irispy.utils.moments.calculate_moments( cube, *, rest_wavelength=None, wings=None, integrated=False, min_intensity=None, saturation_limit=None, )[source]#

Calculate the 0th, 1st, and 2nd spectral moments of a data cube.

The moments are computed along the spectral (wavelength) axis for each spatial pixel:

0th moment: total intensity, \(\sum I(\lambda_i)\) (or \(\int I(\lambda) \, d\lambda\) when integrated=True)
1st moment: centroid wavelength, \(\sum \lambda_i I(\lambda_i) / \sum I(\lambda_i)\)
2nd moment: standard deviation, \(\sqrt{\sum (\lambda_i - \lambda_0)^2 I(\lambda_i) / \sum I(\lambda_i)}\)

Parameters:

cube (irispy.spectrograph.SpectrogramCube) – The input data cube. Must have a spectral (wavelength) axis.
rest_wavelength (astropy.units.Quantity, optional) – The rest wavelength of the spectral line. Required if wings is given.
wings (astropy.units.Quantity, optional) – The spectral range around rest_wavelength to include in the calculation. Must be an Quantity with appropriate units (e.g., nm or Angstrom). If a scalar Quantity, it is applied symmetrically. If a tuple of two Quantities, they are the lower and upper offsets respectively.
integrated (bool, optional) – If True, the 0th moment is computed as \(\int I(\lambda) \, d\lambda\) with units of DN·nm. If False (default), it is computed as \(\sum I(\lambda)\) with units of DN (i.e., per-pixel sum, matching the convention used in Gaussian fitting).
min_intensity (float, optional) – Minimum integrated (or per-pixel) intensity required for a pixel to be considered valid. Pixels with intensity below this value have all their moments (including intensity) set to NaN. Useful for excluding noisy low-signal pixels.
saturation_limit (float, optional) – Maximum allowed peak intensity in any spectral bin. Pixels where any bin in the (cropped) profile exceeds this value are treated as saturated and have all their moments set to NaN.

Returns:

A collection containing 2D SpectrogramCube objects with the spatial WCS preserved from the input cube.

Always present:

"intensity" — 0th moment (total intensity)
"centroid" — 1st moment (centroid wavelength)
"width" — 2nd moment (standard deviation)

Additionally, if rest_wavelength is provided:

"velocity" — Doppler shift from the centroid in km/s
"velocity_width" — line width converted to velocity units in km/s

Return type:

irispy.spectrograph.RasterCollection

Notes

Negative and non-finite (NaN/inf) data values are set to zero before computing moments.
Wavelength coordinates are converted to nm internally, so centroid and width are always returned in nm.
For a uniform spectral grid, the 1st and 2nd moments are identical regardless of the integrated setting because the pixel spacing cancels out in the ratio.

References