Migrate from the 2022 package

The 11 functions that lived at the top level of the 2022 gspice package, such as gspice.covar_iter_mask and gspice.gp_interp, now live in gspice.legacy, which preserves their signatures and arithmetic. Legacy interface documents them, and the table below maps each 2022 function to its 2.0 replacement.

From scaled units to flux

The largest change is the units. The 2022 functions took and returned the scaled spectra of standard_scale. A scaled spectrum is the flux times $a_s$, the square root of the mean ivar of the good pixels, minus the mean spectrum. The new prediction functions take flux and return flux, with variances in flux². The model in between, a gspice.Model, still holds its mean and covariance in scaled units. Working units explains the scaling.

This example fits both ways and predicts every pixel. With cumulative=False, fit uses the 2022 rule for the masks of its clipping passes. The two models then agree under the conditions in the docstring of gspice.fit(). The main ones are the default nguard, no center, weights, rank, snr_bins or noise, and float64 flux:

Python

import warnings

import numpy as np

import gspice

rng = np.random.default_rng(7)
sim = gspice.simulate(1000, 100, rng=rng, artifacts=0.3)
mask = np.zeros(sim.flux.shape, dtype=bool)

# 2022: scaled spectra in, scaled predictions out.
cov, finalmask = gspice.legacy.covar_iter_mask(sim.flux, sim.ivar, mask)
X, refscale, refmean = gspice.legacy.standard_scale(sim.flux, sim.ivar, finalmask)
pred, predvar = gspice.legacy.gp_interp(X, cov)

# New: flux in, flux out.
model, newmask = gspice.fit(sim.flux, sim.ivar, mask, cumulative=False)
result = gspice.pixelwise(model, sim.flux, sim.ivar, newmask)

a = refscale[:, None]
print(np.array_equal(newmask, finalmask != 0))
print(np.allclose(result.flux, (pred + refmean) / a, rtol=1e-7, atol=0))
print(np.allclose(result.var, predvar / a**2, rtol=1e-7, atol=0))

Text

True
True
True

The 2022 predictions return to flux as $(\mathrm{pred} + \mathrm{refmean}) / a_s$, and their variances as $\mathrm{predvar} / a_s^2$. gspice.unscale() does this for any scaled values. The 2022 functions work from explicit inverses of the covariance, so their variances differ from the new ones by a relative error of up to 8e-9 on one machine. The comparison allows 1e-7. The default cumulative=True keeps the flags of every pass, as the paper does, so its mask and model differ from the 2022 ones.

Function by function

Each row gives the outputs and their units as 2022 → new.

2022 function	New function	Outputs	Units
standard_scale	scale	Dvec, refscale, refmean → X, refscale, refmean	scaled, flux⁻¹, scaled, in both
covar	fit with nsigma=()	cov, refmean → Model, mask	units of the input → scaled
covar_iter_mask	fit	cov, float mask → Model, bool mask	scaled, in both
get_chimask	fit, then pixelwise	bool mask → z; flag abs(z) >= nsigma, and each flag also covers its two neighbors	unit-free
gp_interp	pixelwise	pred, predvar of irange → Prediction: flux, var, z of every pixel	scaled → flux, flux²
gaussian_estimate	infill	predoverD, predcovar, predkstar, kstar → Repaired: flux, var, chi2 and, with covariance=True, covariance(s)	scaled → flux, flux²
cholesky_inv, submatrix_inv, submatrix_inv_mult, maskinterp1, maskinterp	none: keep gspice.legacy.<name>	unchanged	unchanged

The new functions have no 2022 equivalent for the block scan and the search for artifacts: Find and repair artifacts shows gspice.repair().

When the old names go

Version	What changes
2.0.0, 2026-10-29	The 11 functions move to gspice.legacy. gspice.<name> still works, with a DeprecationWarning. The 2022 modules move, and their old paths fail.
3.0.0	gspice.<name> is removed. gspice.legacy stays.

The warning names the replacement. The example catches it to print it:

Python

with warnings.catch_warnings(record=True) as caught:
    warnings.simplefilter("always")
    covar_iter_mask = gspice.covar_iter_mask
print(caught[0].message)
print(covar_iter_mask is gspice.legacy.covar_iter_mask)

Text

gspice.covar_iter_mask is deprecated and will be removed in 3.0.0. Use gspice.fit, or gspice.legacy.covar_iter_mask to keep the 2022 results.
True

To keep the 2022 results without the warning, import from gspice.legacy, for example from gspice.legacy import covar_iter_mask. For a 2022 module, insert legacy. into its path, as in from gspice.legacy.specUtils import gp_interp.

gspice.legacy also fixes crashes and wrong results of the 2022 code on some inputs. The changelog lists these behavior changes under 2.0.0.