Metadata-Version: 2.4
Name: tess-vesper
Version: 0.1.1
Summary: VESPER - fast learned vetting of transiting-planet candidates around TESS M dwarfs
Author: Yohann Tschudi
License: MIT
Project-URL: Repository, https://gitlab.com/yohanntschudi/exoplanets-project
Project-URL: Model card, https://gitlab.com/yohanntschudi/exoplanets-project/-/blob/main/documentation/pipeline_ml/VETTER_MODEL_CARD.md
Keywords: TESS,exoplanets,vetting,M dwarfs,transits
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24
Requires-Dist: torch>=2.0
Requires-Dist: scikit-learn>=1.3
Requires-Dist: celerite2>=0.3.0
Provides-Extra: acquire
Requires-Dist: lightkurve>=2.4.0; extra == "acquire"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"

# VESPER

**Vetting Exoplanet Signals with Pixel-informed Evidence, Rapidly.**

VESPER is a fast, learned vetter for transiting-planet candidates around
**TESS M dwarfs**. Give it a star's TESS photometry and a candidate
ephemeris (period, epoch, duration); it returns a **calibrated probability
that the signal is a planet**, seven named impostor scores (background
eclipsing binary, eclipsing binary, window alias, stellar rotation,
companion dilution, no-signal, spacecraft systematics), and a keep/reject
disposition — in about a tenth of a second per star, entirely offline (no
external service calls). The frozen model, its full performance record and
its known limitations are documented in the model card
(`VETTER_MODEL_CARD.md`, shipped alongside this package).

## Install

**Python ≥ 3.10 required** — check with `python3 --version`. Work in a
fresh virtual environment (system Pythons are often older and their
site-packages messy):

```
python3.11 -m venv vesper-env          # any Python >= 3.10
source vesper-env/bin/activate         # Windows: vesper-env\Scripts\activate
pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install "tess-vesper[acquire]"
```

CPU-only torch is enough. The `[acquire]` extra adds lightkurve, used by
`vesper fetch` to download and prepare TESS photometry for you. The
package bundles the frozen model; installing it needs nothing else. The wheel bundles the frozen model
(weights, calibrator, decision threshold, M-dwarf stellar catalog); their
SHA-256 fingerprints are checked at every load.

## How it works

1. **You provide the ephemeris** — VESPER judges a candidate at a given
   (period, T0, duration); it complements your transit search and your
   follow-up, taking the statistical-vetting step in between.
2. **VESPER prepares its own photometry.** From stitched, median-normalised
   PDCSAP flux *before any detrending*, it removes stellar variability with
   its own Gaussian-process model on a 200 s grid — the exact preparation
   the network was trained and certified on. `vesper fetch` builds that
   input for any TIC directly from the TESS archive; if you supply your own
   curves, give it pre-detrending flux and let VESPER do the rest.
3. **It folds and judges.** The signal is folded into shape views (global,
   transit zoom, secondary, odd/even, per-observing-block), normalised to
   the star's own noise, and weighed together with the stellar parameters
   and — when you have them — difference-image centroid measurements.
4. **It answers in calibrated units.** `p_cal` is a calibrated probability;
   the shipped threshold (0.29565…, calibrated to keep 95 % of planets) turns
   it into a disposition, and the named impostor heads tell you *what* the
   signal most resembles when it is not a planet.

Domain: TESS M dwarfs (Teff ≲ 4,000 K), periods ~0.5–100 d, cadences
20–200 s. Anything the contract cannot serve comes back as an explicit
`blocked:...` status, never a silent skip.

## Try it — the bundled example

Two well-known M-dwarf systems: **L 98-59** (three small confirmed planets,
plus one unconfirmed 1.05 d candidate signal — judge it yourself) and
**TOI-700** (four confirmed planets, including the habitable-zone TOI-700 d).

```
vesper example
vesper fetch --candidates candidates_example.csv --out-dir example_curves
vesper vet-batch --candidates candidates_example.csv --curves-dir example_curves --out example_results.csv
```

The fetch downloads every TESS sector of both stars (a few minutes). Then
open `example_results.csv`: one row per candidate with `p_cal`, the named
impostor scores and the disposition.

For your own targets, write the same kind of CSV — header
`tic_id, period_days, t0_btjd, duration_hours` (optional: `depth_ppm`,
`planet_num`) — and run the same two commands. Single candidates:

```
vesper vet --tic 307210830 --period 7.450726 --t0 1355.29 --duration-h 1.68 \
           --curves-dir example_curves
```

## Reading the output

| Column | Meaning |
|---|---|
| `p_cal` | calibrated P(planet) — the number to read |
| `kept_literal` | `p_cal` ≥ the shipped threshold (planet-recall-95 operating point) |
| `cascade_fp` | the deep-eclipse prior fired (depth > 50,000 ppm and `p_cal` < 0.9). For very deep candidates around small stars, also read the `--no-cascade` disposition — giant planets on M dwarfs can exceed that depth |
| `final_literal` | the disposition: True = keep as a planet candidate |
| `aux_*` | the impostor heads — triage pointers to the most likely false-positive channel |
| `spatial_status` | `unmeasured` = no centroid evidence supplied (the default); pass `--spatial` CSVs when you have difference-image measurements |
| `row_status` | `served`, or an explicit `blocked:...` reason |

## License and citation

MIT. The reference article is in preparation; until it is out, cite this
package and its model card (`VETTER_MODEL_CARD.md`), which carries the full
provenance of the frozen model.
