specsr — spectral super-resolution for JWST/NIRSpec galaxy spectra

Weights for the pipeline described in:

Haghjoo, A., Hemmati, S., Mobasher, B., et al. Learning to See Sharper: A Physics-Informed Artificial Intelligence Framework for Super-Resolving Galaxy Spectra. ApJ, under revision (AAS75211). arXiv:2603.18357

main serves the current chain (v3, 2026-07-31). Two earlier revisions are kept as archival tags for reproducibility and must not be used for science — see Revisions.

from specsr.inference.pipeline import SpecSRPipeline

pipe = SpecSRPipeline.from_pretrained()      # downloads ~18 MB
result = pipe(flux_low)                      # on the package's log constant-R grid
result.sr2, result.z, result.z_sigma

What the pipeline does

Three stages, trained in order, each freezing the previous one:

Stage	Role
SR1	1D ResNet-CNN backbone: prism (R100) → grating-like (R1000) reconstruction
ZHead	Redshift inference from SR1 output; softmax PDF over ~1000 bins
SR2	Physics-informed residual refiner: attention over 98 emission-line tokens, each a parametric Gaussian gated by a supervised presence probability, plus a CNN continuum branch

Honest performance summary

All numbers on 572 held-out galaxies, split by parent galaxy so no augmented sibling crosses the split. JADES DR4, log constant-R grid (R_grid = 4000).

Emission-line flux (SR2 vs HR reference)

The SR/HR flux ratio is a strong function of line SNR — a single number is misleading. Median ratio by HR SNR cut: 0.04 / 0.19 / 0.43 / 0.62 at 5 / 10 / 20 / 50. Below SNR ~20 the HR line flux is itself mostly noise.

HR SNR cut	median SR/HR	16-84 scatter	within 20%	within 50%
>= 20	0.618	[+0.09, +1.04]	26.8%	54.4%
>= 50	0.700	[+0.07, +1.04]	35.1%	62.3%

Read the scatter, not just the median: only ~35% of even the brightest lines land within 20% of the true flux. Usable in aggregate for bright lines; not yet reliable line by line. Blended systems (Halpha+[N II], the [S II] doublet) carry larger uncertainty than isolated lines — 11 of the 98 catalogued lines have no line-free continuum window within +/-1500 km/s.

Redshift — and a limitation to be aware of

One head architecture, one split, one seed; only the input representation differs. Outliers are |dz|/(1+z) > 0.15.

head input	outliers	med |dz|/(1+z)	sigma_NMAD
Low-res prism (raw input)	6.12%	0.00151	0.00223
SR1 output	10.84%	0.00177	0.00269
High-res grating (reference)	11.01%	0.00083	0.00125
SR2 output	training in progress	—	—

Super-resolution does not currently improve redshift recovery over the raw prism input. We state this plainly because the repository's own numbers say so.

The pattern is interpretable rather than mysterious: the prism and the grating trade SNR against resolution at fixed exposure — the prism has 4.4x higher median per-pixel SNR (4.13 vs 0.94), the grating ~4x the resolving power. Precision follows resolution (the grating is 2x better on median |dz|/(1+z)); catastrophic outliers follow SNR (the prism is ~2x better). Super-resolution's goal is to obtain both, and on this measurement it does not yet.

Use the prism-trained redshift head, not the SR1 head, if redshift is what you need. Both are in this repo.

Contents

Path	Stage
sr1/best_sr1.pth	SR1 backbone (selected)
sr1/config_logR.yaml	SR1 architecture config — required to rebuild SR1
zhead/best_zhead.pth	ZHead on SR1 output (softmax PDF head)
sr2/best_sr2.pth	SR2 residual refiner
zhead/best_zhead_lowres.pth	ZHead on raw prism input — comparison arm
zhead/best_zhead_hires.pth	ZHead on true grating spectra — comparison arm

zhead/best_zhead_sr2.pth is not yet present on this revision; that arm is still training. get_checkpoint("zhead_sr2") will 404 until it lands.

Known limitations

• Redshift: see above. SR1 does not beat the raw prism input.
• Line flux: large per-line scatter (see above). The improvement over previous revisions is in the median bias; the dispersion is essentially unchanged.
• SR2's flux term overfits the augmented training rows. Training-set flux ratio reaches 0.946 while the held-out figure stays at 0.49-0.63. The product augments every training galaxy ~21x. Restricting flux supervision to original rows is a known, not-yet-applied fix.
• ZHead sigma_z is optimistically narrow. The head's point estimate improves while its validation NLL rises, so treat z_sigma as a lower bound.

Revisions

Revision	Status
main (v3, 2026-07-31)	current — use this
v2-presencefix-20260726	archival. Trained with unnormalised HR errors, and its presence gate is functionally collapsed (see below). Not for science.
v1-submission	archival. Reproduces the originally submitted manuscript. Trained on a leaky split: 99.2% of galaxies had rows on both sides. Not for science.

The archival tags exist so the published manuscript's numbers remain reproducible while the paper is under review. Neither is reachable by default — DEFAULT_REVISION = "main".

What changed in v3

• The presence gate is supervised, not penalised. In earlier revisions a blanket sparsity penalty drove it to a constant ~0.002 — identical on real and absent lines, a discrimination ratio of 0.95, i.e. carrying no information. Since the model forms amp * presence, that constant multiplied every line amplitude and the line branch contributed 0.17% of the required flux; every apparent line gain was coming from the generic CNN branch. Presence is now trained by class-balanced BCE against the lines the reference actually shows. Discrimination 16.1x -> 841x.
• An explicit integrated-line-flux term, measured against a line-free continuum so blended systems are not silently mis-measured.
• Retrained on JADES DR4 with a log constant-R grid (the previous linspace grid downsampled the HR targets 2.5x below 3.2 um) and a group-wise 80/20 split.

License

MIT, matching the source repository.