specsrbench.sample

The small tutorial dataset: 24 held-out spectra, fetched from the Hub.

The benchmark proper reads a 267 MB cache that this package does not ship and most readers will never rebuild – it needs the raw JADES DR4 tree, the Hub weights and a few CPU-hours. That is a poor first experience for someone who has just run pip install specsrbench and wants to see what the thing does.

This module is the other end of that scale. One 1.9 MB archive, downloaded on first use and cached by huggingface_hub thereafter, carrying everything the benchmark needs on a small subset: the prism input, the grating reference, the measured line-spread function, the SR2 prediction, and the tuned classical parameters. Every classical baseline runs on it in seconds with no torch, no survey data and no configuration.

What the numbers off it mean

24 galaxies, not 572. The ordering of the methods reproduces and so does the lesson – SR2 leads raw MAE by ~30% at 0.58 of the reference amplitude, and ranks last once that is corrected for – but the individual figures carry the error bar of a 24-spectrum sample and are not the paper’s. Quote the paper for the paper’s numbers.

The galaxies are the evaluation set sorted by redshift and sampled at evenly spaced ranks, so they are held out by construction and span z = 0.31 to 13.86 rather than being chosen for how good they look. tests/test_tutorial_sample.py checks that against the split.

Warning

sigma_pix here is the derived kernel, the one specsrbench.classical.load_sigma_pix() returns. The evaluation set ships a different array under that name which does not describe the data – roughly constant in nanometres where a real spectrograph is fixed in detector pixels, and up to 2.3x too broad at 5 um. Deconvolving with it merges line pairs the input still resolves. Nothing in this archive carries that array.

Module Attributes

DEFAULT_REPO	Hub dataset repo holding the archive.
DEFAULT_REVISION	Branch, tag or commit.
FILENAME	The one file in it.

Functions

load_sample([path, repo_id, revision])	The tutorial sample, downloading it from the Hub on first use.
sample_path([repo_id, revision])	Local path to the archive, downloading it if necessary.

Classes

Sample(path)

24 held-out spectra and everything needed to benchmark against them.

class specsrbench.sample.Sample(path)

Bases: object

24 held-out spectra and everything needed to benchmark against them.

Attributes mirror specsrbench.data.Cache where they mean the same thing, so code written against one mostly reads on the other.

Parameters:

path (Path | str)

property wave: ndarray

The log constant-R grid, in microns (6,671 points, R = 4000).

property sigma_pix: ndarray

The measured LSF width, in detector pixels, per grid point.

property z: ndarray

Spectroscopic redshift, ascending.

property z_pred: ndarray

The redshift head’s estimate, which SR2 was conditioned on.

property mf_lines: ndarray

Rest wavelengths the matched filter places templates at, in microns.

Carried here so the matched filter runs without specsr, which owns the line list and pulls in torch.

property x_low: ndarray

The prism input, cubic-interpolated onto the high-resolution grid.

This is both the input every deconvolver takes and the no-deconvolution baseline every one of them has to beat.

property x_high: ndarray

The grating reference every method is scored against.

property x_high_err: ndarray

Reference flux uncertainty, normalised like x_high; NaN where invalid.

property sr2: ndarray

The SR2 deep-learning prediction, precomputed (no torch needed).

property valid: ndarray

Pixels where the grating reference is real, not padding.

property params: dict

The tuned classical parameters, as classical_params.json records them.

property tuned: dict

Just the per-method parameter blocks, keyed as reconstruct() expects.

property provenance: dict

Where these spectra came from, and what produced the arrays beside them.

property n_spectra: int

property n_pixels: int

summary()

Return type:

str

line_positions(i)

(key, label, observed wavelength) for lines inside the grid.

Parameters:

i (int)

Return type:

list[tuple[str, str, float]]

reconstruct(methods=None)

Run the classical baselines at the tuned parameters.

Returns {display name: array} including the two reconstructions that need no work – "Cubic (LR)", the prism input, and "ML (SR2)", the precomputed prediction – so the result is the full comparison table rather than only the part that had to be computed.

Takes a few seconds for all six on 24 spectra.

Return type:

dict[str, ndarray]

specsrbench.sample.load_sample(path=None, *, repo_id=None, revision=None)

The tutorial sample, downloading it from the Hub on first use.

Parameters:

• path (Path | str | None) – A local .npz to read instead of fetching anything.

• repo_id (str | None) – Override the Hub dataset repo and the revision taken from it.

• revision (str | None) – Override the Hub dataset repo and the revision taken from it.

Return type:

Sample

specsrbench.sample.sample_path(repo_id=None, revision=None)

Local path to the archive, downloading it if necessary.

SPECSRBENCH_SAMPLE points at a local .npz and wins outright: no network, no Hub account, and the way to work against a rebuilt sample before it is published.

Parameters:

• repo_id (str | None)

• revision (str | None)

Return type:

Path

specsrbench.sample.DEFAULT_REPO = 'aryana-haghjoo/specsr-benchmark'

Hub dataset repo holding the archive. Override with SPECSRBENCH_SAMPLE_REPO.

specsrbench.sample.FILENAME = 'specsrbench_sample.npz'

The one file in it.