Metadata-Version: 2.4
Name: exotransit
Version: 0.1.0
Summary: AI-enabled detection, classification, and characterization of exoplanet transit signals in noisy TESS light curves
Author: Pranav
License: MIT
Project-URL: Homepage, https://github.com/yourusername/exotransit
Project-URL: Issues, https://github.com/yourusername/exotransit/issues
Keywords: exoplanet,transit,TESS,astronomy,light curve,box least squares,BLS,machine learning,astrophysics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Requires-Dist: scipy>=1.9
Requires-Dist: astropy>=5.2
Requires-Dist: scikit-learn<1.9,>=1.6
Provides-Extra: remote
Requires-Dist: lightkurve>=2.4; extra == "remote"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# 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

```bash
pip install exotransit
```

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

```bash
pip install "exotransit[remote]"
```

## Quickstart

### CLI

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

```python
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](https://archive.stsci.edu/tess/tic_ctl.html). Two ways to get
data into the pipeline:

1. **Direct download + local file**: download SPOC light curve FITS files for
   a sector, then:
   ```python
   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):
   ```python
   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:

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

```python
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

```bash
pip install -e ".[dev]"
pytest
```

## License

MIT — see `LICENSE`.
