Nancy Grace Roman Space Telescope Calibration Pipeline

This package (romancal) processes uncalibrated data from the Nancy Grace Roman Space Telescope (Roman). The pipeline performs a series of calibration steps that result in standard data products usable for science.

Detailed explanations of specific calibration stages, reference files, and pipeline builds can be found on the ReadTheDocs pages and RDox.

Note

If you have trouble installing this package, have encountered a bug while running the pipeline, or wish to request a new feature, please open an issue on GitHub or contact the Roman Telescope Help Desk.

• Quick Start
  • 1. Install the Pipeline
    • Option: Build Pipeline Directly from Source Code
    • Option: Install Exact Operational Environment
  • 2. Set up the Calibration Reference Data System (CRDS)
  • 3. Run the Pipeline
• Code Contributions
• DMS Operational Build Versions

Quick Start

1. Install the Pipeline

Important

The Roman Telescope calibration pipeline currently supports Linux and macOS. Native Windows builds are not currently supported; use WSL instead.

We recommend using an isolated Python environment to install romancal. Python "environments" are isolated Python installations, confined to a single directory, where you can install packages, dependencies, and tools without cluttering your system Python libraries. You can manage environments with mamba / conda, virtualenv, uv, etc.

These instructions assume you are creating Conda environments with the mamba command (see Miniforge for installation instructions); to use conda instead, simply replace mamba with conda in the following commands.

First, create an empty environment with Python installed:

mamba create -n romancal_env python=3.13

Then, activate that environment (necessary to be able to access this isolated Python installation):

mamba activate romancal_env

Finally, install romancal into the environment:

pip install romancal

Without a specified version, pip defaults to the latest released version that supports your environment. To install a specific version of romancal, explicitly set that version in your pip install command:

pip install romancal==0.22.0

To install a different version of romancal, simply create a new environment for that version:

mamba create -n romancal0.22_env python=3.13
mamba activate romancal0.22_env
pip install romancal==0.22

mamba create -n romancal0.20_env python=3.12
mamba activate romancal0.20_env
pip install romancal==0.20

Option: Build Pipeline Directly from Source Code

To install the latest unreleased (and unstable) development version directly from the source code on GitHub:

pip install git+https://github.com/spacetelescope/romancal

Option: Install Exact Operational Environment

There may be occasions where you need to replicate the exact environment used for canonical calibration operations by STScI (e.g. for validation testing or debugging issues). We package releases for operations as environment snapshots that specify exact versions for both the pipeline and all dependencies.

See the DMS Operational Build Versions table for the version of the pipeline corresponding to each operational build. For example, use romancal==0.22.0 for DMS build 26Q2_B21. Also note that Linux and macOS systems require different snapshot files:

mamba env create --file https://ssb.stsci.edu/stasis/releases/romancal/ROMANDP-0.20.0/delivery/latest-py312-macos-arm64.yml
mamba activate ROMANDP-0.20.0-1-py312-macos-arm64

2. Set up the Calibration Reference Data System (CRDS)

Before running the pipeline, you must first set up your local machine to retrieve files from the Calibration Reference Data System (CRDS) CRDS provides calibration reference files for several telescopes, including Roman.

Set CRDS_SERVER_URL and CRDS_PATH to run the pipeline with access to reference files from CRDS:

export CRDS_SERVER_URL=https://roman-crds.stsci.edu
export CRDS_PATH=$HOME/data/crds_cache/

The pipeline will automatically download individual reference files and cache them in the CRDS_PATH directory. Expect to use 50 gigabytes (or more) of disk space for reference files, depending on the instrument modes in use.

Tip

Users within the STScI network do not need to set CRDS_PATH (it defaults to shared network storage).

To use a specific CRDS context other than that automatically associated with a given pipeline version, explicitly set the CRDS_CONTEXT environment variable:

export CRDS_CONTEXT=roman_0046.pmap

3. Run the Pipeline

Once installed, the pipeline allows users to run and configure calibration themselves for custom processing of Roman Telescope data, either from the command line with strun or from Python with pipeline and step functions and classes in the romancal package. Additionally, the romancal package provides Roman Telescope datamodel classes, the recommended method for reading and writing Roman Telescope data files in Python.

Code Contributions

romancal is an open source package written in Python. The source code is available on GitHub. New contributions and contributors are very welcome! Please read CONTRIBUTING.md.

We strive to provide a welcoming community by abiding with our CODE_OF_CONDUCT.md.

See TESTING.md for instructions on automated testing.

DMS Operational Build Versions

The table below provides information on each release of the romancal package and its relationship to software builds used in STScI Roman Telescope DMS operations. Each romancal tag was released on PyPI on the date given in Date.

romancal tag	DMS build	CRDS_CONTEXT	Date	Notes
1.0.0	26Q3_B22	051	May 2026	Release for Build 26Q3_B22 (Build 22)
0.22.0	26Q2_B21	046	Feb 2026	Release for Build 26Q2_B21 (Build 21)
0.21.0	26Q1_B20	090	Nov 2025	Release for Build 26Q1_B20 (Build 20)
0.20.1	25Q4_B19	088	Aug 2025	Release for Build 25Q4_B19 (Build 19)
0.20.0	25Q4_B19	088	Aug 2025	Release for Build 25Q4_B19 (Build 19)
0.19.0	25Q3_B18	083	May 2025	Release for Build 25Q3_B18 (Build 18)
0.18.0	25Q2_B17	072	Feb 2025	Release for Build 25Q2_B17 (Build 17)
0.17.0	25Q1_B16	065	Nov 2024	Release for Build 25Q1_B16 (Build 16)
0.16.3	24Q4_B15	063	Aug 2024	Release for Build 24Q3_B15 (Build 15)
0.16.2	24Q4_B15	063	Aug 2024	Release for Build 24Q3_B15 (Build 15)
0.16.1	24Q4_B15	063	Aug 2024	Release for Build 24Q3_B15 (Build 15)
0.16.0	24Q4_B15	063	Aug 2024	Release for Build 24Q3_B15 (Build 15)
0.15.1	24Q3_B14	058	May 2024	Release for Build 24Q3_B14 (Build 14)
0.15.0	24Q3_B14	058	May 2024	Release for Build 24Q3_B14 (Build 14)
0.14.0	24Q2_B13	056	Feb 2024	Release for Build 24Q2_B13 (Build 13)
0.13.0	24Q1_B12	052	Nov 2023	Release for Build 24Q1_B12 (Build 12)
0.12.0	23Q4_B11	051	Aug 2023	Release for Build 23Q4_B11 (Build 11)
0.11.0	23Q3_B10	047	May 2023	Release for Build 23Q3_B10 (Build 10)
0.10.0	23Q2_B9	041	Feb 2023	Release for Build 23Q2_B9 (Build 9)
0.9.0	23Q1_B8	039	Nov 2022	Release for Build 23Q1_B8 (Build 8)
0.8.1	22Q4_B7	038	Aug 2022	Release for Build 22Q4_B7 (Build 0.7)
0.8.0	22Q4_B7	038	Aug 2022	Release for Build 22Q4_B7 (Build 0.7)
0.7.1	22Q3_B6	032	May 2022	Release for Build 22Q3_B6 (Build 0.6)
0.7.0	22Q3_B6	032	May 2022	Release for Build 22Q3_B6 (Build 0.6)
0.6.0	0.5	030	Mar 2022	Release for Build 0.5
0.5.0	0.4	023	Dec 2021	Release for Build 0.4
0.4.2	0.3	011	Sep 2021	Release for Build 0.3
0.3.1	0.2	007	Jun 2021	Release for Build 0.2 CRDS tests
0.3.0	0.2	007	May 2021	Release for Build 0.2
0.2.0	0.1	004	Mar 2021	Release for Build 0.1
0.1.0	0.0	003	Nov 2020	Release for Build 0.0