Skip to content

Spectroscopy

Spectroscopy-domain containers and operations.

Spectrum

A 1-D spectrum: a wavelength Grid plus per-bin flux, optional 1-sigma error, and optional mask.

The mask convention is True = invalid (a True entry marks the bin as masked / excluded), matching astropy's masked-array convention. All per-bin arrays share the wavelength Grid's dtype (float32 or float64); flux determines the channel and every other input must match it.

Use rebin to resample onto a new wavelength axis, to_f_nu / to_f_lambda to convert between flux density conventions, and synthetic_photometry to integrate through a transmission curve.

dtype property

The numpy dtype of the Spectrum's arrays.

Returns:

Type Description
dtype

Either numpy.dtype('float32') or numpy.dtype('float64'). All per-bin arrays (flux, error, wavelength values) share this dtype.

error property

The 1-sigma uncertainty array, if present.

Returns:

Type Description
ndarray or None

A new copy of the per-bin 1-sigma uncertainty, or None if the Spectrum was constructed without an error array. dtype matches the Spectrum's dtype.

flux property

The flux density array.

Returns:

Type Description
ndarray

A new copy of the per-bin flux density. dtype matches the Spectrum's dtype.

mask property

The per-bin mask, if present.

Returns:

Type Description
ndarray of bool or None

A new copy of the per-bin mask flags (True = invalid: a True entry marks the bin as masked / excluded, matching astropy's masked-array convention), or None if no mask was supplied at construction.

n_bins property

Number of bins in the spectrum.

Returns:

Type Description
int

The length of the flux array, equivalently the wavelength Grid's bin count.

wavelength property

The wavelength axis.

Returns:

Type Description
Grid

A clone of the wavelength Grid. dtype matches the Spectrum's dtype.

convolve_lsf(*, spec, resolving_power=None, sigma=None, speed_of_light=None) method descriptor

Broaden the spectrum with a Gaussian line-spread function.

The spectrum is treated as a noise-free template: only flux is convolved and the result carries no error / mask. The wavelength Grid is returned unchanged and flux is conserved, including at the spectrum edges. Works for any wavelength axis: a uniform log grid uses a single fixed kernel, anything else uses an exact per-pixel variable-width Gaussian.

Both specs describe a Gaussian whose sigma / lambda ratio is constant (sigma_lambda = sigma_lnlambda * lambda).

Parameters:

Name Type Description Default
spec (constant_r, constant_velocity)

"constant_r" uses a constant resolving power R = lambda / FWHM (requires resolving_power). "constant_velocity" uses a constant velocity dispersion (requires sigma and speed_of_light).

 "constant_r"
resolving_power float

The resolving power R for spec="constant_r".

 None
sigma float

The velocity dispersion for spec="constant_velocity", in the same unit as speed_of_light.

 None
speed_of_light float

Speed of light for spec="constant_velocity", in the same unit as sigma. noobase does not track units; consistency is the caller's responsibility.

 None

Returns:

Type Description
Spectrum

A new broadened Spectrum on the same wavelength axis.

Raises:

Type Description
ValueError

If the spectrum carries error or mask (an LSF applies only to noise-free templates — strip them first), if spec is unknown or its required companion is missing, or if the resolution is non-positive.

rebin(target, *, spacing=None, kind=None) method descriptor

Resample the spectrum onto a target wavelength axis.

Flux is propagated via overlap-weighted averaging (density-conserving: the integral of flux * bin_width is preserved over the region of overlap). Error, if present, is propagated by squaring to variance, applying the same overlap operator assuming independent source bins, and taking the square root; the result is the marginal 1-sigma per target bin. Mask, if present, is propagated as logical OR (True = invalid): a target bin is invalid iff any source bin with non-zero overlap into it is invalid.

Parameters:

Name Type Description Default
target Grid or ndarray

Target wavelength axis. If an ndarray is passed, spacing and kind must be supplied (each defaults to "linear" / "centers" when omitted but the dtype is read from the array). dtype must match the Spectrum's dtype.

 required
spacing (linear, log)

Spacing convention for building a Grid from target. Must be omitted when target is already a Grid.

 "linear"
kind (centers, edges)

Bin convention for building a Grid from target. Must be omitted when target is already a Grid.

 "centers"

Returns:

Type Description
Spectrum

A new Spectrum on the target wavelength axis.

Raises:

Type Description
ValueError

If target dtype does not match the Spectrum's dtype, or if spacing/kind are passed together with a Grid target.
Notes

When the target is finer than the source (upsampling), neighboring target bins drawing from the same source bin are strongly correlated. The per-bin sigma values returned here are still individually correct as marginals, but downstream operations that assume independent bins (for example summing under quadrature, or synthetic_photometry on the upsampled spectrum) will underestimate the true uncertainty. See Spectrum.synthetic_photometry and photometry.synthetic for the same caveat.

synthetic_photometry(*, transmission_grid, transmission_values, convention='photon_counting') method descriptor

Compute synthetic photometry through a transmission curve.

Convenience wrapper around photometry.synthetic that reuses the Spectrum's wavelength, flux, and (optional) error. Returns the band-averaged flux density, the propagated 1-sigma uncertainty (only when the Spectrum has an error array), and the geometric coverage of the filter by the spectrum.

Parameters:

Name Type Description Default
transmission_grid Grid or ndarray

Filter wavelength axis. If an ndarray is passed, its length must equal len(transmission_values) (centers) or len(transmission_values) + 1 (edges); spacing is assumed linear and kind is inferred from the length match. For log-spaced filters, pass a pre-built Grid. dtype must match the Spectrum's dtype.

 required
transmission_values ndarray

Filter transmission per bin. dtype must match the Spectrum's dtype.

 required
convention (photon_counting, energy_weighted)

Photon-counting (default) is appropriate for photon-counting detectors such as CCDs and HgCdTe arrays (including JWST NIRCam). Energy-weighted is appropriate for bolometric / energy-integrating detectors.

 "photon_counting"

Returns:

Type Description
tuple of (float, float or None, float)

(band_flux, band_error, coverage). band_error is None when the Spectrum has no error array. coverage is the fraction of the filter's transmission integral probed by the spectrum (1.0 means full coverage; a value below 1.0 means the spectrum does not span the full filter and band_flux is biased low).

Raises:

Type Description
ValueError

If dtypes mismatch across inputs, array lengths are inconsistent, convention is invalid, or the spectrum does not overlap the filter in wavelength.
Notes

The error is propagated assuming spectrum bins are statistically independent. The transmission curve's bin density does not affect this assumption — it only enters the deterministic weights. The assumption is violated if the spectrum was previously upsampled (for example via Spectrum.rebin onto a finer grid), in which case the returned band_error underestimates the true uncertainty. See Spectrum.rebin for the same caveat.

to_f_lambda(speed_of_light) method descriptor

Convert flux density from f_nu to f_lambda.

Applies f_lambda = f_nu * c / lambda^2 per bin, using each bin's center wavelength. The wavelength Grid and mask are preserved; the error array, if present, scales by the same factor element-wise.

Parameters:

Name Type Description Default
speed_of_light float

Speed of light expressed in the wavelength axis's length unit per second. For example, with the wavelength in angstroms pass 2.998e18 (Å/s). noobase does not track units; consistency is the caller's responsibility.

 required

Returns:

Type Description
Spectrum

A new Spectrum with the converted flux density.
Notes

This method does not check whether the input is in fact f_nu; it unconditionally applies the conversion factor. The caller is responsible for tracking which density the Spectrum currently represents.

to_f_nu(speed_of_light) method descriptor

Convert flux density from f_lambda to f_nu.

Applies f_nu = f_lambda * lambda^2 / c per bin, using each bin's center wavelength. The wavelength Grid and mask are preserved; the error array, if present, scales by the same factor element-wise.

Parameters:

Name Type Description Default
speed_of_light float

Speed of light expressed in the wavelength axis's length unit per second. For example, with the wavelength in angstroms pass 2.998e18 (Å/s). noobase does not track units; consistency is the caller's responsibility.

 required

Returns:

Type Description
Spectrum

A new Spectrum with the converted flux density.
Notes

This method does not check whether the input is in fact f_lambda; it unconditionally applies the conversion factor. The caller is responsible for tracking which density the Spectrum currently represents.

Synthetic Photometry

Synthetic photometry through transmission curves. Lives at noobase.spectroscopy.synthetic_photometry.

synthetic(*, spectrum_grid, spectrum_flux, spectrum_error=None, transmission_grid, transmission_values, convention='photon_counting') builtin

Compute synthetic photometry of a spectrum through a transmission curve.

Returns the band-averaged flux density, the propagated 1-sigma uncertainty (only when spectrum_error is given), and the geometric coverage of the filter by the spectrum.

All arguments are keyword-only. The dtype channel (float32 or float64) is determined by spectrum_flux; every other array argument must match.

Parameters:

Name Type Description Default
spectrum_grid Grid or ndarray

Spectrum wavelength axis. If an ndarray is passed, its length must equal len(spectrum_flux) (centers) or len(spectrum_flux) + 1 (edges); spacing is assumed linear and kind is inferred from the length match. For log-spaced spectra, pass a pre-built Grid.

 required
spectrum_flux ndarray

Flux density per bin. Determines the dtype channel for the whole call; all other arrays must match.

 required
spectrum_error ndarray

1-sigma uncertainty per bin. Same length and dtype as spectrum_flux. Default is None.

 None
transmission_grid Grid or ndarray

Filter wavelength axis. Same dtype and length-match rules as spectrum_grid, paired with transmission_values.

 required
transmission_values ndarray

Filter transmission per bin. Same dtype as spectrum_flux.

 required
convention (photon_counting, energy_weighted)

Photon-counting (default) is appropriate for photon-counting detectors such as CCDs and HgCdTe arrays (including JWST NIRCam). Energy-weighted is appropriate for bolometric / energy-integrating detectors.

 "photon_counting"

Returns:

Type Description
tuple of (float, float or None, float)

(band_flux, band_error, coverage). band_error is None when spectrum_error was not provided. coverage is the fraction of the filter's transmission integral probed by the spectrum (1.0 means full coverage; a value below 1.0 means the spectrum does not span the full filter and band_flux is biased low).

Raises:

Type Description
ValueError

If dtypes mismatch across inputs, array lengths are inconsistent, convention is invalid, or the spectrum does not overlap the filter in wavelength.
Notes

The error is propagated assuming spectrum bins are statistically independent. The transmission curve's bin density does not affect this assumption — it only enters the deterministic weights. The assumption is violated if the spectrum was previously upsampled (for example via Spectrum.rebin onto a finer grid), in which case the returned band_error underestimates the true uncertainty. See Spectrum.rebin for the same caveat.

SyntheticOperator

Pre-built synthetic photometry operator with cached weights.

Amortizes the cost of grid intersection and transmission weighting for repeated evaluation against many spectra that share the same wavelength axis and transmission curve. apply then becomes a small inner product. Useful for SED-fitting inner loops.

The operator caches both the deterministic weights and the geometric coverage (available via the coverage property), so per-spectrum calls do not recompute either.

coverage property

Geometric coverage of the filter by the operator's spectrum grid.

Returns:

Type Description
float

Fraction of the filter's transmission integral probed by the spectrum grid, in [0, 1]. A value below 1.0 means the spectrum grid does not span the full filter and band fluxes produced by apply are biased low. SED-fitting callers should threshold on this (for example, require coverage > 0.999).

dtype property

The numpy dtype of the operator's cached weights.

Returns:

Type Description
dtype

Either numpy.dtype('float32') or numpy.dtype('float64'). Arrays passed to apply must match this dtype.

apply(spectrum_flux, *, spectrum_error=None) method descriptor

Apply the operator to a spectrum flux array.

Returns the band-averaged flux density and, optionally, the propagated 1-sigma uncertainty. The geometric coverage is fixed at construction time and accessible via the coverage property; it is not returned here.

Parameters:

Name Type Description Default
spectrum_flux ndarray

Flux density per bin. Length must equal the operator's spectrum bin count and dtype must match the operator's dtype.

 required
spectrum_error ndarray

1-sigma uncertainty per bin. Same length and dtype as spectrum_flux. Default is None.

 None

Returns:

Type Description
tuple of (float, float or None)

(band_flux, band_error). band_error is None when spectrum_error was not provided.

Raises:

Type Description
ValueError

If dtypes mismatch with the operator, or if array lengths do not match the operator's spectrum bin count.
Notes

As with photometry.synthetic, the error is propagated assuming spectrum bins are statistically independent; the assumption is violated for spectra that were previously upsampled via Spectrum.rebin. See Spectrum.rebin for the same caveat.