Transit Hunter

How it works

The pipeline

One command takes a star's TIC ID through six stages. Each stage is a separate module that can be used on its own, and each has a page here with the maths, the design decisions and figures from real pipeline runs.

flowchart TB
    subgraph S1["Find"]
        direction LR
        A["MAST archive<br/>SPOC 2-min light curves"] --> B["<b>1 · Clean</b><br/>flags, outliers,<br/>normalize, cache"] --> C["<b>2 · Detrend</b><br/>robust biweight<br/>filter"] --> D["<b>3 · Search</b><br/>iterative BLS<br/>SDE + S/N"]
        D -->|"found one: mask it,<br/>re-detrend, search again"| C
    end
    subgraph S2["Characterize"]
        direction LR
        E["<b>4 · Fit</b><br/>batman + emcee"] --> F["<b>5 · Vet</b><br/>nine tests"] --> G["report.json<br/>summary.md, figures"]
    end
    S1 --> S2
    H["<b>6 · Inject</b><br/>fake planets through<br/>detrend + search"] -.-> S1
01

Download & clean

Fetch every 2-minute TESS sector, drop flagged cadences, clip only the outliers that can't be transits.

data.py 02

Detrend

A robust sliding filter removes starspots and drifts while leaving transits intact.

detrend.py 03

Search

Box Least Squares tries millions of period, phase and duration combinations and keeps what beats the noise.

search.py 04

Fit

A physical transit model sampled with MCMC turns a dip into a planet radius, orbit and uncertainties.

fit.py 05

Vet

Seven tests hunt for the fingerprints of eclipsing binaries, starspots and instrumental artifacts.

vet.py 06

Injection–recovery

Thousands of fake planets measure what the search can and cannot see.

inject.py

What comes out

Every run writes a folder, reports/TIC<ID>/:

file contents
report.json every number: target, stellar parameters, noise, all search iterations, posterior summaries, derived quantities, vetting tests, configuration, software versions, data provenance
summary.md human-readable summary with the vetting reasoning
detrending.png raw flux with trend, flattened flux
search_summary.png, periodogram_<n>.png, fold_<n>.png BLS periodograms and folded light curves per iteration
fit_<n>.png, corner_<n>.png best-fitting model with residuals; posterior corner plot
vetting_<n>.png odd/even, phase 0.5, transit shape, stellar density

A complete example, a simulated three-planet M-dwarf system, is in results/synthetic_benchmark/SYN-3/. The figures on the step pages come from that folder and from the eclipsing-binary control SYN-5.

transit-hunter run --tic 261136679 --outdir reports/          # one real star (needs MAST access)
transit-hunter demo --outdir reports/                         # offline: synthetic 3-planet system

In a terminal, both commands show a live progress line: the stages done, a bar for each periodogram and MCMC fit, and the elapsed time. --plain turns it off, and it never appears in files, pipes or CI logs.

The parameter-by-parameter reference, with every default and citation, is the methods reference.