API reference¶

The user-facing API is a single function, frizzle.frizzle(). The helpers in frizzle.utils are documented below for completeness.

frizzle¶

frizzle.frizzle(λ_out, λ, flux, ivar=None, mask=None, flags=None, censor_missing_regions=True, n_modes=None)¶

Combine spectra by forward modeling.

Parameters:

λ_out (array) – The wavelengths to sample the combined spectrum on.
λ (array) – An N-length array of wavelength values (the wavelengths of individual pixels).
flux (array) – An N-length array of input flux values.
ivar (array | None) – [optional] An N-length array of inverse variances.
mask (array | None) – [optional] A boolean mask of which pixels to use when combining spectra (pixels with mask True get ignored). The mask is used to ignore pixel values when combining spectra, but the mask is not used when computing combined pixel flags.
flags (array | None) – [optional] An optional integer array of bitwise flags. If given, this should be shape (N, ).
censor_missing_regions (bool | None) – [optional] If True, then regions where there is no data will be set to NaN in the combined spectrum. If False the values evaluated from the model will be reported (and have correspondingly large uncertainties) but this will produce unphysical features.
n_modes (int | None) – [optional] The number of Fourier modes to use. If None is given then this will default to len(λ_out).

Returns:

A four-length tuple of (y_star, C_star, flags, meta) where:

y_star is the combined fluxes,
C_star is the covariance of the combined fluxes,
flags are the combined flags, and
meta is a dictionary.

Note that the input expects inverse variance ivar, but the output returns C_star, the covariance of the combined fluxes.

frizzle.utils¶

frizzle.utils.get_modes(n_modes, λ_out, mask)¶

Choose the number of Fourier modes to use.

If n_modes is provided it is returned unchanged. Otherwise the value is set to the smaller of len(λ_out) and the number of unmasked pixels, and rounded down to the nearest odd integer.

Parameters:

n_modes (int | None) – The user-specified number of modes, or None to choose automatically.
λ_out (ArrayLike) – The wavelengths to sample the combined spectrum on.
mask (ArrayLike) – A boolean array where True marks masked pixels.

Returns:

The number of Fourier modes to use.

Return type:

int

frizzle.utils.check_inputs(λ_out, λ, flux, ivar, mask)¶

Validate and normalize the inputs for combining spectra.

Concatenates per-spectrum arrays into single 1D arrays, fills in defaults for ivar and mask, sorts λ_out, and extends the mask to cover pixels that fall outside the resampling range.

Parameters:

λ_out (ArrayLike) – The wavelengths to sample the combined spectrum on.
λ (ArrayLike) – The input wavelengths, either a single array or a sequence of arrays that will be concatenated.
flux (ArrayLike) – The input fluxes, with the same shape conventions as λ.
ivar (ArrayLike | None) – The input inverse variances, with the same shape conventions as λ. If None, an array of ones is used.
mask (ArrayLike | None) – A boolean mask where True marks pixels to ignore, with the same shape conventions as λ. If None, no pixels are masked.

Returns:

A tuple (λ_out, λ, flux, ivar, mask) of normalized arrays.

Return type:

Tuple[Array, Array, Array, Array, Array]

frizzle.utils.combine_flags(λ_out, λ, flags)¶

Combine flags from input spectra.

For each set bit, a flag is propagated to an output pixel when the nearest flagged input wavelength is within one output pixel width.

Parameters:

λ_out (ArrayLike) – The wavelengths to sample the combined spectrum on.
λ (ArrayLike) – The input wavelengths.
flags (ndarray[tuple[Any, ...], dtype[integer]] | None) – An array of integer flags, or None if no flags are provided.

Returns:

An array of combined integer flags with shape λ_out.shape.

Return type:

ndarray[tuple[Any, …], dtype[integer]]

frizzle.utils.separate_flags(flags=None)¶

Separate flags into a dictionary of flags for each bit.

Parameters:: flags (ArrayLike | None) – An M-length array of flag values.
Returns:: A dictionary of flags, where each key is a bit and each value is an array of 0s and 1s.
Return type:: Dict[int, ndarray[tuple[Any, …], dtype[bool]]]

frizzle.test_utils¶

Synthetic-data helpers used throughout the documentation and tests.

frizzle.test_utils.make_one_dataset(dx, snr, N=8, x_min=8.7, x_max=8.7025, R=135000.0, lines_per_x=20000.0, ew_max_x=3e-05, ew_power=5.0, badfrac=0.01, profile_type='gaussian', profile_width=None, random_seed=None, Delta_xs=None)¶

Generate one synthetic multi-epoch dataset.

Parameters:

dx – Pixel spacing in log-wavelength.
snr – Continuum signal-to-noise ratio per pixel.
N – Number of epochs.
x_max (x_min,) – Log-wavelength range.
R – Spectral resolving power.
lines_per_x – Mean line density per unit log-wavelength.
ew_max_x – Max equivalent width.
ew_power – Power-law index for the EW distribution.
badfrac – Fraction of pixels marked bad.
profile_type – ‘gaussian’, ‘lorentzian’, or ‘voigt’.
profile_width – Profile width(s); defaults to 1/R.
random_seed – Seed for reproducibility.
Delta_xs – Per-epoch Doppler shifts (defaults to a sinusoid).

Returns:

(xs, ys, y_ivars, bs, Delta_xs, line_args) where line_args is a tuple (line_xs, line_ews, profile_func) accepted by true_spectrum().

frizzle.test_utils.true_spectrum(xs, doppler, line_xs, line_ews, profile_func)¶: The noise-free template at log-wavelengths xs, Doppler-shifted by doppler.