sheap.Sheapectral.Utils.SpectralSetup module

Spectral preparation & masking utilities.

This module provides small, JAX‑friendly helpers to: - hard‑cut spectra to wavelength windows, - pad a missing error channel, - normalize/reshape batches to a common pixel length, - build robust masks and uncertainty arrays for fitting.

Notes

  • All functions are written to be light on copies and JAX‑compatible

    (using jnp where the arrays participate in later JAX code).

cut_spectra(spectra, xmin, xmax)[source]

Hard cut a spectrum to a wavelength interval.

Parameters:

  • spectra (ndarray | jax.numpy.ndarray) – Array with shape (C, N) whose first row is wavelength [Å].

  • xmin (float) – Interval bounds.

  • xmax (float) – Interval bounds.

Returns:

The sliced spectrum with pixels xmin ≤ λ ≤ xmax.

Return type:

ArrayLike

mask_builder(sheap_array, inner_limits=(0.0, 0.0), outer_limits=None, instrumental_limit=1e+50)[source]

Build a robust mask and uncertainty channel for a batch of spectra.

Rules: - Mask pixels inside inner_limits (to exclude e.g. strong tellurics). - If outer_limits is provided, mask pixels outside it. - Mask NaN wavelengths / infinite errors / non‑positive flux. - Convert any NaNs in the error channel to a very large uncertainty (1e31).

Parameters:

  • sheap_array (jax.numpy.ndarray) – Array with shape (n_obj, C, N), channels: [λ, flux, err, (opt …)].

  • inner_limits (Tuple[float, float]) – (xmin, xmax) wavelengths to mask out inside this window.

  • outer_limits (Tuple[float, float] | None) – If given, wavelengths outside (xmin, xmax) are masked.

  • instrumental_limit (float) – Unused placeholder (kept to avoid breaking callers).

Returns:

  • array (jnp.ndarray) – Copy of input with the error channel replaced by prepared uncertainties.

  • prepared_uncertainties (jnp.ndarray) – The prepared error channel (same shape as input error channel).

  • original_array (jnp.ndarray) – Reference to the original sheap_array.

  • mask (jnp.ndarray) – Boolean mask (True = masked / ignored).

pad_error_channel(spectra, frac=0.01)[source]

Ensure a third channel (error) by padding with a fraction of the signal.

Parameters:

  • spectra (ndarray | jax.numpy.ndarray) – Array with shape (n_obj, C, N) or (C, N). If C==2 (λ, flux), the error channel is appended as frac * flux.

  • frac (float) – Error fraction applied to the flux to fabricate uncertainties.

Returns:

Spectra with shape (…, 3, N).

Return type:

ArrayLike

prepare_spectra(spectra_list, outer_limits)[source]

Cut each spectrum to outer_limits, pad to common length, and build masks.

Parameters:

  • spectra_list (Sequence[ndarray]) – Iterable of per‑object arrays with shape (C, N).

  • outer_limits (Tuple[float, float]) – (xmin, xmax) hard window to keep.

Returns:

  • spectral_region (jnp.ndarray) – Batched spectra of shape (n_obj, C, N_max) after cutting/padding.

  • mask_region (jnp.ndarray) – Boolean mask with True where samples are masked (ignored in fit).

prepare_uncertainties(y_uncertainties, y_data)[source]

Prepare an uncertainty channel consistent with masking rules.

  • If y_uncertainties is None, returns an array of ones.

  • Any NaNs in the uncertainties or the data are set to a very large value (1e31),

    so inverse‑variance weighting effectively ignores those pixels.

Parameters:

  • y_uncertainties (jax.numpy.ndarray | None) – Error channel or None.

  • y_data (jax.numpy.ndarray) – Flux channel (used only to propagate NaN locations).

Returns:

Prepared uncertainties (same shape as y_data).

Return type:

jnp.ndarray

resize_and_fill_with_nans(original_array, new_xaxis_length, number_columns=None)[source]

Resize a (C, N) spectral array to (C_out, new_xaxis_length), padding with NaNs.

Parameters:

  • original_array (ndarray) – Input array with shape (C, N).

  • new_xaxis_length (int) – Target number of pixels along the wavelength axis.

  • number_columns (int | None) – Target number of channels C_out. If None, uses original C.

Returns:

New array of shape (C_out, new_xaxis_length) with the original data copied into the upper-left corner and NaNs elsewhere.

Return type:

np.ndarray

ensure_sfd_data(sfd_path=None)[source]

Ensure the Schlegel, Finkbeiner & Davis (1998) dust maps are available locally. Downloads the 4 required FITS files into sfd_path if missing.

Parameters:

  • sfd_path (Path, optional) – Directory where the SFD data should be stored. Defaults to SuportData/sfddata relative to this file.

  • Files

  • ----- –

    • SFD_dust_4096_ngp.fits

    • SFD_dust_4096_sgp.fits

    • SFD_mask_4096_ngp.fits

    • SFD_mask_4096_sgp.fits