RomanXYZ

Mapping the three-dimensional Universe with Roman grism spectroscopy

A community-developed toolkit for Nancy Grace Roman Space Telescope WFI grism data: from count-rate images to calibrated spectra, redshifts, emission-line maps and kinematic stamps for every source in the field. An open-source release is coming soon.

Background: a simulated Roman G150 grism exposure. Every streak is the spectrum of one galaxy or star. (Simulation: Wang et al. 2022)

Learn more

What is RomanXYZ?

The Roman Wide Field Instrument carries a slitless G150 grism covering 1.00–1.93 μm at a wavelength-dependent resolving power of R = 461 λ/μm (about 460–890 across the band). Every exposure records the spectrum of every source on 18 detectors at once, with no target pre-selection. This spectroscopy is a core component of the High-Latitude Wide-Area Survey, which will measure redshifts from Hα (z = 0.5–1.9), [O III] (z = 1.0–2.9) and [O II] (z = 1.7–4.2) over thousands of square degrees.

RomanXYZ reduces these data. It starts from count-rate (L2) images and produces source catalogs, flux-calibrated 2-D and 1-D spectra with exact error and covariance propagation, contamination models, emission-line redshifts, emission-line maps, and per-exposure kinematic stamps for rotation-curve and kinematic-lensing studies. The step sequence, products and command-line interface follow the JWST/NIRCam slitless reduction I wrote for the SAPPHIRES survey, adapted to Roman. Traces and sensitivities come from the roman_disperser optical model.

From rate images to science

One command, romanxyz reduce, runs the full chain. Every step writes a status table and can be re-run on its own.

One Roman detector through RomanXYZ: direct image, catalog, grism image, traces, contamination model, 2-D spectra, and a 1-D spectrum with H-beta, [OIII] and H-alpha at z = 1.497

One detector (SCA 9) of the Wang et al. (2022) simulation through the pipeline: 8,025 sources → 5,924 spectra → 2,735 with an emission line at S/N ≥ 5. The galaxy shown has Hβ, [O III] and Hα at z = 1.497.

The steps

  1. Imaging: sky subtraction, artifact and 1/f removal, astrometry, source catalog from the direct images
  2. Traces: trace and sensitivity model for every source, with self-calibration of the trace zero point
  3. Contamination: every neighbour dispersed from its own direct-image cutout, bright neighbours refined
  4. Extraction: 2-D spectra per exposure, per roll angle and combined; boxcar and optimal 1-D spectra
  5. Science: line search, template redshifts with an optional photo-z prior, line maps and kinematic stamps

Spectra at three levels

2-D spectra for every exposure, every roll angle and the combined coadd, with weights, covariances, contamination and continuum-subtracted planes. Each exposure carries its sky orientation and trace Jacobian.

Honest uncertainties

Exact noise and covariance propagation from pixels to 1-D spectra, a contamination model with its own uncertainty, and per-exposure wavelength uncertainties from the trace zero point and source position.

Redshifts and beyond

Emission-line redshifts with probabilities, an EAZY photo-z prior from Roman imaging, emission-line maps on the sky, and kinematic stamps that drop into any kinematics code.

Kinematic stamps of a simulated rotating disk in four exposures at two roll angles: data, model and residual

Kinematic stamps

For every emission line in every exposure, RomanXYZ writes a native-pixel cutout with its variance, contamination and continuum models, the PSF at the line and the full sky-to-pixel map, including the trace distortion. A simulated sheared rotating disk is fit directly in detector pixels in four exposures at two roll angles, leaving noise-like residuals.

H-alpha emission-line maps of eight simulated disk galaxies reconstructed on the sky

Emission-line maps

Each exposure's line stamp is mapped back to the sky with its own geometry, and the exposures from both rolls are combined. The result is a resolved Hα image of every emitter, for sizes and morphologies. Simulated disks recover 0.88–0.96 of the true flux within 2″.

Validated on simulations

Injection tests with exact truth, full-field roman_disperser pointings at two roll angles, the Wang et al. (2022) simulations, and a sheared rotating-disk set for kinematic lensing.

RomanXYZ simulation validation results
1.00 Noise arrays: (noisy − noiseless) / error has unit scatter for 2-D pixels (1.000) and 1-D spectra (1.01–1.02)
0.007 px Per-exposure wavelength zero point (+0.07 Å), with no trend with sub-pixel source position
94% Continuum flux recovered by optimal extraction for both point sources and disks (the rest is PSF light beyond 1.1″)
97% Redshift purity for clean, high-probability sources, from only 2 × 301 s exposures, using line templates and a photo-z prior

Get started

RomanXYZ is written in Python and installs with pixi. The quick-start example simulates one detector at two roll angles and runs the whole chain in about a minute. An open-source release is coming soon. 

pixi install && pixi run hydrate && pixi run test
pixi run hydrate-sim --sca 9
pixi run python examples/quickstart/run_quickstart.py

# a larger test: six dithered exposures with injected lines
pixi run python scripts/validation/make_injection_sim.py ../test_data/inject
pixi run romanxyz reduce --config configs/inject.yaml --n-workers 8

Status: early development (v0.1), tested on simulations. Interfaces and product formats may still change. The open-source release will use the MIT License; contributions and feedback from the Roman community are welcome.

GitHub: open release soon Contact me to join as an early user