# deaththekid1614/exoplanet architecture

> Architecture diagram of the GitHub repository deaththekid1614/exoplanet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/deaththekid1614/exoplanet
- Repository: https://github.com/deaththekid1614/exoplanet

## Overview

This is a CPU-only TESS exoplanet transit-candidate detection and vetting pipeline. Users provide TIC IDs (or generate demo targets); the runner executes preprocessing, transit detection, stellar-context lookup, physics validation, ML classification, parameter estimation, ensemble scoring, and reporting. The README documents the stage sequence and external data sources; source excerpts confirm selected implementations and calls. Several stage implementations were not sampled, so their documented links use the README as evidence.

Main entry points: [`run_pipeline.py`](https://github.com/deaththekid1614/exoplanet/blob/main/run_pipeline.py) (Pipeline Runner), [`tess_pipeline/stage2_detect.py`](https://github.com/deaththekid1614/exoplanet/blob/main/tess_pipeline/stage2_detect.py) (BLS and TLS Search), [`tess_pipeline/stage5_classify.py`](https://github.com/deaththekid1614/exoplanet/blob/main/tess_pipeline/stage5_classify.py) (ML Classifier), [`tess_pipeline/stage1_preprocess.py`](https://github.com/deaththekid1614/exoplanet/blob/main/tess_pipeline/stage1_preprocess.py) (Light-Curve Prep)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Inputs and Preprocessing"]
  node_tic_ids["TIC ID Lists<br/>[tic_ids.csv]"]
  node_demo["Demo Generator<br/>[demo_data.py]"]
  node_config["Pipeline Config<br/>[config.py]"]
  node_runner["Pipeline Runner<br/>[run_pipeline.py]"]
  node_preprocess["Light-Curve Prep"]
  node_utils["Shared Utilities<br/>[utils.py]"]
end

subgraph group_detection["Transit Detection"]
  node_bls_tls["BLS and TLS Search<br/>[stage2_detect.py]"]
  node_harmonics["Harmonic Analysis"]
end

subgraph group_vetting["Candidate Vetting"]
  node_gaia["Gaia Context<br/>[stage3_gaia.py]"]
  node_physics["Physics Checks<br/>[stage4_physics.py]"]
  node_classifier["ML Classifier<br/>[stage5_classify.py]"]
  node_training_data["Training Labels"]
end

subgraph group_results["Scoring and Reporting"]
  node_parameters["Parameter Fitting<br/>[stage6_params.py]"]
  node_ensemble["Ensemble Scoring<br/>[stage7_ensemble.py]"]
  node_visualize["Plots and Reports"]
  node_explainability["SHAP Explanations<br/>[shap_explainer.py]"]
end

node_user(("Pipeline User"))
node_mast[("MAST Archive")]
node_gaia_service[("Gaia DR3")]

node_user -->|"starts"| node_runner
node_user -->|"provides"| node_tic_ids
node_tic_ids -->|"loads targets"| node_runner
node_runner -->|"generates demo data"| node_demo
node_runner -->|"loads settings"| node_config
node_runner -->|"runs first"| node_preprocess
node_mast -->|"supplies light curves"| node_preprocess
node_preprocess -->|"feeds prepared curves"| node_bls_tls
node_bls_tls -->|"checks aliases"| node_harmonics
node_bls_tls -->|"passes candidates"| node_gaia
node_gaia_service -->|"provides stellar data"| node_gaia
node_gaia -->|"supplies stellar context"| node_physics
node_physics -->|"provides validation features"| node_classifier
node_training_data -->|"trains classifier"| node_classifier
node_classifier -->|"passes classifications"| node_parameters
node_parameters -->|"passes estimates"| node_ensemble
node_ensemble -->|"reports verdicts"| node_visualize
node_classifier -.-> node_explainability
node_bls_tls -->|"uses shared helpers"| node_utils

click node_tic_ids "https://github.com/deaththekid1614/exoplanet/blob/main/data/tic_ids.csv"
click node_demo "https://github.com/deaththekid1614/exoplanet/blob/main/tess_pipeline/demo_data.py"
click node_config "https://github.com/deaththekid1614/exoplanet/blob/main/tess_pipeline/config.py"
click node_runner "https://github.com/deaththekid1614/exoplanet/blob/main/run_pipeline.py"
click node_preprocess "https://github.com/deaththekid1614/exoplanet/blob/main/tess_pipeline/stage1_preprocess.py"
click node_bls_tls "https://github.com/deaththekid1614/exoplanet/blob/main/tess_pipeline/stage2_detect.py"
click node_harmonics "https://github.com/deaththekid1614/exoplanet/blob/main/tess_pipeline/harmonic/harmonic_analysis.py"
click node_gaia "https://github.com/deaththekid1614/exoplanet/blob/main/tess_pipeline/stage3_gaia.py"
click node_physics "https://github.com/deaththekid1614/exoplanet/blob/main/tess_pipeline/stage4_physics.py"
click node_classifier "https://github.com/deaththekid1614/exoplanet/blob/main/tess_pipeline/stage5_classify.py"
click node_training_data "https://github.com/deaththekid1614/exoplanet/blob/main/data/real_training/training_labels.csv"
click node_parameters "https://github.com/deaththekid1614/exoplanet/blob/main/tess_pipeline/stage6_params.py"
click node_ensemble "https://github.com/deaththekid1614/exoplanet/blob/main/tess_pipeline/stage7_ensemble.py"
click node_visualize "https://github.com/deaththekid1614/exoplanet/blob/main/tess_pipeline/stage8_visualize.py"
click node_explainability "https://github.com/deaththekid1614/exoplanet/blob/main/tess_pipeline/explainability/shap_explainer.py"
click node_utils "https://github.com/deaththekid1614/exoplanet/blob/main/tess_pipeline/utils.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_tic_ids,node_demo,node_config,node_runner,node_preprocess,node_utils,node_user toneBlue
class node_bls_tls,node_harmonics,node_mast,node_gaia_service toneAmber
class node_gaia,node_physics,node_classifier,node_training_data toneMint
class node_parameters,node_ensemble,node_visualize,node_explainability toneRose
```

## Components

### Inputs and Preprocessing

- [TIC ID Lists](https://github.com/deaththekid1614/exoplanet/blob/main/data/tic_ids.csv): `data/tic_ids.csv`
- [Demo Generator](https://github.com/deaththekid1614/exoplanet/blob/main/tess_pipeline/demo_data.py): `tess_pipeline/demo_data.py`
- [Pipeline Config](https://github.com/deaththekid1614/exoplanet/blob/main/tess_pipeline/config.py): `tess_pipeline/config.py`
- [Pipeline Runner](https://github.com/deaththekid1614/exoplanet/blob/main/run_pipeline.py): `run_pipeline.py`
- [Light-Curve Prep](https://github.com/deaththekid1614/exoplanet/blob/main/tess_pipeline/stage1_preprocess.py): `tess_pipeline/stage1_preprocess.py`
- [Shared Utilities](https://github.com/deaththekid1614/exoplanet/blob/main/tess_pipeline/utils.py): `tess_pipeline/utils.py`

### Transit Detection

- [BLS and TLS Search](https://github.com/deaththekid1614/exoplanet/blob/main/tess_pipeline/stage2_detect.py): `tess_pipeline/stage2_detect.py`
- [Harmonic Analysis](https://github.com/deaththekid1614/exoplanet/blob/main/tess_pipeline/harmonic/harmonic_analysis.py): `tess_pipeline/harmonic/harmonic_analysis.py`

### Candidate Vetting

- [Gaia Context](https://github.com/deaththekid1614/exoplanet/blob/main/tess_pipeline/stage3_gaia.py): `tess_pipeline/stage3_gaia.py`
- [Physics Checks](https://github.com/deaththekid1614/exoplanet/blob/main/tess_pipeline/stage4_physics.py): `tess_pipeline/stage4_physics.py`
- [ML Classifier](https://github.com/deaththekid1614/exoplanet/blob/main/tess_pipeline/stage5_classify.py): `tess_pipeline/stage5_classify.py`
- [Training Labels](https://github.com/deaththekid1614/exoplanet/blob/main/data/real_training/training_labels.csv): `data/real_training/training_labels.csv`

### Scoring and Reporting

- [Parameter Fitting](https://github.com/deaththekid1614/exoplanet/blob/main/tess_pipeline/stage6_params.py): `tess_pipeline/stage6_params.py`
- [Ensemble Scoring](https://github.com/deaththekid1614/exoplanet/blob/main/tess_pipeline/stage7_ensemble.py): `tess_pipeline/stage7_ensemble.py`
- [Plots and Reports](https://github.com/deaththekid1614/exoplanet/blob/main/tess_pipeline/stage8_visualize.py): `tess_pipeline/stage8_visualize.py`
- [SHAP Explanations](https://github.com/deaththekid1614/exoplanet/blob/main/tess_pipeline/explainability/shap_explainer.py): `tess_pipeline/explainability/shap_explainer.py`

### Other components

- **Pipeline User**
- **MAST Archive**
- **Gaia DR3**

## Connections

- Pipeline User → Pipeline Runner: starts (evidence: `README.md`)
- Pipeline User → TIC ID Lists: provides (evidence: `README.md`)
- TIC ID Lists → Pipeline Runner: loads targets (evidence: `run_pipeline.py`)
- Pipeline Runner → Demo Generator: generates demo data (evidence: `run_pipeline.py`)
- Pipeline Runner → Pipeline Config: loads settings (evidence: `run_pipeline.py`)
- Pipeline Runner → Light-Curve Prep: runs first (evidence: `README.md`)
- MAST Archive → Light-Curve Prep: supplies light curves (evidence: `README.md`)
- Light-Curve Prep → BLS and TLS Search: feeds prepared curves (evidence: `README.md`)
- BLS and TLS Search → Harmonic Analysis: checks aliases (evidence: `tess_pipeline/stage2_detect.py`)
- BLS and TLS Search → Gaia Context: passes candidates (evidence: `README.md`)
- Gaia DR3 → Gaia Context: provides stellar data (evidence: `README.md`)
- Gaia Context → Physics Checks: supplies stellar context (evidence: `README.md`)
- Physics Checks → ML Classifier: provides validation features (evidence: `README.md`)
- Training Labels → ML Classifier: trains classifier (evidence: `README.md`)
- ML Classifier → Parameter Fitting: passes classifications (evidence: `README.md`)
- Parameter Fitting → Ensemble Scoring: passes estimates (evidence: `README.md`)
- Ensemble Scoring → Plots and Reports: reports verdicts (evidence: `README.md`)
- ML Classifier → SHAP Explanations
- BLS and TLS Search → Shared Utilities: uses shared helpers (evidence: `tess_pipeline/stage2_detect.py`)