# yzhao062/pyod architecture

> Architecture diagram of the GitHub repository yzhao062/pyod, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yzhao062/pyod
- Repository: https://github.com/yzhao062/pyod

## Overview

##### Project type and purpose
- This is **PyOD**, an **open-source Python library** for multivariate outlier/anomaly detection.
- Provides a unified API for 50+ detection algorithms (classical, ensemble, deep learning), utilities, thresholding, examples, notebooks, documentation, packaging, and CI/CD.

##### File structure
- **Top-level directories**
- `/pyod` – the core library package
- `/examples` – standalone example scripts demonstrating API usage
- `/notebooks` – Jupyter notebooks for benchmarking and tutorials
- `/docs` – Sphinx source for user documentation (RST files, conf.py)
- `/.github/workflows` – CI/CD pipelines for testing, code scanning, cron benchmarks
- **Core module layout**
- `pyod/models` – individual detectors (base.py, base_dl.py, subdirectories per category)
- `pyod/utils` – data generation, evaluation, statistical and PyTorch utilities
- `pyod/test` – extensive unit tests exercising all detectors and utils
- **Configuration & packaging**
- `setup.py` / `setup.cfg` / `requirements.txt` – packaging and dependencies
- `MANIFEST.in`, `pypi_build_commands.txt` – prepare distribution
- **Documentation pipeline**
- Sphinx Makefiles (`docs/Makefile`, `docs/rebuild.bat`)
- ReadTheDocs config (`.readthedocs.yaml`)

##### README for insights
- **Architecture highlights**
- Modular, **plugin-style** detectors inheriting from a common interface
- **Ensemble framework** (SUOD, combination strategies)
- **Optional deep-learning** backends (PyTorch) and optional dependencies (xgboost, pythresh, suod)
- **Thresholding** abstractions for contamination estimation
- **CI/CD and publishing**
- GitHub Actions for testing, code coverage, security scanning
- Published to PyPI and Conda
- **Usage patterns**
- Simple `fit` / `predict` / `decision_function` API
- Model persistence via `joblib` or `pickle`

1. **User/Application Code**
- Imports PyOD, calls detectors, utilities, persists models
2. **Core Library (`pyod/`)**
- **Models Submodule** – base interfaces, classical, ensemble, deep learning
- **Utils Submodule** – data, evaluation, stat, torch helpers
- **Thresholding Module** – dynamic contamination estimation
3. **Examples & Notebooks**
- Scripts and notebooks that illustrate usage and benchmarking
4. **Documentation Pipeline**
- Sphinx sources → ReadTheDocs
5. **CI/CD Pipeline**
- GitHub Actions workflows: testing, code quality, cron benchmarks
6. **Packaging & Distribution**
- setup.py → PyPI / Conda
7. **External Dependencies**
- numpy, scipy, scikit-learn, numba, joblib, matplotlib
- Optional: PyTorch, xgboost, suod, pythresh

- **User Code → Core Library**: imports modules and invokes API
- **Core Library → External Dependencies**: uses numpy/numba for computation, PyTorch for DL, joblib for parallelism
- **Core Library ↔ Thresholding Module**: detectors output raw scores → thresholding logic yields binary labels
- **Core Library → Model Persistence**: uses joblib/pickle to save/load
- **Docs Pipeline** reads code & RST → generates HTML on ReadTheDocs
- **CI/CD Pipeline** triggers on push/pull: runs tests in `pyod/test`, builds docs, badges update
- **Packaging**: `setup.py` bundles `pyod/`, examples, docs into a distribution

c. **Architectural patterns & design principles**
- **Modularity & Plugin Architecture**: each detector implements a shared interface (Base or BaseDL)
- **Separation of Concerns**: distinct subpackages for algorithms vs. utilities vs. thresholding
- **Extensibility Points**: easily add new detectors under `pyod/models` and update registry
- **Parallel & JIT Optimization**: use joblib for ensemble parallelism, numba for JIT compilation
- **Conditional Imports**: optional dependencies guarded so users install only what they need

d. **Technologies & frameworks**
- Python 3.8+ standard library
- Core: numpy, scipy, scikit-learn
- Performance: numba, joblib
- Deep Learning: PyTorch (in `pyod/models/*_dl.py`)
- Publishing: setuptools, PyPI, Conda
- Documentation: Sphinx, ReadTheDocs
- CI: GitHub Actions

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User/Application
    User["User/Application Code"]:::external

    %% Core Library
    subgraph "Core Library" 
        direction TB
        Models["Models Submodule"]:::core
        BaseInt["Base Interfaces"]:::core
        Classical["Classical & Ensemble Detectors"]:::core
        Deep["Deep Learning Detectors"]:::core
        Thresholds["Thresholding Module"]:::core
        Utils["Utils Submodule"]:::core
        Version["Version Info"]:::core
    end

    %% Examples & Notebooks
    subgraph "Examples & Demonstrations"
        Examples["Examples Scripts & Data"]:::examples
    end
    subgraph "Notebooks & Benchmarks"
        Notebooks["Jupyter Notebooks & Benchmarks"]:::examples
    end

    %% Documentation Pipeline
    subgraph "Documentation Pipeline"
        DocsSrc["Sphinx Sources"]:::infra
        RTDConfig["ReadTheDocs Config"]:::infra
    end

    %% CI/CD Pipeline
    CI["CI/CD (GitHub Actions)"]:::infra

    %% Packaging & Distribution
    Packaging["Packaging & Distribution"]:::infra

    %% External Dependencies
    subgraph "External Dependencies"
        Numpy["NumPy / SciPy / scikit-learn"]:::external
        NumbaJoblib["Numba / Joblib"]:::external
        Torch["PyTorch (Optional)"]:::external
        Others["xgboost / suod / pythresh (Optional)"]:::external
        JoblibPersist["joblib / pickle"]:::external
    end

    %% Relationships
    User -->|"imports & uses"| Models
    User -->|"imports & uses"| Utils
    Models -->|"inherits from"| BaseInt
    Classical -->|"implements plugin"| Models
    Deep -->|"implements plugin"| Models
    Models -->|"outputs scores"| Thresholds
    Thresholds -->|"returns labels"| Models
    Models -->|"uses"| Numpy
    Models -->|"uses"| NumbaJoblib
    Models -->|"optional DL"| Torch
    Models -->|"optional"| Others
    Models -->|"persists via"| JoblibPersist
    Utils -->|"helpers"| Models
    Examples -->|"demonstrates"| Models
    Examples -->|"uses data"| Numpy
    Notebooks -->|"benchmarks & tutorials"| Models
    DocsSrc -->|"reads code & rst"| Models
    DocsSrc -->|"reads rst"| DocsSrc
    RTDConfig -->|"configures build"| DocsSrc
    CI -->|"runs tests on"| Models
    CI -->|"runs tests on"| Utils
    CI -->|"runs docs build"| DocsSrc
    CI -->|"cron benchmarks"| Notebooks
    Packaging -->|"bundles code & docs"| Models
    Packaging -->|"publishes to PyPI/Conda"| Packaging

    %% Click Events
    click Models "https://github.com/yzhao062/pyod/tree/master/pyod/models/"
    click BaseInt "https://github.com/yzhao062/pyod/blob/master/pyod/models/base.py"
    click Deep "https://github.com/yzhao062/pyod/blob/master/pyod/models/deep_svdd.py"
    click Thresholds "https://github.com/yzhao062/pyod/blob/master/pyod/models/thresholds.py"
    click Utils "https://github.com/yzhao062/pyod/tree/master/pyod/utils/"
    click Version "https://github.com/yzhao062/pyod/blob/master/pyod/version.py"
    click CI "https://github.com/yzhao062/pyod/tree/master/.github/workflows/"
    click DocsSrc "https://github.com/yzhao062/pyod/tree/master/docs/"
    click RTDConfig "https://github.com/yzhao062/pyod/blob/master/.readthedocs.yaml"
    click Packaging "https://github.com/yzhao062/pyod/blob/master/setup.py"
    click Examples "https://github.com/yzhao062/pyod/tree/master/examples/"
    click Notebooks "https://github.com/yzhao062/pyod/tree/master/notebooks/"
    click Classical "https://github.com/yzhao062/pyod/blob/master/pyod/models/combination.py"
    click Classification "https://github.com/yzhao062/pyod/blob/master/pyod/models/suod.py"
    click UtilsData "https://github.com/yzhao062/pyod/blob/master/pyod/utils/data.py"
    click UtilsStat "https://github.com/yzhao062/pyod/blob/master/pyod/utils/stat_models.py"
    click UtilsTorch "https://github.com/yzhao062/pyod/blob/master/pyod/utils/torch_utility.py"
    click UtilsUtil "https://github.com/yzhao062/pyod/blob/master/pyod/utils/utility.py"
    click TestSuite "https://github.com/yzhao062/pyod/tree/master/pyod/test/"

    %% Styles
    classDef core fill:#D6EAF8,stroke:#2980B9,color:#1B2631
    classDef external fill:#F9E79F,stroke:#D68910,color:#1B2631
    classDef infra fill:#ABEBC6,stroke:#239B56,color:#1B2631
    classDef examples fill:#E8DAEF,stroke:#8E44AD,color:#1B2631

    %% Legend
    subgraph Legend
        direction LR
        C1["Core Modules"]:::core
        C2["External / Optional Dependencies"]:::external
        C3["CI/CD & Docs Infrastructure"]:::infra
        C4["Examples & Notebooks"]:::examples
    end
```
