monohunter

Find single long-period mono-transits in public TESS light curves — the single-transit events that periodic pipelines (SPOC/QLP, which fold on a period) structurally under-find. Built so many people can each search under-covered targets and combine machine-readable finds.

New here? Run it in your browser — no install. The quickstart notebook installs monohunter in Colab, recovers a known single transit to prove it works, then scans any star you pick. Open it with the badge above.

Why

Automated TESS pipelines run periodic searches (BLS/TLS) over every target. A single transit has no period to fold on, so those searches miss it. Real long-period planets have been co-discovered exactly here (e.g. TOI-2180 b, found from one ~24-hour transit). monohunter targets that gap.

Install

pip install monohunter

Python 3.10+. Pulls in lightkurve, wotan, astroquery, scipy, matplotlib. The ASAS-SN ground cross-check needs one extra: pip install monohunter[ground].

Or run it with Docker (no Python setup)

docker run --rm -v "$PWD/data:/data" ghcr.io/rinkia/monohunter \
    run --tic 298663873 --sectors 19

Outputs land in ./data. For a always-on fresh-data watcher (ideal on a homelab), docker compose up -d runs monohunter watch on the newest sector in a resumable, self-healing loop — see docker-compose.yml.

Usage

Search one target by its TESS Input Catalog (TIC) id:

monohunter run --tic 298663873

This searches every available sector, and for each candidate writes a JSON find-record + a diagnostic PNG into candidates/. Example (TOI-2180, the canonical mono-transit — restrict to its sector to keep it quick):

monohunter run --tic 298663873 --sectors 19
# S19: depth=4.09ppt dur=24h SNR=39.4  [known TOI-2180.01] -> candidates/tic298663873_s19.json

Options

Reading a result

Each candidate is one JSON file:

{
  "schema_version": 6,
  "tic": 298663873,
  "sector": 19,
  "cadence_s": 120,
  "event_time_btjd": 1830.77,
  "depth_ppt": 4.09,
  "duration_hr": 23.8,
  "ingress_hr": 2.29,
  "snr": 39.4,
  "tool_version": "0.3.0",
  "known_toi_match": true,
  "known_toi_id": "TOI-2180.01",
  "likely_eb": false,
  "period_constrained": true,
  "p_best_d": 856.0,
  "p_lo_d": 396.0,
  "p_hi_d": 1946.0,
  "next_window_btjd": [3200.0, 3245.0, 3290.0],
  "n_sectors_observed": 1,
  "recurring_dip": false,
  "measured_period_d": null,
  "plot_path": "candidates/tic298663873_s19.png"
}

Always look at the PNG. SNR alone lies — confirm the marked dip is a real, centered transit, not a sector-edge ramp, a data gap, or a single bad cadence. Re-run with a different --window; a real dip survives, an artifact moves or vanishes. A known_toi_match: false is the interesting case (potentially unsearched); true still validates the tool.

A candidate is not a discovery. It means a human thinks the dip is real. Confirming a planet needs follow-up (radial velocity, more transits) beyond this tool.

How it works

fetch      search TESS, dedup sectors (prefer 2-min), quality-mask (hard),
           stream one sector at a time
   |
detrend    wotan biweight; window must be >> transit or the dip is flattened away
   |
detect     matched-filter box scan (non-periodic — finds a SINGLE transit),
           red-noise-aware SNR + 7 false-positive guards (edge / gap / scatter /
           momentum-dump ramps)
   |
characterize   trapezoid fit -> true depth, duration, ingress; EB flag
   |
cross-match    flag known TESS Objects of Interest (NASA Exoplanet Archive)
   |
ephemeris      period + next-transit window (single-transit, or exact from
           multiple sectors); multi-sector recurrence flag
   |
FindRecord     versioned + validated JSON  ->  candidates/

The Detector interface is a seam: v1 is the box scan; a GP-based detector (nuance) can plug in later without touching the pipeline. The versioned FindRecord JSON is the contract a future aggregation server consumes.

Reuse, not reinvention

Stands on lightkurve, wotan, scipy, and astroquery. monohunter is orchestration + the single-transit gap + result aggregation, not a new detection engine.

Fresh-data watcher (be first)

Institutional pipelines take weeks-to-months to vet a new TESS sector. Run the watcher on a schedule and you process a sector within hours of its release — and a single transit you flag comes with a next-transit window (see below) an observer can still act on.

monohunter watch --sector 90 --max 100 --out watch_out --state watch_state.json

Each run scans the next --max un-processed targets of the sector and prints any not-yet-known candidates. It's resumable: state tracks which TICs are done, so scheduled runs continue where the last stopped and a crash loses nothing.

Schedule it to keep chewing through the sector:

# Linux/macOS cron — every 2 hours
0 */2 * * * cd /path/to/monohunter && monohunter watch --sector 90 --max 200

# Windows: Task Scheduler → run the same command on a trigger

Point --sector at the newest released sector. Candidates land in watch_out/; vet each with monohunter run --tic <id> --sectors <N> to get its PNG, then submit the good ones (see Contributing).

Reproducible sweeps. watch is the sweep tool — resumable, parallel, and it logs provenance. For a full sector sweep:

monohunter watch --sector 17 --max 5000 --workers 3 --max-hours 5 \
    --summaries summaries_s17 --csv-log sweeps/sector17.csv

--max-hours is a safety net: a hung MAST socket can wedge a worker indefinitely, so the run force-exits past that wall-clock (set it a bit above the expected runtime). It's resumable — re-run the same command to continue where it stopped.

--csv-log appends one status row per star (none/novel/error) — the scan-log a catalog and any retry build from. A star that errors (usually a transient MAST hiccup) is logged and left un-processed, so simply re-running the same command retries only the failures — no manual cleanup. --summaries writes the rotation/variability catalog from the same downloads.

Next-transit ephemeris

When a candidate's target has a catalog stellar density, monohunter estimates the period from the transit duration and predicts when the next transit could occur:

S19: depth=4.09ppt dur=24h SNR=39.4  [known TOI-2180.01]
    P~856d (396-1946d, P_min 15d), next transit ~2027-08-07

Single-transit periods are inherently uncertain (a range, not a precise value) — the output is a targeting window for follow-up, not a confirmed ephemeris. If the stellar density is missing or too uncertain, monohunter reports the period as unconstrained rather than guessing.

Multi-sector sharpens both. A target that dips in more than one sector is flagged recurring_dip (periodic/variable, not a clean mono-transit), and once it transits in ≥3 sectors the exact period is fitted from the transit times (measured_period_d) — vastly tighter than the single-transit range.

More commands

Anomaly detection — flares (brightenings) and dippers (aperiodic multi-dip young stars), on the same light curves:

monohunter anomaly --tic 441420236     # AU Mic: flares detected

FFI reach — extract from the Full-Frame Images to search stars with no pre-made light curve. One target (run --ffi), or a whole cutout at once:

monohunter ffi-batch --tic <center> --sector 14   # every catalog star in one cutout

Ground cross-check — is a candidate's host quiet over years, or a variable star / eclipsing binary? Confirm against ZTF or ASAS-SN:

monohunter ground --tic 198382838 --survey ztf     # or --survey asassn

Eclipsing-binary periods — an EB with two or more eclipses in one sector has a recoverable orbital period. eb finds the eclipse times, splits primary from secondary by depth, and fits the period from the primary times (their spacing is exactly one orbit):

monohunter eb --tic 271763138 --sectors 15
# S15: 2 eclipses (1 primary) (primary+secondary) -> period needs >=2 same-type eclipses

A lone primary+secondary pair is left unrecoverable on purpose — on an eccentric orbit the secondary sits at an unknown phase, so the primary-secondary gap is not a period fraction. The tool never reports a confident wrong period.

Rotation / variability catalog — the same download that feeds the transit scan also yields a per-star rotation period, variability amplitude, flare count, and a sub-class. summarize writes one JSON per star; catalog aggregates them:

monohunter summarize --tic 100010286              # rotation/variability/flares/dipper + subclass
monohunter catalog --summaries summaries --out catalog.csv

The subclass field splits variables into eclipsing (≥2 eclipse-shaped dips), pulsator (near-pure sinusoid, low 2nd-harmonic content), and rotator (non-sinusoidal spot modulation) via periodogram harmonics.

Rotation-period distribution — a population science figure straight from a catalog CSV: the period distribution and the period–amplitude relation over every rotator in the sweep:

monohunter rotation-plot --csv catalogs/sector15.csv --sector 15 --out rotation.png

Faster sweeps — watch (and the sweep scripts) take --workers N for parallel MAST downloads (network-bound; keep it modest, 4-8).

Crowd vetting + triage — turn a pile of candidates into a labelled queue, then rank future survivors by how much they deserve a human's eyes:

monohunter vet --candidates candidates --out _vet      # static page: PNGs + label buttons
monohunter triage-train --labels labels/seed_labels.csv --sweeps sweeps
monohunter triage --candidates candidates              # ranks by P(worth vetting)

The vetting page exports labels as JSON; those labels train the triage model, which then puts the real finds at the top of the next sweep's queue.

Community leaderboard (swarm)

Submitted candidates are aggregated into one ranked list — deduped by (tic, sector), ranked by novelty (not a known TOI), cross-submitter agreement, and SNR. Live at https://rinkia.github.io/monohunter/, rebuilt automatically on every merged contribution.

Vetted candidates worth follow-up (RV, characterization, a second transit) are tracked in docs/followup-targets.md — currently led by TIC 400048097, a bright, uncatalogued star with one clean 2.5% transit.

Build it yourself from a contributions/ tree:

monohunter aggregate --contributions contributions --out _site
# writes _site/index.html + _site/leaderboard.json

This is phase 1 of the swarm: pure aggregation over the PR flow, no backend. A live coordination server (handing out targets so no two people search the same star) is a later increment, worth building only once there's real contention.

One-time to publish: repo Settings → Pages → Source = "GitHub Actions" (the pages.yml workflow does the rest).

Contributing

Found a candidate, or want to improve the detector? See CONTRIBUTING.md.

• No git? Use the issue form. Open a Submit a candidate issue — fill in the TIC, sector, stats, drag in the PNG, tick the vetting boxes. A maintainer turns a complete submission into a leaderboard entry.
• Comfortable with git? Candidate submissions go to contributions/<username>/ via the candidate PR template.

Development

git clone https://github.com/Rinkia/monohunter
cd monohunter
python -m venv .venv && . .venv/Scripts/activate   # Windows
pip install -e ".[dev]"
pytest -q                 # fast, offline unit tests
pytest --runslow          # + live real-data regression (hits MAST)

Releasing to PyPI

CI (.github/workflows/ci.yml) runs the tests on every push. Publishing (.github/workflows/release.yml) fires on a version tag and uses Trusted Publishing — no token in GitHub.

One-time PyPI setup (before the first release):

1. On PyPI: Account → Publishing → Add a pending publisher:
   • PyPI project name: monohunter
   • Owner: Rinkia · Repository: monohunter
   • Workflow: release.yml · Environment: leave blank (Any)
2. (Optional) For a manual approval gate, create a GitHub Environment, set it as the pending-publisher Environment, and add environment: <name> back to the publish job in release.yml.

Then release:

# bump version in pyproject.toml + monohunter/__init__.py, update CHANGELOG.md
git tag vX.Y.Z
git push origin vX.Y.Z

License

MIT.