DOCSEARCHbyAlgolia
Submit Docs

PyOD (Python Outlier Detection)

repository·master·Indexed 27 days ago

https://github.com/yzhao062/pyod

A comprehensive Python library for anomaly detection across tabular, time series, graph, text, image, and audio data. It features 61 detectors, the ADEngine for benchmark-backed algorithm routing, and agentic capabilities for LLMs via MCP tools. PyOD provides a consistent BaseDetector API (fit, predict, decision_function) and supports scalable ensembles through the SUOD framework.

Tokens
70.6K
Snippets
114
Records
405
Agent score
93%

What's inside pyod

  1. Overview of Time-Series Anomaly Detection (TS-AD) Models in PyOD

    master

    PyOD is implementing a suite of 7 time-series anomaly detection algorithms as first-class BaseDetector subclasses. These models are categorized into classical methods (using numpy/scipy) and deep learning methods (using PyTorch).

    Planned Models

    ModelTypeDescription
    MatrixProfileClassicalSTOMP algorithm
    SpectralResidualClassicalFFT saliency
    KShapeClassicalExperimental k-Shape clustering
    SANDClassicalExperimental streaming detection
    LSTMADDeepLSTM prediction error + Mahalanobis
    AnomalyTransformerDeepAttention discrepancy
    TimeSeriesODBridgeWindowed bridge for TS models

    Technical Requirements

    • Python Version: 3.8+
    • Dependencies: numpy, scipy, and optionally torch (for LSTMAD and AnomalyTransformer).

  2. Overview of Graph Anomaly Detection models in PyOD

    master

    PyOD implements several graph anomaly detectors as BaseDetector subclasses. These models are designed to work with PyTorch Geometric (PyG) Data objects.

    Note: In the current implementation (v1), these detectors are transductive, meaning they support fit only and do not support out-of-sample scoring.

    The models are categorized into three types:

    1. Classical Matrix/Clustering:

      • pyg_scan.py (SCAN structural clustering)
      • pyg_radar.py (Radar matrix factorization)
      • pyg_anomalous.py (ANOMALOUS joint MF)

    2. GCN-based Autoencoders:

      • pyg_dominant.py (DOMINANT GCN autoencoder)
      • pyg_anomalydae.py (AnomalyDAE dual autoencoder)
      • pyg_guide.py (GUIDE motif-based dual autoencoder)

    3. Contrastive Learning:

      • pyg_cola.py (CoLA contrastive)
      • pyg_conad.py (CONAD contrastive+reconstruction)

  3. Overview of Time Series Anomaly Detection Algorithms

    master

    PyOD provides several time series anomaly detection algorithms categorized by their multivariate handling behavior:

    Native Multivariate

    These algorithms process all channels jointly:

    • TimeSeriesOD: A windowed bridge that applies any PyOD detector to sliding windows.
    • LSTMAD: A deep learning approach using LSTM prediction error and Mahalanobis distance.
    • AnomalyTransformer: A deep learning approach using attention discrepancy and reconstruction error.

    Per-Channel Aggregate

    These algorithms run independently per channel and then aggregate the scores. Per-channel scores are z-normalized before aggregation to prevent high-variance channels from dominating. Aggregation is controlled by the channel_aggregation parameter ('max' or 'mean', default 'max').

    • MatrixProfile: Uses subsequence distance (STOMP algorithm).
    • SpectralResidual: Uses frequency domain saliency computation.
    • KShape (Experimental): Uses shape-based clustering.
    • SAND (Experimental): A simplified streaming/online version of k-Shape-based detection.

  4. Overview of PyOD usage layers

    master

    PyOD provides three distinct layers of interaction depending on your needs:

    1. Classic API: Use this when you know exactly which detector you want to apply. Entry point: standard detector imports.
    2. ADEngine: Use this when you want PyOD to automatically choose, compare, and assess detectors. Entry point: from pyod.utils.ad_engine import ADEngine.
    3. Agentic Investigation: Use this to drive anomaly detection through natural language conversation using an AI agent. Entry point: od-expert skill for Claude/Codex or MCP tools for other agents.

  5. Overview of EmbeddingOD

    master

    EmbeddingOD is a wrapper designed to add text and image anomaly detection to PyOD. It works by chaining an embedding encoder (such as sentence-transformers, OpenAI, HuggingFace, or a custom callable) with an existing PyOD detector.

    It follows the standard PyOD API by inheriting from BaseDetector. The workflow involves:

    1. Encoding raw data (text/images) into numpy embeddings using a BaseEncoder.
    2. Preprocessing the embeddings (e.g., using StandardScaler or optional PCA).
    3. Delegating the anomaly detection task to a standard PyOD detector.

  6. Understand the od-expert skill architecture

    master

    The od-expert skill in PyOD 3.2.0 is designed for agentic workers (like Claude Code or MCP-compatible LLMs) to autonomously drive the ADEngine. It uses a hybrid architecture of hand-written expert distillation and KB-derived (Knowledge Base) data.

    Core Components:

    • SKILL.md (Always Loaded): Contains activation rules, a master decision tree (mapping data shape to modality and detectors), top-10 critical pitfalls, and adaptive escalation triggers.
    • references/ (On-Demand): Specialized markdown files loaded based on the detected data modality:
      • workflow.md: Autonomous loop patterns and result interpretation.
      • pitfalls.md: Detailed library of 20+ pitfalls.
      • tabular.md: Decision tables and detectors for tabular data.
      • time_series.md: Context for TSB-AD benchmarks and TimeSeriesOD.
      • graph.md: Coverage for DOMINANT, CoLA, CONAD, and AnomalyDAE.
      • text_image.md: Guidance for EmbeddingOD and transformer-based detectors.

    Key Feature: Every recommendation made by the skill is designed to map directly to an ADEngine-callable method.

  7. Graph Anomaly Detection Algorithms Overview

    master

    PyOD provides several graph-based anomaly detection algorithms. Note that all algorithms in this version are transductive.

    Deep Learning Based (GNN-based)

    These require pyod[graph] and use Graph Neural Network layers:

    • DOMINANT: GCN autoencoder reconstructing adjacency and attributes.
    • CoLA: Contrastive self-supervised learning using subgraph patches.
    • CONAD: Combines contrastive learning with graph augmentation and reconstruction.
    • AnomalyDAE: Dual autoencoder using attention (GATConv) and MLP.
    • GUIDE: Exploits higher-order structures (motifs) via dual GCN autoencoders.

    Classical/Matrix-based (No GNN required)

    These use numpy/scipy operations on graph data:

    • Radar: Matrix factorization approach (X = AW + R).
    • ANOMALOUS: Joint CUR decomposition for structural and attribute anomalies.
    • SCAN: Structural clustering based on shared neighbor density.

  8. Available Graph Anomaly Detectors

    master

    PyOD provides 8 graph anomaly detectors built on PyTorch Geometric. Note that in version 1, all these detectors are transductive. The available modules are:

    • pyod.models.pyg_scan
    • pyod.models.pyg_radar
    • pyod.models.pyg_anomalous
    • pyod.models.pyg_dominant
    • pyod.models.pyg_anomalydae
    • pyod.models.pyg_cola
    • pyod.models.pyg_conad
    • pyod.models.pyg_guide

  9. Understand the PyOD V3 Three-Layer Architecture

    master

    PyOD V3 is organized into three independent layers, allowing developers to choose the level of automation they need:

    1. Layer 1: BaseDetector models: The standard direct Python API. Use this for traditional fit/predict workflows. It remains unchanged.
    2. Layer 2: ADEngine: The intelligent orchestration layer. Use this for agentic workflows where you want the engine to handle algorithm selection and orchestration.
    3. Layer 3: Skill (od-expert): The agent conversation layer. This is designed for AI agents (like Claude) to follow a conversational workflow by calling ADEngine.

    Each layer can be used independently.

  10. Understand PyOD's benchmark-driven detector routing

    master

    PyOD uses the pyod.utils.ad_engine.ADEngine class to route users to recommended anomaly detection algorithms. These recommendations are directly tied to findings from three peer-reviewed benchmark suites, ensuring that suggestions for Layer 2 and Layer 3 of the engine are based on reproducible evidence.

    Supported benchmark domains include:

    • Tabular Data: Guided by ADBench.
    • Time Series: Guided by TSB-AD.
    • Graph Data: Guided by BOND.
    • Text Data: Guided by NLP-ADBench.

  11. Explore PyOD Time Series Detectors

    master

    PyOD provides 7 dedicated modules for time series anomaly detection. These models are ranked by the TSB-AD benchmark (NeurIPS 2024).

    Available modules include:

    • pyod.models.ts_od
    • pyod.models.ts_matrix_profile
    • pyod.models.ts_spectral_residual
    • pyod.models.ts_kshape
    • pyod.models.ts_sand
    • pyod.models.ts_lstm
    • pyod.models.ts_anomaly_transformer

  12. Tabular and Multi-Modal Detection Algorithms

    master

    PyOD provides a wide range of algorithms for tabular and multi-modal data. These are categorized by their underlying mathematical approach:

    • Probabilistic: Includes ECOD, COPOD, ABOD, MAD, GMM, and KDE.
    • Linear Model: Includes PCA, KPCA, MCD, CD, OCSVM, and LMDD.
    • Proximity-Based: Includes LOF, COF, CBLOF, LOCI, HBOS, HDBSCAN, and kNN variants.
    • Outlier Ensembles: Includes IForest, INNE, DIF, FeatureBagging, LSCP, XGBOD, LODA, and SUOD.
    • Neural Networks: Includes AutoEncoder, VAE, DeepSVDD, AnoGAN, ALAD, and DevNet.
    • Graph-based: Includes RGraph and LUNAR.
    • Embedding-based: EmbeddingOD supports multi-modal anomaly detection (text, image, audio) via foundation model embeddings.