DOCSEARCHbyAlgolia
Submit Docs

DeepOD: Deep Learning-based Outlier and Anomaly Detection

repository·main·Indexed 20 days ago

https://github.com/xuhongzuo/deepod

An open-source Python library for deep learning-based outlier and anomaly detection supporting tabular and time-series data. It provides a unified API compatible with scikit-learn and PyOD, featuring unsupervised and weakly-supervised models, a variety of neural network architectures (MLP, GRU, LSTM, TCN, Transformer), and a comprehensive testbed for benchmarking state-of-the-art reconstruction and representation-learning methods.

Tokens
4.3K
Snippets
15
Records
21
Agent score
69%

What's inside DeepOD

  1. Overview of DeepOD

    main

    DeepOD is an open-source Python library designed for Deep Learning-based Outlier Detection and Anomaly Detection. It provides a unified API for various algorithms and is optimized for both tabular and time-series data.

    Key features include:

    • Unified APIs: Consistent interfaces across different detection algorithms.
    • SOTA Models: Support for state-of-the-art reconstruction-based, representation-learning-based, and self-supervised deep learning methods.
    • Comprehensive Testbed: A framework for testing models on benchmark datasets, particularly useful for academic research.
    • Versatile Data Support: Currently supports tabular and time-series data (with future support planned for images, graphs, logs, and traces).
    • Diverse Network Structures: For time-series data, DeepOD supports LSTM, GRU, TCN, Conv, and Transformer architectures.

  2. Use unsupervised anomaly detection models for time series

    main

    The deepod.models.time_series module provides several implemented unsupervised anomaly detection models specifically designed for time series data. These models can be used to identify outliers or anomalies within temporal sequences without requiring labeled training data.

    Available models include:

    • TimesNet
    • DCdetector
    • AnomalyTransformer
    • NCAD
    • TranAD
    • COUTA
    • TcnED
    • DeepIsolationForestTS
    • DeepSVDDTS
    • DeepSADTS
    • DevNetTS
    • PReNetTS

  3. Configure Network Structures for Time-Series Models

    main

    For certain models like Deep SVDD, DevNet, PReNet, and DeepSAD, you can customize the underlying network architecture used for time-series data by passing the network parameter during initialization.

    Supported network types include:

    • TCN
    • GRU
    • LSTM
    • Transformer
    • ConvSeq
    • DilatedConv

  4. Install DeepOD

    main

    You can install the stable version of DeepOD via pip, or install the development version directly from the GitHub repository for the latest features.

    # Install stable version
pip install deepod

# Install development version
git clone https://github.com/xuhongzuo/DeepOD.git
cd DeepOD
pip install .

  5. Use DeepOD detection models for tabular data

    main

    DeepOD provides an API compatible with scikit-learn and PyOD. You can use unsupervised or weakly-supervised models for tabular anomaly detection.

    • Unsupervised methods: Use clf.fit(X_train, y=None).
    • Weakly-supervised methods: Use clf.fit(X_train, y=semi_y), where semi_y uses 1 for known anomalies and 0 for unlabeled data.
    • Scoring: Use clf.decision_function(X_test) to obtain anomaly scores.
    • Evaluation: Use tabular_metrics(y_test, scores) to calculate metrics like AUC, AP, and F1.
    # unsupervised methods
from deepod.models.tabular import DeepSVDD
clf = DeepSVDD()
clf.fit(X_train, y=None)
scores = clf.decision_function(X_test)

# weakly-supervised methods
from deepod.models.tabular import DevNet
clf = DevNet()
clf.fit(X_train, y=semi_y) # semi_y uses 1 for known anomalies, and 0 for unlabeled data
scores = clf.decision_function(X_test)

# evaluation of tabular anomaly detection
from deepod.metrics import tabular_metrics
auc, ap, f1 = tabular_metrics(y_test, scores)

  7. Use DeepOD detection models for time series data

    main

    For time series anomaly detection, follow these steps:

    • Detection: Import models from deepod.models.time_series. Fit the model using clf.fit(X_train) and get scores via clf.decision_function(X_test).
    • Evaluation: Use ts_metrics(labels, scores) for standard evaluation.
    • Point Adjustment: For time series, it is common to apply point adjustment. Use point_adjustment(labels, scores) before passing the adjusted scores to ts_metrics to get adj_eval_metrics.
    # time series anomaly detection methods
from deepod.models.time_series import TimesNet
clf = TimesNet()
clf.fit(X_train)
scores = clf.decision_function(X_test)

# evaluation of time series anomaly detection
from deepod.metrics import ts_metrics
from deepod.metrics import point_adjustment # execute point adjustment for time series ad
eval_metrics = ts_metrics(labels, scores)
adj_eval_metrics = ts_metrics(labels, point_adjustment(labels, scores))

  8. Run the DeepOD Testbed

    main

    The Testbed is a comprehensive tool for testing anomaly detection models on benchmark datasets. It handles data loading, preprocessing, detection, and evaluation.

    Available Testbed Scripts

    • testbed/testbed_unsupervised_ad.py: For unsupervised tabular anomaly detection.
    • testbed/testbed_unsupervised_tsad.py: For unsupervised time-series anomaly detection.

    CLI Arguments

    • --input_dir: Folder containing datasets (.csv, .npy).
    • --dataset: "FULL" to test all files in the folder, or a comma-separated list of names (e.g., "10_cover*,20_letter*").
    • --model: Name of the anomaly detection model to test.
    • --runs: Number of times to run the model (reports average performance and standard deviation).
    cd DeepOD
pip install .
cd testbed
python testbed_unsupervised_ad.py --model DeepIsolationForest --runs 5 --input_dir ADBench

  9. Run anomaly detection benchmarks using the Testbed

    main

    The testbed/ directory contains scripts for end-to-end testing of anomaly detection models, including data loading, preprocessing, detection, and evaluation.

    Available Testbed Scripts

    • testbed/testbed_unsupervised_ad.py: For unsupervised tabular anomaly detection.
    • testbed/testbed_unsupervised_tsad.py: For unsupervised time-series anomaly detection.

    CLI Arguments

    ArgumentDescription
    --input_dirThe folder containing datasets (.csv, .npy)
    --dataset"FULL" to test all files in the folder, or a comma-separated list of names (e.g., "10_cover*,20_letter*")
    --modelThe name of the anomaly detection model to use
    --runsNumber of times to run the detection (reports average performance and standard deviation)

    Quickstart Example

    1. Download ADBench datasets.
    2. Ensure dataset_root in the script points to your dataset directory.
    3. Set input_dir to the sub-folder name (e.g., Classical).
    4. Run the command below:
    cd DeepOD
pip install .
cd testbed
python testbed_unsupervised_ad.py --model DeepIsolationForest --runs 5 --input_dir ADBench

  10. Save and load models using built-in methods

    main

    All detection model classes in DeepOD provide save_model and load_model methods for persisting trained models. To save a model, call model.save_model(path) where path is the destination file path. To restore a model, use the class method ModelClass.load_model(path) (e.g., DeepSVDD.load_model(path)).

    from deepod.models import DeepSVDD

# training an anomaly detection model
model = DeepSVDD()
model.fit(X_train)

# save trained model at the assigned path
path = 'save_file.pkl'
model.save_model(path)

# directly load trained model from path
model = DeepSVDD.load_model(path)
model.decision_function(X_test)
# or
model.predict(X_test)

  11. Install DeepOD via pip

    main

    The recommended way to install DeepOD is using pip. Since the library is updated frequently, it is advised to ensure you are using the latest version.

    To perform a normal installation:

    pip install deepod

    To upgrade an existing installation to the latest version:

    pip install --upgrade deepod
    pip install deepod            # normal install
pip install --upgrade deepod  # or update if needed

  12. Use DeepOD for Time Series Anomaly Detection

    main

    DeepOD supports various network structures for time-series data, including LSTM, GRU, TCN, Transformer, ConvSeq, and DilatedConv.

    Detection

    Train models using clf.fit(X_train) and generate scores with clf.decision_function(X_test).

    Evaluation

    Use ts_metrics for time-series evaluation. For time-series specific tasks, it is often recommended to apply point_adjustment to the scores before evaluation.

    # Time series anomaly detection
from deepod.models.time_series import TimesNet
clf = TimesNet()
clf.fit(X_train)
scores = clf.decision_function(X_test)

# Evaluation
from deepod.metrics import ts_metrics, point_adjustment
eval_metrics = ts_metrics(labels, scores)

# Evaluation with point adjustment
adj_eval_metrics = ts_metrics(labels, point_adjustment(labels, scores))