telemetry-anomdet 0.3.0

telemetry-anomdet

telemetry-anomdet is an open-source anomaly detection toolkit for spacecraft telemetry. It runs classical and graph-based deep detectors behind one interface, selects alarm thresholds without labels, points each alarm at the channels that raised it, and distills a trained detector down to Power of Ten conformant C that runs on flight hardware. SHAP attribution and LLM-generated diagnostic reports are on the roadmap.

Benchmarked on SMAP and MSL (NASA) and ESA-ADB (ESA).

Quick Install

# recommended
uv add telemetry-anomdet

# or with pip
pip install telemetry-anomdet

The base install is torch-free. The deep detectors (GDN, KANGDN) need the deep extra:

uv add "telemetry-anomdet[deep]"

Plotting, including the learned sensor graph, needs the viz extra.

Example Usage

Fit the Ensemble on Nominal Telemetry

All detectors are trained on nominal data only, no anomaly labels used during training. Labels are used exclusively for evaluation.

import numpy as np
from telemetry_anomdet.models.unsupervised.pca import PCAAnomaly
from telemetry_anomdet.models.unsupervised.kmeans import KMeansAnomaly
from telemetry_anomdet.models.ensemble import AnomalyEnsemble

# X_train: (n_windows, window_size, n_features), produced by windowify()
X_train = ...

ensemble = AnomalyEnsemble(
    models = {
        "pca":    PCAAnomaly(n_components = 10),
        "kmeans": KMeansAnomaly(n_clusters = 5, scale = True),
    },
    combine = "mean",
    normalize = "robust",
    percentile = 95.0,
)

ensemble.fit(X_train)

Inference and Anomaly Flags

scores = ensemble.decision_function(X_test)   # higher = more anomalous
flags  = ensemble.is_anomaly(X_test)          # boolean mask at training threshold

# Runtime sensitivity override, no retraining needed
flags_strict = ensemble.is_anomaly(X_test, percentile = 98.0)
flags_custom  = ensemble.is_anomaly(X_test, threshold = 0.75)

Per-Model Score Decomposition

score_components() returns raw per-model scores before normalization or combination. This is the SHAP hook: perturb input channels, measure how each sensor drives each model's score independently.

components = ensemble.score_components(X_test)
# {"pca": array(100,), "kmeans": array(100,)}

Getting the SMAP dataset

The benchmarks and examples need a local copy of the NASA SMAP/MSL data, which is not redistributed with the toolkit. From the root of the repo:

pip install kaggle

# Requires a Kaggle API key in ~/.kaggle/kaggle.json
kaggle datasets download -d patrickfleith/nasa-anomaly-detection-dataset-smap-msl \
  && mv nasa-anomaly-detection-dataset-smap-msl.zip data.zip \
  && unzip -o data.zip \
  && rm data.zip \
  && mv data/data tmp && rm -r data && mv tmp data

That leaves data/train/, data/test/ and labeled_anomalies.csv. Point the examples at it:

export TAD_SMAP_DIR=data          # Windows: $env:TAD_SMAP_DIR = "data"
python examples/smap_demo.py
python examples/smap_benchmark.py

Datasets are never committed; data/ is gitignored.

Coming in Phase 3+

# Per-channel SHAP attribution (Phase 3)
# shap_values = explainer.explain(ensemble, X_anomalous)
# {"sensor_01": 0.42, "sensor_02": 0.18, ...}

# LLM diagnostic report (Phase 4)
# report = llm_engine.explain(shap_values, context, channel_names)
# DiagnosticReport(
#     anomaly_type = "power subsystem fault",
#     severity = "high",
#     primary_channels = ["sensor_01", "sensor_07"],
#     explanation = "...",
#     recommended_action = "...",
#     confidence = 0.87,
# )

Features

Available now

• One interface for every detector. Classical and deep detectors share the same fit / decision_function / predict / is_anomaly API, so stacking or swapping models needs no per-model glue.
• Graph deviation detectors. GDN and KANGDN forecast each channel from its learned top-k neighbours and score the deviation, catching readings that are individually plausible but wrong in relation to each other. feat_mode selects how KANGDN encodes each channel's history (linear, kan, ar_kan, ar_kan_residual).
• Which sensor, not just when. channel_deviations and dominant_channels attribute each alarm to the channels driving it, and plot_sensor_graph draws the graph the detector learned.
• Alarms without labels. threshold_for_budget and dynamic_threshold pick an operating point from the score distribution alone. Operations can state an alarm rate; they cannot state a recall they have no way to observe.
• Honest evaluation. Event-level scoring alongside the conventional point-adjusted F1, plus a random baseline row in the benchmark. ESA-ADB is scored by its own protocol, with F0.5 as the headline metric.
• Runs on flight hardware. A fitted KANGDN distills to a torch-free NumPy evaluator, then to Power of Ten conformant C with golden vectors, for every feat_mode. Host and ESP32-S3 targets are in targets/.
• Stacking ensemble with robust (median + IQR) score normalization, built for anomaly scores that are extreme by definition.
• Per-model score decomposition via score_components(), the hook that enables per-channel attribution without retraining.
• Spacecraft-native ingestion. SMAP, MSL, ESA-ADB and CSV load straight into a long-form TelemetryDataset, no schema wrangling. The ESA-ADB loader reads the official archive directly, with no preprocessing step; its payloads are pickled, so load only that archive, never untrusted files.
• Runtime sensitivity control. is_anomaly() accepts a percentile or threshold override, so operators re-tune without retraining.

On the roadmap

• TranAD: transformer-based sequence reconstruction
• SHAPExplainer: per-channel attribution over score_components() (Phase 3)
• LLM diagnostic reports, SHAP chart supplied as an image (Phase 4)
• Human-in-the-loop threshold feedback (Phase 5)

AI Transparency

AI assistants are used while writing and maintaining this project's documentation.

What that does not change:

• Numbers come from runs. Benchmark figures are produced by examples/smap_benchmark.py and examples/esa_benchmark.py, and the hardware results in the deployment docs are measured on an ESP32-S3 by the conformance harness in targets/. Nothing quoted in these docs is estimated or inferred.
• Behavior claims are backed by tests. The suite gates CI, and the documented API is covered by it.

Everything published here is reviewed before it lands.

Getting Help

Discussions

To suggest improvements, or ask for help, please see GitHub Discussions

Bug reports

To submit a report on any bugs or issues, open an issue here