exotransit 0.1.0

AI-enabled detection, classification, and characterization of exoplanet transit signals in noisy TESS light curves

exotransit

AI-enabled detection of exoplanets from noisy astronomical light curves.

An end-to-end pipeline that takes a raw TESS (or similar) light curve and:

1. Detects periodic dips using a Box Least Squares (BLS) search.
2. Classifies each dip as a transit, eclipsing_binary, blend, starspot, or other false positive, using a Random Forest trained on vetting-style features (odd/even depth difference, secondary eclipse depth, V-shape score, duration/period ratio, etc.).
3. Reports the signal-to-noise ratio / significance (SNR and Multiple Event Statistic) of the detected event.
4. For genuine transit candidates, estimates transit parameters — depth, period, duration, ingress duration, and Rp/Rs — via a trapezoid-model least-squares fit.

Built for the "AI-enabled Detection of Exoplanets from Noisy Astronomical Light Curves" project brief.

Install

pip install exotransit

To also fetch real TESS light curves from MAST (archive.stsci.edu):

pip install "exotransit[remote]"

Quickstart

CLI

# Run on built-in synthetic data (no download needed) — good smoke test:
exotransit demo

# Run on a local light curve file (CSV: time,flux[,flux_err] or a TESS SPOC .fits file):
exotransit run path/to/lightcurve.csv

# Fetch a real TESS target from MAST and run the pipeline on it:
exotransit fetch "TIC 261136679" --sector 15

Python API

from exotransit import ExotransitPipeline
from exotransit.data_loader import load_csv

lc = load_csv("path/to/lightcurve.csv")

pipeline = ExotransitPipeline()          # trains a classifier on synthetic data by default
result = pipeline.run(lc)

print(result.summary())

Example output:

[TIC 261136679]
  category      : transit (p=0.87)
  period        : 3.14159 d
  duration      : 2.410 h
  depth         : 823.4 ppm
  SNR / MES     : 7.92 / 14.31
  n transits    : 8
  refined depth : 810.2 ppm (Rp/Rs=0.0285)

Working with real TESS data

Per the project brief, bulk TESS light curves can be downloaded from the MAST archive. Two ways to get data into the pipeline:

1. Direct download + local file: download SPOC light curve FITS files for a sector, then:

   from exotransit.data_loader import load_fits
   lc = load_fits("tess2019199201929-s0014-0000000261136679-0150-s_lc.fits")
   

2. Programmatic fetch via lightkurve (requires network + the remote extra):

   from exotransit.data_loader import fetch_tess_lightcurve
   lc = fetch_tess_lightcurve("TIC 261136679", sector=14)
   

For batch-processing an entire sector (20-30k light curves as suggested in the brief), loop over target files/TIC IDs and call pipeline.run(lc) for each — see examples/batch_sector_example.py.

Note on the bundled model: ExotransitPipeline() loads a small pretrained classifier bundled with the package (exotransit/models/default_classifier.pkl, trained on synthetic data — see scripts/train_default_model.py) so pipeline start-up is instant instead of retraining every time. If your installed scikit-learn version is much newer than the one it was pickled with, you may see a harmless InconsistentVersionWarning; if you'd rather not depend on the bundled pickle at all, just call pipeline.classifier.train_on_synthetic() yourself, or train on your own data as shown below.

Training the classifier on real, curated data

The pipeline ships with a synthetic light-curve generator (exotransit.synthetic) so it is runnable immediately, and the built-in ExotransitPipeline() trains on synthetic data by default. Once you have the curated dataset of known exoplanets / false positives / eclipsing binaries mentioned in the brief, retrain on it directly:

from exotransit.classifier import DipClassifier
from exotransit.data_loader import load_csv

light_curves = [load_csv(p) for p in curated_file_paths]
labels = [...]  # e.g. "transit", "eclipsing_binary", "blend", "other"

clf = DipClassifier()
clf.train(light_curves, labels)
clf.save("exotransit_classifier.pkl")

Then use it in the pipeline:

from exotransit import ExotransitPipeline
from exotransit.classifier import DipClassifier

clf = DipClassifier.load("exotransit_classifier.pkl")
pipeline = ExotransitPipeline(classifier=clf)

Project layout

exotransit/
├── data_loader.py            # load local CSV/FITS or fetch from MAST
├── preprocessing.py          # sigma-clipping, detrending, normalization
├── detection.py              # Box Least Squares periodic-dip search
├── features.py               # vetting-style feature extraction
├── classifier.py             # RandomForest transit/EB/blend/starspot classifier
├── significance.py           # SNR / Multiple Event Statistic
├── parameter_estimation.py   # trapezoid-model transit parameter fit
├── synthetic.py              # synthetic light curve generator (demo/training)
├── pipeline.py                # end-to-end orchestration
└── cli.py                    # `exotransit` command-line tool

Method notes

• Detection: astropy.timeseries.BoxLeastSquares — the standard algorithm for box-shaped periodic transit/eclipse signals.
• Classification features: odd/even transit depth difference and secondary eclipse depth (classic eclipsing-binary tells), a V-shape score (grazing/blend tell), duration/period ratio, depth, and SNR — the same style of features used in the Kepler/TESS Robovetter and Autovetter vetting pipelines.
• Significance: both a single-event SNR (depth / local out-of-transit scatter) and the Multiple Event Statistic (MES), which combines all individual transit epochs and is what actually determines detectability against the noise floor for periodic search.
• Parameter estimation: a trapezoidal (flat-bottom + linear ingress/egress) least-squares fit to the phase-folded light curve, chosen over a full limb-darkened model because it needs no stellar limb-darkening priors and is more robust on noisy, crowded-field TESS data.

Running tests

pip install -e ".[dev]"
pytest

License

MIT — see LICENSE.