PyOD

https://github.com/yzhao062/pyod
Admin
A Python Library for Outlier and Anomaly Detection, Integrating Classical and Deep Learning...
Tokens:509,296
Snippets:3,061
Trust Score:9.3
License:BSD-2-Clause
Update:1 month ago
Show doc for...
Tokens:
Raw
### GUIDE Usage Example

Source: https://github.com/yzhao062/pyod/blob/master/docs/superpowers/plans/2026-04-11-graph-od-implementation.md

Example script demonstrating how to use the GUIDE detector for graph anomaly detection.

```python
# -*- coding: utf-8 -*-
"""Example of using GUIDE for graph anomaly detection.

GUIDE uses dual GCN autoencoders on original and motif
(triangle) adjacency. Transductive.

Requires: pip install pyod[graph]
"""
# Author: Yue Zhao <yzhao062@gmail.com>
# License: BSD 2 clause

from __future__ import division
from __future__ import print_function

import os
import sys

sys.path.append(
    os.path.abspath(os.path.join(os.path.dirname("__file__"), '..')))

import numpy as np
import torch
from torch_geometric.data import Data
from pyod.models.pyg_guide import GUIDE
from pyod.utils.data import generate_graph_data

if __name__ == "__main__":
    contamination = 0.1

    X, edge_index, y = generate_graph_data(
        n_nodes=300, contamination=contamination, random_state=42)

    data = Data(x=torch.FloatTensor(X),
                edge_index=torch.LongTensor(edge_index))

    clf_name = 'GUIDE'
    clf = GUIDE(hidden_dim=32, epochs=50,
                contamination=contamination)
    clf.fit(data)

    print("Detector: %s" % clf_name)
    print("Number of anomalies: %d" % clf.labels_.sum())
    print("Top 5 anomaly scores:", np.sort(clf.decision_scores_)[-5:])
```

--------------------------------

### Configure MCP Server

Source: https://github.com/yzhao062/pyod/blob/master/docs/install.rst

Install the mcp extra and start the MCP server.

```bash
pip install pyod[mcp]
pyod mcp serve              # alias for ``python -m pyod.mcp_server``
```

--------------------------------

### Run GUIDE Tests

Source: https://github.com/yzhao062/pyod/blob/master/docs/superpowers/plans/2026-04-11-graph-od-implementation.md

Command to execute the test suite for the GUIDE implementation.

```bash
python -m pytest pyod/test/test_pyg_guide.py -v
```

--------------------------------

### Example PyOD info output

Source: https://github.com/yzhao062/pyod/blob/master/docs/install.rst

Sample output showing version information, detector counts, and the installation status of various components.

```text
PyOD version:          3.1.0
Detectors (ADEngine):  61 total (43 tabular, 7 time-series, 8 graph, 2 text, 2 image, 1 multimodal, 3 audio)
Classic API:           OK
ADEngine (Layer 2):    OK
MCP extra:             OK (run: pyod mcp serve)
od-expert skill:       INSTALLED (user-global) at /Users/you/.claude/skills/od-expert/SKILL.md
```

--------------------------------

### GUIDE Implementation Stub

Source: https://github.com/yzhao062/pyod/blob/master/docs/superpowers/plans/2026-04-11-graph-od-implementation.md

Initial stub for the GUIDE model implementation file.

```python
# -*- coding: utf-8 -*-
"""GUIDE: Higher-order Structure Based Anomaly Detection.

```

--------------------------------

### Install PyOD from Source

Source: https://github.com/yzhao062/pyod/blob/master/docs/install.rst

Steps to clone the repository and install from the local source directory.

```bash
git clone https://github.com/yzhao062/pyod.git
cd pyod
pip install .
```

--------------------------------

### Install PyOD for MCP-compatible LLMs

Source: https://github.com/yzhao062/pyod/blob/master/docs/index.rst

Install the optional mcp extra and start the MCP server.

```bash
# 2. Any MCP-compatible LLM — requires the optional mcp extra
pip install pyod[mcp]
pyod mcp serve                 # alias for `python -m pyod.mcp_server`
```

--------------------------------

### Commit GUIDE Implementation

Source: https://github.com/yzhao062/pyod/blob/master/docs/superpowers/plans/2026-04-11-graph-od-implementation.md

Git command to stage and commit the new GUIDE implementation files.

```bash
git add pyod/models/pyg_guide.py pyod/test/test_pyg_guide.py examples/pyg_guide_example.py
git commit -m "feat: add GUIDE graph anomaly detector"
```

--------------------------------

### Install PyOD and skills

Source: https://github.com/yzhao062/pyod/blob/master/examples/agentic_demo.html

Command to install the PyOD library and the additional skill set.

```bash
pip install pyod && pyod install skill
```

--------------------------------

### LOCI Model Initialization and Fitting

Source: https://github.com/yzhao062/pyod/blob/master/docs/pyod.models.tabular.rst

Example showing how to import the LOCI model, generate synthetic data, and fit the model to the training set.

```pycon
>>> from pyod.models.loci import LOCI
>>> from pyod.utils.data import generate_data
>>> n_train = 50
>>> n_test = 50
>>> contamination = 0.1
>>> X_train, y_train, X_test, y_test = generate_data(
...     n_train=n_train, n_test=n_test,
...     contamination=contamination, random_state=42)
>>> clf = LOCI()
>>> clf.fit(X_train)
LOCI(alpha=0.5, contamination=0.1, k=None)
```

--------------------------------

### SOS Model Basic Usage

Source: https://github.com/yzhao062/pyod/blob/master/docs/pyod.models.tabular.rst

Example demonstrating how to initialize the SOS detector, generate synthetic data, and fit the model.

```pycon
>>> from pyod.models.sos import SOS
>>> from pyod.utils.data import generate_data
>>> n_train = 50
>>> n_test = 50
>>> contamination = 0.1
>>> X_train, y_train, X_test, y_test = generate_data(
...     n_train=n_train, n_test=n_test,
...     contamination=contamination, random_state=42)
>>>
>>> clf = SOS()
>>> clf.fit(X_train)
SOS(contamination=0.1, eps=1e-05, metric='euclidean', perplexity=4.5)
```

--------------------------------

### GUIDE.__init__

Source: https://github.com/yzhao062/pyod/blob/master/docs/superpowers/plans/2026-04-11-graph-od-implementation.md

Initializes the GUIDE anomaly detector with specified hyperparameters.

```APIDOC
## GUIDE(hidden_dim=64, num_layers=2, alpha=0.5, dropout=0.3, epochs=100, lr=5e-3, contamination=0.1)

### Description
Initializes the GUIDE model. This detector uses two GCN autoencoders in parallel to reconstruct the original graph and a motif (triangle) graph.

### Parameters
- **hidden_dim** (int) - Optional - Hidden dimension of GCN layers. Default: 64.
- **num_layers** (int) - Optional - Number of GCN encoder layers. Default: 2.
- **alpha** (float) - Optional - Weight for original-graph reconstruction error. Default: 0.5.
- **dropout** (float) - Optional - Dropout rate. Default: 0.3.
- **epochs** (int) - Optional - Training epochs. Default: 100.
- **lr** (float) - Optional - Learning rate. Default: 5e-3.
- **contamination** (float) - Optional - Expected proportion of anomalies. Default: 0.1.
```

--------------------------------

### Implement start() and plan() methods in ADEngine

Source: https://github.com/yzhao062/pyod/blob/master/docs/superpowers/plans/2026-04-12-v3-agentic-implementation.md

The start() method initializes an investigation session by profiling data, while plan() selects top-N detectors based on priority and constraints.

```python
    def start(self, X, data_type=None):
        """Start an investigation session.

        Profiles the data and returns an InvestigationState.

        Parameters
        ----------
        X : array-like, Data, list, or dict
            Input data (any modality).
        data_type : str or None
            Explicit type override.

        Returns
        -------
        state : InvestigationState
        """
        from .investigation import InvestigationState, _make_history_entry

        profile = self.profile_data(X, data_type=data_type)
        state = InvestigationState(
            phase='profiled',
            data=X,
            profile=profile,
            next_action={
                'action': 'plan',
                'reason': 'Data profiled as %s with %d samples. '
                          'Ready to select detectors.'
                          % (profile['data_type'],
                             profile.get('n_samples', 0)),
            },
        )
        state.history.append(_make_history_entry(
            'profiled', 'start', 0,
            'Profiled %s data' % profile['data_type']))
        return state

    def plan(self, state, priority='balanced', constraints=None):
        """Plan detection: select top-N detectors.

        Wraps ``plan_detection()`` and extracts primary + alternatives
        into ``state.plans`` (up to 3 detectors, v1 limit).

        Parameters
        ----------
        state : InvestigationState
        priority : str
        constraints : dict or None

        Returns
        -------
        state : InvestigationState
        """
        from .investigation import _make_history_entry

        constraints = constraints or {}
        result = self.plan_detection(
            state.profile, priority=priority, constraints=constraints)

        # Extract primary + alternatives into flat list
        plans = []
        if result.get('detector_name'):
            plans.append(result)
        for alt in result.get('alternatives', []):
            if alt.get('detector_name'):
                plans.append(alt)

        # Honor max_detectors (v1 cap at 3)
        max_det = max(1, min(
            int(constraints.get('max_detectors', 3)), 3))
        state.plans = plans[:max_det]
        state.phase = 'planned'
        names = [p['detector_name'] for p in state.plans]
        state.next_action = {
            'action': 'run',
            'reason': 'Top %d detectors selected: %s. Ready to run.'
                      % (len(state.plans), ', '.join(names)),
        }
        state.history.append(_make_history_entry(
            'planned', 'plan', state.iteration,
            'Selected %d detectors: %s' % (len(plans), ', '.join(names))))
        return state
```

--------------------------------

### Initialize ADEngine and Profile Data

Source: https://github.com/yzhao062/pyod/blob/master/pyod/skills/od_expert/references/workflow.md

Set up the environment, load the dataset, and initialize the ADEngine to profile the data structure.

```python
import numpy as np
import pandas as pd
from pyod.utils.ad_engine import ADEngine

np.random.seed(42)  # reproducible across the reference numbers below
df = pd.read_csv("examples/data/cardio.csv")
X = df.values[:, :-1]  # exclude the trailing label column; use it only for offline validation
engine = ADEngine()
state = engine.start(X)
```

--------------------------------

### Configure sys.path for local repository execution

Source: https://github.com/yzhao062/pyod/blob/master/examples/README.md

Temporary solution to resolve relative imports when running examples from the downloaded repository without installing PyOD via pip.

```python
import sys
sys.path.append("..")
```

--------------------------------

### Graph Anomaly Detection with DOMINANT

Source: https://github.com/yzhao062/pyod/blob/master/docs/index.rst

A three-line example for performing graph anomaly detection using the DOMINANT model. Requires the pyod[graph] installation and a PyG Data object as input.

```python
from pyod.models.pyg_dominant import DOMINANT
clf = DOMINANT(hidden_dim=64, epochs=100)
clf.fit(data)                                  # PyG Data object
scores = clf.decision_scores_                  # per-node anomaly scores
```

--------------------------------

### Install and verify PyOD from TestPyPI

Source: https://github.com/yzhao062/pyod/blob/master/docs/superpowers/plans/2026-04-13-v3.2-od-expert-deep-skill.md

Commands to install the package from TestPyPI and verify the installation using the pyod CLI.

```bash
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ pyod==3.2.0
pyod info
pyod install skill --target <SCRATCH>
```

--------------------------------

### PyOD Installation and Verification Commands

Source: https://github.com/yzhao062/pyod/blob/master/docs/superpowers/plans/2026-04-13-v3.1-skill-install-ux.md

Commands to upgrade PyOD, install the od-expert skill for Claude Code, and verify the installation status.

```bash
pip install --upgrade pyod
pyod install skill      # Claude Code: enable the od-expert skill
pyod info               # verify everything is wired up
```

--------------------------------

### Examine existing install function logic

Source: https://github.com/yzhao062/pyod/blob/master/docs/superpowers/plans/2026-04-13-v3.2-od-expert-deep-skill.md

The current implementation copies only the SKILL.md file using shutil.copy2.

```python
source_file = source_dir / "SKILL.md"
...
dest_file = dest_dir / "SKILL.md"
shutil.copy2(source_file, dest_file)
return dest_file
```

--------------------------------

### Install PyOD skills for Claude Code or Codex

Source: https://github.com/yzhao062/pyod/blob/master/docs/examples/agentic.rst

Install the pyod package and use the CLI to install the od-expert skill globally for Claude Code or locally for Codex.

```bash
pip install pyod

# Claude Code: user-global install
pyod install skill              # installs to ~/.claude/skills/od-expert/

# Codex: project-local install (Codex reads ./skills/, has no user-global dir)
pyod install skill --project    # installs to ./skills/od-expert/
```

--------------------------------

### GUIDE(hidden_dim=64, num_layers=2, alpha=0.5, dropout=0.3, epochs=100, lr=0.005, contamination=0.1)

Source: https://github.com/yzhao062/pyod/blob/master/docs/pyod.models.graph.rst

Constructor for the GUIDE anomaly detection model.

```APIDOC
### Constructor

#### Parameters
- **hidden_dim** (int, default=64) - Hidden dimension of GCN layers.
- **num_layers** (int, default=2) - Number of GCN encoder layers.
- **alpha** (float, default=0.5) - Weight for original-graph reconstruction error.
- **dropout** (float, default=0.3) - Dropout rate.
- **epochs** (int, default=100) - Training epochs.
- **lr** (float, default=5e-3) - Learning rate.
- **contamination** (float, default=0.1) - Expected proportion of anomalies.
```

--------------------------------

### Inspect installer code with grep

Source: https://github.com/yzhao062/pyod/blob/master/docs/superpowers/plans/2026-04-13-v3.2-od-expert-deep-skill.md

Use grep to locate the install function and shutil usage within the skills initialization file.

```bash
grep -n "shutil\|install\b" pyod/skills/__init__.py | head -20
```

--------------------------------

### Implement ADEngine usage example

Source: https://github.com/yzhao062/pyod/blob/master/docs/superpowers/plans/2026-04-07-ad-engine-tier-a.md

A complete example demonstrating one-shot detection, the step-by-step lifecycle, and knowledge queries using ADEngine.

```python
# examples/ad_engine_example.py
"""ADEngine: Intelligent anomaly detection in 3 lines.

Demonstrates PyOD's ADEngine for automatic detector selection
and anomaly detection across data types.
"""
from pyod.utils.ad_engine import ADEngine
from pyod.utils.data import generate_data

# Generate sample data
X_train, X_test, y_train, y_test = generate_data(
    n_train=300, n_test=100, n_features=20, contamination=0.1)

# Initialize the engine
engine = ADEngine()

# === One-shot detection ===
result = engine.detect(X_train)
print("Detector chosen:", result['plan']['detector_name'])
print("Reason:", result['plan']['reason'])
print("Anomalies found:", result['n_anomalies'])
print()

# === Step-by-step lifecycle ===
# 1. Profile the data
profile = engine.profile_data(X_train)
print("Data profile:", profile)

# 2. Plan detection
plan = engine.plan_detection(profile, priority='speed')
print("Plan:", plan['detector_name'], "-", plan['reason'])

# 3. Build detector
clf = engine.build_detector(plan)
print("Detector:", clf)

# 4. Fit and predict
clf.fit(X_train)
print("Training anomalies:", clf.labels_.sum())
print("Test scores:", clf.decision_function(X_test)[:5])
print()

# === Knowledge queries ===
print("=== Available text detectors ===")
for d in engine.list_detectors(data_type='text'):
    print(f"  {d['name']}: {d['full_name']}")

print()
print("=== ECOD explained ===")
info = engine.explain_detector('ECOD')
print(f"  {info['full_name']}")
print(f"  Best for: {info['best_for']}")
print(f"  Strengths: {', '.join(info['strengths'][:3])}")

print()
print("=== ADBench results ===")
bench = engine.get_benchmarks('ADBench')
print(f"  Top 5: {bench['ADBench']['rankings']['overall_top_5']}")
```

--------------------------------

### EmbeddingOD installation commands

Source: https://github.com/yzhao062/pyod/blob/master/pyod/skills/od_expert/references/text_image.md

Installation commands for the different encoder backends supported by EmbeddingOD.

```bash
pip install pyod[embedding]
pip install pyod[openai]
pip install pyod[huggingface]
```

--------------------------------

### ADEngine.__init__

Source: https://github.com/yzhao062/pyod/blob/master/docs/superpowers/plans/2026-04-07-ad-engine-tier-a.md

Initializes the ADEngine instance with an optional path to a knowledge base.

```APIDOC
## ADEngine(knowledge_dir=None)

### Description
Initializes the anomaly detection lifecycle engine.

### Parameters
- **knowledge_dir** (str or None) - Optional - Path to knowledge base directory. If None, uses bundled.
```

--------------------------------

### Install PyOD via Conda

Source: https://github.com/yzhao062/pyod/blob/master/docs/install.rst

Installation command for users using the conda-forge channel.

```bash
conda install -c conda-forge pyod
```

--------------------------------

### Install sentence-transformers dependency

Source: https://github.com/yzhao062/pyod/blob/master/docs/examples/embedding.rst

Install the optional dependency required for text embedding functionality.

```bash
pip install sentence-transformers
```

--------------------------------

### Initialize and fit the SAND model

Source: https://github.com/yzhao062/pyod/blob/master/docs/pyod.models.timeseries.rst

Demonstrates how to import the SAND class, generate synthetic training data, initialize the model with specific parameters, and fit it to the data.

```pycon
>>> from pyod.models.ts_sand import SAND
>>> import numpy as np
>>> X_train = np.random.randn(500)
>>> clf = SAND(n_clusters=3, window_size=20, contamination=0.1)
>>> clf.fit(X_train)
>>> scores = clf.decision_function(np.random.randn(200))
```

--------------------------------

### SCAN usage example

Source: https://github.com/yzhao062/pyod/blob/master/docs/superpowers/plans/2026-04-11-graph-od-implementation.md

Example script demonstrating graph anomaly detection with SCAN.

```python
# -*- coding: utf-8 -*-
"""Example of using SCAN for graph anomaly detection.

SCAN is a structure-only method -- it does not use node features.
It is transductive: use decision_scores_ and labels_ after fit().

Requires: pip install pyod[graph]
"""
# Author: Yue Zhao <yzhao062@gmail.com>
# License: BSD 2 clause

from __future__ import division
from __future__ import print_function

import os
import sys

sys.path.append(
    os.path.abspath(os.path.join(os.path.dirname("__file__"), '..')))

import numpy as np
import torch
from torch_geometric.data import Data
from pyod.models.pyg_scan import SCAN
from pyod.utils.data import generate_graph_data

if __name__ == "__main__":
    contamination = 0.1

    X, edge_index, y = generate_graph_data(
        n_nodes=500, contamination=contamination, random_state=42)

    data = Data(x=torch.FloatTensor(X),
                edge_index=torch.LongTensor(edge_index))

    clf_name = 'SCAN'
    clf = SCAN(epsilon=0.5, mu=2, contamination=contamination)
    clf.fit(data)

    print("Detector: %s" % clf_name)
    print("Number of anomalies: %d" % clf.labels_.sum())
    print("Top 5 anomaly scores:", np.sort(clf.decision_scores_)[-5:])
```
Tokens:
Raw