# astrovall02/tess-vet-cnn architecture

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

- Interactive diagram: https://gitdiagram.com/astrovall02/tess-vet-cnn
- Repository: https://github.com/astrovall02/tess-vet-cnn

## Overview

TESS-Vet is a research pipeline for classifying TESS exoplanet candidates as planets or false positives. Its main workflow prepares candidate labels and engineered catalog features, pairs them with phase-folded light curves, trains and evaluates a dual-branch CNN under a train/validation/test protocol, then summarizes saved predictions. Separate branches cover catalog-only feature studies and centroid vetting. The README documents some data-acquisition and model details not visible in the sampled source, so those links are cited to the README or left unverified.

Main entry points: [`data/processed_labels_v2.csv`](https://github.com/astrovall02/tess-vet-cnn/blob/main/data/processed_labels_v2.csv) (Processed labels), [`src/run_protocol.py`](https://github.com/astrovall02/tess-vet-cnn/blob/main/src/run_protocol.py) (Training protocol), [`src/data_setup.py`](https://github.com/astrovall02/tess-vet-cnn/blob/main/src/data_setup.py) (Dataset and splits), [`src/fetch_data.py`](https://github.com/astrovall02/tess-vet-cnn/blob/main/src/fetch_data.py) (Catalog ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_catalog_ingest["Catalog ingestion<br/>[fetch_data.py]"]
  node_labels["Processed labels"]
  node_lightcurve_etl["Light-curve ETL"]
  node_lightcurves["Light-curve arrays"]
  node_feature_engineering["Catalog features"]
end

subgraph group_classifier["CNN classification"]
  node_dataset["Dataset and splits<br/>[data_setup.py]"]
  node_model["Dual-branch CNN<br/>[models.py]"]
  node_protocol["Training protocol<br/>[run_protocol.py]"]
end

subgraph group_evaluation["Evaluation studies"]
  node_probabilities["Saved probabilities"]
  node_results["Metrics and predictions<br/>[make_results.py]"]
  node_catalog_baseline["Catalog baseline"]
  node_catalog_ablation["Catalog ablation"]
end

subgraph group_centroid["Centroid vetting"]
  node_spoc_coverage["SPOC coverage"]
  node_spoc_features["Centroid features"]
  node_centroid_checks["Difference-image checks<br/>[centroid_checks.py]"]
end

node_exofop(("ExoFOP catalog"))
node_mast(("MAST / TESS"))
node_spoc(("SPOC light curves"))
node_tic(("TIC catalog"))
node_diffimage["transit-diffImage"]

node_exofop -->|"provides table"| node_catalog_ingest
node_catalog_ingest -->|"writes labels"| node_labels
node_mast -->|"provides curves"| node_lightcurve_etl
node_lightcurve_etl -->|"builds arrays"| node_lightcurves
node_labels -->|"engineers features"| node_feature_engineering
node_labels -->|"loads labels"| node_dataset
node_lightcurves -->|"loads arrays"| node_dataset
node_dataset -->|"feeds batches"| node_protocol
node_feature_engineering -.->|"supplies features"| node_protocol
node_protocol -.->|"trains and predicts"| node_model
node_protocol -->|"saves predictions"| node_probabilities
node_probabilities -->|"summarizes"| node_results
node_labels -->|"evaluates features"| node_catalog_baseline
node_labels -->|"tests ablations"| node_catalog_ablation
node_labels -->|"checks targets"| node_spoc_coverage
node_spoc -->|"searches sectors"| node_spoc_coverage
node_spoc -->|"provides centroids"| node_spoc_features
node_tic -->|"provides positions"| node_centroid_checks
node_diffimage -.->|"supports fits"| node_centroid_checks

click node_catalog_ingest "https://github.com/astrovall02/tess-vet-cnn/blob/main/src/fetch_data.py"
click node_labels "https://github.com/astrovall02/tess-vet-cnn/blob/main/data/processed_labels_v2.csv"
click node_lightcurve_etl "https://github.com/astrovall02/tess-vet-cnn/blob/main/notebooks/02_NASA_ETL_Pipeline.ipynb"
click node_lightcurves "https://github.com/astrovall02/tess-vet-cnn/tree/main/data"
click node_feature_engineering "https://github.com/astrovall02/tess-vet-cnn/blob/main/src/build_aux_features.py"
click node_dataset "https://github.com/astrovall02/tess-vet-cnn/blob/main/src/data_setup.py"
click node_model "https://github.com/astrovall02/tess-vet-cnn/blob/main/src/models.py"
click node_protocol "https://github.com/astrovall02/tess-vet-cnn/blob/main/src/run_protocol.py"
click node_probabilities "https://github.com/astrovall02/tess-vet-cnn/tree/main/results/probs"
click node_results "https://github.com/astrovall02/tess-vet-cnn/blob/main/experiments/make_results.py"
click node_catalog_baseline "https://github.com/astrovall02/tess-vet-cnn/blob/main/experiments/catalog_baseline.py"
click node_catalog_ablation "https://github.com/astrovall02/tess-vet-cnn/blob/main/experiments/catalog_ablation.py"
click node_spoc_coverage "https://github.com/astrovall02/tess-vet-cnn/blob/main/centroid/check_spoc_coverage.py"
click node_spoc_features "https://github.com/astrovall02/tess-vet-cnn/blob/main/centroid/extract_centroid_features.py"
click node_centroid_checks "https://github.com/astrovall02/tess-vet-cnn/blob/main/centroid/centroid_checks.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_catalog_ingest,node_labels,node_lightcurve_etl,node_lightcurves,node_feature_engineering toneBlue
class node_dataset,node_model,node_protocol toneAmber
class node_probabilities,node_results,node_catalog_baseline,node_catalog_ablation toneMint
class node_spoc_coverage,node_spoc_features,node_centroid_checks toneRose
class node_exofop,node_mast,node_spoc,node_tic,node_diffimage toneIndigo
```

## Components

### Data preparation

- [Catalog ingestion](https://github.com/astrovall02/tess-vet-cnn/blob/main/src/fetch_data.py): `src/fetch_data.py`
- [Processed labels](https://github.com/astrovall02/tess-vet-cnn/blob/main/data/processed_labels_v2.csv): `data/processed_labels_v2.csv`
- [Light-curve ETL](https://github.com/astrovall02/tess-vet-cnn/blob/main/notebooks/02_NASA_ETL_Pipeline.ipynb): `notebooks/02_NASA_ETL_Pipeline.ipynb`
- [Light-curve arrays](https://github.com/astrovall02/tess-vet-cnn/tree/main/data): `data`
- [Catalog features](https://github.com/astrovall02/tess-vet-cnn/blob/main/src/build_aux_features.py): `src/build_aux_features.py`

### CNN classification

- [Dataset and splits](https://github.com/astrovall02/tess-vet-cnn/blob/main/src/data_setup.py): `src/data_setup.py`
- [Dual-branch CNN](https://github.com/astrovall02/tess-vet-cnn/blob/main/src/models.py): `src/models.py`
- [Training protocol](https://github.com/astrovall02/tess-vet-cnn/blob/main/src/run_protocol.py): `src/run_protocol.py`

### Evaluation studies

- [Saved probabilities](https://github.com/astrovall02/tess-vet-cnn/tree/main/results/probs): `results/probs`
- [Metrics and predictions](https://github.com/astrovall02/tess-vet-cnn/blob/main/experiments/make_results.py): `experiments/make_results.py`
- [Catalog baseline](https://github.com/astrovall02/tess-vet-cnn/blob/main/experiments/catalog_baseline.py): `experiments/catalog_baseline.py`
- [Catalog ablation](https://github.com/astrovall02/tess-vet-cnn/blob/main/experiments/catalog_ablation.py): `experiments/catalog_ablation.py`

### Centroid vetting

- [SPOC coverage](https://github.com/astrovall02/tess-vet-cnn/blob/main/centroid/check_spoc_coverage.py): `centroid/check_spoc_coverage.py`
- [Centroid features](https://github.com/astrovall02/tess-vet-cnn/blob/main/centroid/extract_centroid_features.py): `centroid/extract_centroid_features.py`
- [Difference-image checks](https://github.com/astrovall02/tess-vet-cnn/blob/main/centroid/centroid_checks.py): `centroid/centroid_checks.py`

### Other components

- **ExoFOP catalog**
- **MAST / TESS**
- **SPOC light curves**
- **TIC catalog**
- **transit-diffImage**

## Connections

- ExoFOP catalog → Catalog ingestion: provides table (evidence: `src/fetch_data.py`)
- Catalog ingestion → Processed labels: writes labels (evidence: `src/fetch_data.py`)
- MAST / TESS → Light-curve ETL: provides curves (evidence: `README.md`)
- Light-curve ETL → Light-curve arrays: builds arrays (evidence: `README.md`)
- Processed labels → Catalog features: engineers features (evidence: `src/build_aux_features.py`)
- Processed labels → Dataset and splits: loads labels
- Light-curve arrays → Dataset and splits: loads arrays (evidence: `src/data_setup.py`)
- Dataset and splits → Training protocol: feeds batches (evidence: `src/run_protocol.py`)
- Catalog features → Training protocol: supplies features
- Training protocol → Dual-branch CNN: trains and predicts
- Training protocol → Saved probabilities: saves predictions (evidence: `src/run_protocol.py`)
- Saved probabilities → Metrics and predictions: summarizes (evidence: `experiments/make_results.py`)
- Processed labels → Catalog baseline: evaluates features (evidence: `experiments/catalog_baseline.py`)
- Processed labels → Catalog ablation: tests ablations (evidence: `experiments/catalog_ablation.py`)
- Processed labels → SPOC coverage: checks targets (evidence: `centroid/check_spoc_coverage.py`)
- SPOC light curves → SPOC coverage: searches sectors (evidence: `centroid/check_spoc_coverage.py`)
- SPOC light curves → Centroid features: provides centroids (evidence: `centroid/extract_centroid_features.py`)
- TIC catalog → Difference-image checks: provides positions (evidence: `centroid/centroid_checks.py`)
- transit-diffImage → Difference-image checks: supports fits (evidence: `README.md`)
