---

name: "anomaly-detection" description: "Guides PyPOTS anomaly-detection workflows, including detector inputs, anomaly-rate configuration, output keys, binary metrics, and backend/data pitfalls." disable-model-invocation: true metadata: disco-role: operating license: BSD 3-Clause

PyPOTS Anomaly Detection

Use this sub-skill when the user wants PyPOTS to detect anomalous timesteps or samples in partially-observed time series.

Natural Triggers

• "detect anomalies with PyPOTS"
• "use TimesNet / TEFN / TimeMixer / Transformer for anomaly detection"
• "what does anomaly_rate do?"
• "read predict()[\"anomaly_detection\"]"
• "compute accuracy, precision, recall, or F1 for anomaly labels"
• "why are anomaly labels named anomaly_y in tests?"

First References

• Read ../../references/data-formats.md#anomaly-detection for X, anomaly_y, and CLI label caveats.
• Read ../../references/api-reference.md for detector helpers and result keys.
• Read ../../references/model-overview.md#anomaly-detection for model-family choice.
• Read ../../references/troubleshooting.md for data, CUDA, checkpoint, and result-key failures.
• Use ../cli/ for CLI-driven train/predict/evaluate flows.

Scope

This route covers:

• Detector models such as TimesNet, TEFN, TimeMixer, Transformer, FiLM, SegRNN, ImputeFormer, PatchTST, DLinear, SAITS, iTransformer, Crossformer, Pyraformer, FEDformer, Informer, ETSformer, NonstationaryTransformer, and TimeMixerPP.
• Constructor-time anomaly_rate handling.
• Result extraction through predict()["anomaly_detection"] or detect().
• Binary classification-style metrics for anomaly labels.
• In-memory dict and HDF5 lazy-loading inputs.

Route elsewhere:

• Missing-value imputation without anomaly labels -> ../imputation/.
• Future-value forecasting -> ../forecasting/.
• Sample classification labels -> ../classification/.
• Embeddings for later detectors -> ../representation/.

Core Workflow

1. Prepare X with shape [n_samples, n_steps, n_features].
2. Choose an anomaly_rate in (0, 1) that matches expected anomaly density.
3. Instantiate the detector with n_steps, n_features, anomaly_rate, and model-specific architecture fields.
4. Train with fit(train_set, val_set) where train/validation dicts contain at least X; native fixtures also keep anomaly_y for metric checks.
5. Predict with predict(test_set) and read results["anomaly_detection"], or call detect(test_set).
6. Evaluate with calc_acc and calc_precision_recall_f1 when ground-truth anomaly labels are available.

Minimal Example Shape

from pypots.anomaly_detection import TimesNet

model = TimesNet(
    n_steps=n_steps,
    n_features=n_features,
    anomaly_rate=0.05,
    n_layers=1,
    top_k=1,
    d_model=16,
    d_ffn=16,
    n_kernels=3,
    epochs=1,
    device="cpu",
)
model.fit({"X": train_X}, {"X": val_X})
anomalies = model.detect({"X": test_X})

If using native test-style labels, keep:

test_anomaly_y = dataset["test_anomaly_y"].flatten()

Then compare model outputs to those labels with the metric helpers.

Common Decision Points

• Use a tiny CPU fixture before a large detector run.
• Verify 0 < anomaly_rate < 1; the base detector asserts this range.
• Do not reuse a forecasting or imputation config for anomaly detection without checking task-specific constructor parameters.
• Make sure the evaluation label key matches the code path. Native tests use anomaly_y; CLI evaluation currently checks binary targets through y.
• If the model emits scores instead of hard labels, confirm the metric helper's expected input before interpreting the result.

Validation Signals

A successful anomaly workflow returns anomaly_detection and can compute finite accuracy/precision/recall/F1 values against the chosen binary label array.