TRAP – Temporal Reference Analysis for Planets

TRAP is a novel algorithm for the detection of exoplanets in high-contrast direct imaging data. Unlike traditional image-based approaches, TRAP models and removes stellar contamination using causal temporal regression, offering improved sensitivity to exoplanet signals at small angular separations from the host star.

📄 For a detailed methodology and scientific background, see:
Samland et al. 2021, A&A, 646, A24

Key Features

• Temporal Systematics Modeling: Models time-dependent stellar residuals using causal regression for improved contrast at small inner working angles.
• Automatic Detection and Characterization: Automatically detect point sources, measure their astrometry per wavelength channel, and extract their spectra.
• Spectral Template Matching: Works with external spectral templates (using species) for improved detection.
• Integral-Field and Dual-Band Data: Ready-made configurations for IFS and IRDIS-style data, with experimental, opt-in enrichment of the temporal regressor pool using other wavelength slices.
• Edge-of-Field Reduction: An optional detector footprint mask lets the search run out to the edge of irregularly shaped fields of view instead of stopping at a fixed radius.
• Dataclass Configuration: Reductions are configured with frozen, introspectable dataclasses (TrapConfig / TrapReductionConfig) — no hidden global state.
• Parallel Processing: Efficient parallelism via joblib/loky with a memmap-backed shared-array store, scalable from laptops to clusters.
• Automated Visualization: Generates diagnostic plots, spectra, and contrast curves for each reduction pipeline run.

Installation

TRAP requires Python 3.11, 3.12, or 3.13. It is published on PyPI as trap-hci and imported as trap:

pip install trap-hci

The name trap on PyPI belongs to an unrelated package (ASTRON's Transients Pipeline), which also installs a module called trap, so the two cannot be installed in the same environment.

To install the latest development version, the develop branch, instead:

pip install git+https://github.com/m-samland/trap@develop

ℹ️ TRAP parallelizes with joblib/loky and a memmap-backed shared-array store, so there is no cluster runtime to install separately. Large input arrays are written once to a scratch directory (/dev/shm when available, otherwise the system temp directory) and memory-mapped read-only by the worker processes; set TrapReductionConfig.scratch_dir if your machine needs a different location. To scale beyond one node, submit scheduler job arrays over wavelengths or epochs.

Quick Start

A Jupyter notebook and example dataset based on VLT/SPHERE observations are provided. They demonstrate the full workflow: loading data, performing temporal regression, generating detection maps, and extracting companion spectra.

Reductions are configured with dataclasses rather than a CLI:

from trap.parameters import trap_config_for_ifs

config = trap_config_for_ifs()
reduction_config = config.reduction.merge(result_folder="./results")

TrapReductionConfig is frozen — derive variants with merge(**kwargs) instead of assigning to attributes.

🔗 Related Project: spherical

Looking for a full data reduction pipeline for VLT/SPHERE-IFS data?

Check out spherical — a companion package to TRAP that provides an end-to-end workflow from data discovery and calibration to post-processing.

• 🔍 Automates retrieval of SPHERE-IFS raw and calibration data from the ESO archive
• ⚙️ Uses a Python-based, open-source pipeline based on the CHARIS data reduction pipeline
  (Samland et al. 2022) — a high-performance alternative to the official SPHERE-DRH
• 📊 Seamlessly integrates with TRAP for temporal analysis and exoplanet detection
• 🌈 Automatically applies TRAP’s template matching to collapse detection maps using spectral models (e.g., L- and T-type planets)

TRAP is fully supported as the post-processing backend in spherical, making it easy to go from raw SPHERE data to scientifically validated planet detections.

👉 Learn more at: https://github.com/m-samland/spherical

Contributing

We warmly welcome contributions to TRAP! Here's how to get started:

Setup for Developers

Development happens on the develop branch; main holds the releases. Clone the repository and install it locally for development with tests:

git clone https://github.com/m-samland/trap.git
cd trap
git switch develop
pip install -e ".[test]"

Alternatively, a pixi environment is provided:

pixi install -e dev
pixi shell -e dev

Contributing Guidelines

• Please use feature branches or forks for developing new features or bug fixes, branched from develop, and open Pull Requests against develop.
• Issue and Pull Request templates are provided—please use them.
• Always run the code linting tool (ruff) before submitting a Pull Request:

ruff check .

• pytest runs the fast test suite. pytest -m e2e (or pixi run -e dev test-e2e) also runs the end-to-end reduction of 51 Eri b on the SPHERE-IRDIS data in examples/test_data, which takes a few minutes; CI runs both on every pull request.

If you’re unsure where to start, check out the good first issues or open a discussion.

📖 Citing TRAP

If you use TRAP in your research, please cite:

Matthias Samland et al. (2021) – A temporal systematics model for improved direct detection of exoplanets at small angular separations
A&A, Vol. 646, A24
DOI: 10.1051/0004-6361/201937308

@ARTICLE{2021A&A...646A..24S,
  author       = {{Samland}, M. and {Bouwman}, J. and {Hogg}, D.~W. and {Brandner}, W. and {Henning}, T. and {Janson}, M.},
  title        = "{TRAP: a temporal systematics model for improved direct detection of exoplanets at small angular separations}",
  journal      = {\aap},
  year         = 2021,
  month        = feb,
  volume       = {646},
  pages        = {A24},
  doi          = {10.1051/0004-6361/201937308},
  archivePrefix = {arXiv},
  eprint       = {2011.12311},
  primaryClass = {astro-ph.EP},
  adsurl       = {https://ui.adsabs.harvard.edu/abs/2021A&A...646A..24S},
  adsnote      = {Provided by the SAO/NASA Astrophysics Data System}
}

For other citation formats, visit the ADS entry.

Versioning

The peer-reviewed publication describes release version v1.0.0 of TRAP.
Subsequent changes and feature additions are documented in the CHANGELOG.

v2.0.0 contains breaking changes. The legacy Reduction_parameters object and its bridge methods were removed, include_noise was renamed to estimate_noise_from_data, and Ray was replaced by joblib/loky. See the CHANGELOG for the migration details.

License

This project is licensed under the MIT License.

Author

Matthias Samland
GitHub: @m-samland