# khundman/telemanom architecture

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

- Interactive diagram: https://gitdiagram.com/khundman/telemanom
- Repository: https://github.com/khundman/telemanom

## Overview

Telemanom processes spacecraft or other multivariate sensor streams: it shapes train/test channel data, trains or loads an LSTM, predicts telemetry, then thresholds prediction errors into anomalous sequences and writes per-run results. With labels, it also evaluates detections against labeled sequences. A notebook-oriented plotting component supports result review. The main orchestration calls are partly omitted from the excerpts, so uncertain runtime links are dashed; the plotting file directly shows its result and array reads.

Main entry points: [`telemanom/detector.py`](https://github.com/khundman/telemanom/blob/master/telemanom/detector.py) (Run orchestration), [`telemanom/plotting.py`](https://github.com/khundman/telemanom/blob/master/telemanom/plotting.py) (Result plotting), [`telemanom/modeling.py`](https://github.com/khundman/telemanom/blob/master/telemanom/modeling.py) (LSTM modeling), [`telemanom/errors.py`](https://github.com/khundman/telemanom/blob/master/telemanom/errors.py) (Error processing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Inputs and Setup"]
  node_cli["CLI entry<br/>[example.py]"]
  node_config["Run configuration<br/>[helpers.py]"]
  node_channel["Channel shaping<br/>[channel.py]"]
  node_sensor_data[("Train/test arrays")]
  node_labels["Anomaly labels"]
end

subgraph group_predict["Telemetry Prediction"]
  node_model["LSTM modeling<br/>[modeling.py]"]
  node_model_store[("Saved models")]
  node_predictions[("Telemetry predictions")]
end

subgraph group_detect["Anomaly Detection"]
  node_detector["Run orchestration<br/>[detector.py]"]
  node_errors["Error processing<br/>[errors.py]"]
  node_thresholds["Dynamic thresholding<br/>[errors.py]"]
  node_evaluation["Label evaluation<br/>[detector.py]"]
  node_error_data[("Smoothed errors")]
end

subgraph group_review["Results and Review"]
  node_run_results["Run result CSV<br/>[detector.py]"]
  node_plotter["Result plotting<br/>[plotting.py]"]
end

node_operator(("Experiment operator"))
node_notebook_user(("Notebook reviewer"))

node_operator -->|"starts run"| node_cli
node_cli -->|"creates detector"| node_detector
node_detector -->|"loads settings"| node_config
node_sensor_data -.->|"loads arrays"| node_channel
node_detector -.->|"processes channels"| node_channel
node_channel -.->|"provides shaped data"| node_model
node_detector -.->|"runs prediction"| node_model
node_model -->|"loads or saves"| node_model_store
node_model -->|"writes predictions"| node_predictions
node_detector -.->|"processes prediction errors"| node_errors
node_errors -->|"finds thresholds"| node_thresholds
node_errors -->|"writes smoothed errors"| node_error_data
node_labels -.->|"supplies labels"| node_detector
node_detector -->|"evaluates sequences"| node_evaluation
node_evaluation -.->|"adds evaluation"| node_run_results
node_detector -->|"writes run CSV"| node_run_results
node_notebook_user -.->|"reviews results"| node_plotter
node_plotter -->|"reads results"| node_run_results
node_plotter -->|"reads predictions"| node_predictions
node_plotter -->|"reads errors"| node_error_data
node_plotter -->|"reads channel arrays"| node_sensor_data

click node_cli "https://github.com/khundman/telemanom/blob/master/example.py"
click node_config "https://github.com/khundman/telemanom/blob/master/telemanom/helpers.py"
click node_channel "https://github.com/khundman/telemanom/blob/master/telemanom/channel.py"
click node_labels "https://github.com/khundman/telemanom/blob/master/labeled_anomalies.csv"
click node_detector "https://github.com/khundman/telemanom/blob/master/telemanom/detector.py"
click node_model "https://github.com/khundman/telemanom/blob/master/telemanom/modeling.py"
click node_errors "https://github.com/khundman/telemanom/blob/master/telemanom/errors.py"
click node_thresholds "https://github.com/khundman/telemanom/blob/master/telemanom/errors.py"
click node_evaluation "https://github.com/khundman/telemanom/blob/master/telemanom/detector.py"
click node_run_results "https://github.com/khundman/telemanom/blob/master/telemanom/detector.py"
click node_plotter "https://github.com/khundman/telemanom/blob/master/telemanom/plotting.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_cli,node_config,node_channel,node_sensor_data,node_labels,node_notebook_user toneBlue
class node_model,node_model_store,node_predictions toneAmber
class node_detector,node_errors,node_thresholds,node_evaluation,node_error_data toneMint
class node_run_results,node_plotter toneRose
class node_operator toneIndigo
```

## Components

### Inputs and Setup

- [CLI entry](https://github.com/khundman/telemanom/blob/master/example.py): `example.py`
- [Run configuration](https://github.com/khundman/telemanom/blob/master/telemanom/helpers.py): `telemanom/helpers.py`
- [Channel shaping](https://github.com/khundman/telemanom/blob/master/telemanom/channel.py): `telemanom/channel.py`
- **Train/test arrays**
- [Anomaly labels](https://github.com/khundman/telemanom/blob/master/labeled_anomalies.csv): `labeled_anomalies.csv`

### Telemetry Prediction

- [LSTM modeling](https://github.com/khundman/telemanom/blob/master/telemanom/modeling.py): `telemanom/modeling.py`
- **Saved models**
- **Telemetry predictions**

### Anomaly Detection

- [Run orchestration](https://github.com/khundman/telemanom/blob/master/telemanom/detector.py): `telemanom/detector.py`
- [Error processing](https://github.com/khundman/telemanom/blob/master/telemanom/errors.py): `telemanom/errors.py`
- [Dynamic thresholding](https://github.com/khundman/telemanom/blob/master/telemanom/errors.py): `telemanom/errors.py`
- [Label evaluation](https://github.com/khundman/telemanom/blob/master/telemanom/detector.py): `telemanom/detector.py`
- **Smoothed errors**

### Results and Review

- [Run result CSV](https://github.com/khundman/telemanom/blob/master/telemanom/detector.py): `telemanom/detector.py`
- [Result plotting](https://github.com/khundman/telemanom/blob/master/telemanom/plotting.py): `telemanom/plotting.py`

### Other components

- **Experiment operator**
- **Notebook reviewer**

## Connections

- Experiment operator → CLI entry: starts run (evidence: `example.py`)
- CLI entry → Run orchestration: creates detector (evidence: `example.py`)
- Run orchestration → Run configuration: loads settings (evidence: `telemanom/detector.py`)
- Train/test arrays → Channel shaping: loads arrays (evidence: `telemanom/channel.py`)
- Run orchestration → Channel shaping: processes channels (evidence: `telemanom/detector.py`)
- Channel shaping → LSTM modeling: provides shaped data
- Run orchestration → LSTM modeling: runs prediction (evidence: `telemanom/detector.py`)
- LSTM modeling → Saved models: loads or saves (evidence: `telemanom/modeling.py`)
- LSTM modeling → Telemetry predictions: writes predictions (evidence: `telemanom/modeling.py`)
- Run orchestration → Error processing: processes prediction errors (evidence: `telemanom/detector.py`)
- Error processing → Dynamic thresholding: finds thresholds (evidence: `telemanom/errors.py`)
- Error processing → Smoothed errors: writes smoothed errors (evidence: `telemanom/errors.py`)
- Anomaly labels → Run orchestration: supplies labels (evidence: `README.md`)
- Run orchestration → Label evaluation: evaluates sequences (evidence: `telemanom/detector.py`)
- Label evaluation → Run result CSV: adds evaluation (evidence: `telemanom/detector.py`)
- Run orchestration → Run result CSV: writes run CSV (evidence: `telemanom/detector.py`)
- Notebook reviewer → Result plotting: reviews results (evidence: `README.md`)
- Result plotting → Run result CSV: reads results (evidence: `telemanom/plotting.py`)
- Result plotting → Telemetry predictions: reads predictions (evidence: `telemanom/plotting.py`)
- Result plotting → Smoothed errors: reads errors (evidence: `telemanom/plotting.py`)
- Result plotting → Train/test arrays: reads channel arrays (evidence: `telemanom/plotting.py`)