Quickstart¶

This page is the API in reference form. For the same ground covered as a worked example — with plots, real numbers and the reasoning behind them — see the getting-started notebook.

Super-resolve a spectrum¶

import numpy as np
from specsr_roman import RomanPipeline
from specsr_roman.grids import WAVE_LR, ROMAN_MEDIUM_BANDS

pipe = RomanPipeline.from_pretrained()      # downloads ~11 MB on first use

out = pipe.predict(
    flux_low,          # (864,) on WAVE_LR, the native grism sampling
    flux_low_err,      # same shape; the model reads the flux/err ratio as S/N
    phot=phot[list(ROMAN_MEDIUM_BANDS)],    # F106, F129, F158 — in that order
)

The result carries more than a spectrum:

Attribute	Meaning
`flux_sr`, `flux_sr_err`	super-resolved flux and per-pixel uncertainty, 2500 px
`flux_sr1`	the SR1 stage alone, for comparison
`z`, `z_err`	redshift mode and the spread of the full PDF
`pz`, `z_grid`	the whole P(z)
`presence`	per-line presence probability over 98 features
`wavelength`	observed wavelength grid, Å

Values come back on the input’s own flux scale, so they plot directly against it.

Keep the redshift PDF¶

z is the mode of pz, not its mean. Redshift from a grism is a line identification problem: one observed line is consistent with Hα, [O III], [O II] or Lyα. For an ambiguous source the second mode is real information, and z_err widens precisely when the model is torn between identifications.

top = np.argsort(out.pz)[::-1][:3]
for i in top:
    print(f"z = {out.z_grid[i]:.3f}  p = {out.pz[i]:.3f}")

If a source’s second mode carries meaningful mass, treat the point estimate with suspicion — that is what the PDF is telling you.

Running without photometry¶

out = pipe.predict(flux_low, flux_low_err, phot=None)

This works, and it is much weaker. On the held-out split it gives NMAD 0.014 with 26 % catastrophic outliers, against 0.0065 and 5.1 % with Roman Medium-tier imaging: a single in-band line is alias-degenerate, and the colours are what break most of that.

Be precise about what the number measures, though. The published head was trained with photometry, so phot=None hands it its training-mean colours rather than removing the information — mean imputation on an out-of-distribution input. Read it as “the colour prior carries most of the redshift accuracy”, not as the grism-only information floor, which would need a head trained without colours to measure.

Batches¶

Pass 2D arrays and get a list back:

outs = pipe.predict(flux_low_batch, err_batch, phot=phot_batch)

From the command line¶

specsr-roman predict spectra.npz --out predictions.npz --phot-tier medium

where spectra.npz holds flux_low and optionally flux_low_err, phot and wavelength_low.