Metadata-Version: 2.4
Name: trap-hci
Version: 2.1.0
Summary: Detection of exoplanets in direct imaging data by causal regression of temporal systematics
Author-email: Matthias Samland <m.samland@mailbox.org>
License-Expression: MIT
Project-URL: Bug Tracker, https://github.com/m-samland/trap/issues
Project-URL: Source Code, https://github.com/m-samland/trap
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3,>=2
Requires-Dist: scipy
Requires-Dist: matplotlib
Requires-Dist: numba
Requires-Dist: pandas
Requires-Dist: scikit-learn
Requires-Dist: astropy>7.0
Requires-Dist: photutils
Requires-Dist: seaborn
Requires-Dist: tqdm
Requires-Dist: joblib
Requires-Dist: bottleneck
Requires-Dist: natsort
Requires-Dist: dill
Requires-Dist: species>=0.11.0
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx-automodapi; extra == "docs"
Requires-Dist: numpydoc; extra == "docs"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-doctestplus; extra == "test"
Requires-Dist: codecov; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: ruff; extra == "test"
Provides-Extra: all
Requires-Dist: ipython; extra == "all"
Requires-Dist: jupyterlab; extra == "all"
Requires-Dist: ipywidgets; extra == "all"
Requires-Dist: ipympl; extra == "all"
Dynamic: license-file

# TRAP – Temporal Reference Analysis for Planets

[![Python](https://img.shields.io/badge/Python-3.11%2C%203.12%2C%203.13-brightgreen.svg)](https://github.com/m-samland/trap)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/m-samland/trap/blob/main/LICENSE)
[![DOI](https://img.shields.io/badge/DOI-10.1051%2F0004--6361%2F201937308-blue)](https://doi.org/10.1051/0004-6361/201937308)

**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](https://ui.adsabs.harvard.edu/abs/2021A%26A...646A..24S/abstract)

---

## 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`](https://github.com/tomasstolker/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](https://joblib.readthedocs.io/)/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`:

```bash
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:

```bash
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](https://github.com/m-samland/trap/blob/main/examples/tutorial.ipynb) and [example dataset](https://github.com/m-samland/trap/tree/main/examples/test_data) 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:

```python
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**](https://github.com/m-samland/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](https://ui.adsabs.harvard.edu/abs/2022A%26A...668A..84S/abstract)) — 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](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:

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

Alternatively, a [pixi](https://pixi.sh) environment is provided:

```bash
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:

```bash
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](https://github.com/m-samland/trap/labels/good%20first%20issue) 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](https://ui.adsabs.harvard.edu/abs/2021A%26A...646A..24S)  
> DOI: [10.1051/0004-6361/201937308](https://doi.org/10.1051/0004-6361/201937308)

```bibtex
@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](https://ui.adsabs.harvard.edu/abs/2021A%26A...646A..24S/exportcitation).

---

## Versioning

The peer-reviewed publication describes release version **v1.0.0** of TRAP.  
Subsequent changes and feature additions are documented in the [CHANGELOG](https://github.com/m-samland/trap/blob/main/CHANGELOG.md).

**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](https://github.com/m-samland/trap/blob/main/CHANGELOG.md) for the migration details.

---

## License

This project is licensed under the [MIT License](https://github.com/m-samland/trap/blob/main/LICENSE).

---

## Author

**Matthias Samland**  
GitHub: [@m-samland](https://github.com/m-samland)
