Python 深度异常检测/离群点检测（DeepOD）

.. image:: https://github.com/xuhongzuo/DeepOD/actions/workflows/testing.yml/badge.svg :target: https://github.com/xuhongzuo/DeepOD/actions/workflows/testing.yml :alt: 测试2

.. image:: https://readthedocs.org/projects/deepod/badge/?version=latest :target: https://deepod.readthedocs.io/en/latest/?badge=latest :alt: 文档状态

.. image:: https://app.codacy.com/project/badge/Grade/2c587126aac2441abb917c032189fbe8 :target: https://app.codacy.com/gh/xuhongzuo/DeepOD/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade :alt: Codacy

.. image:: https://coveralls.io/repos/github/xuhongzuo/DeepOD/badge.svg?branch=main :target: https://coveralls.io/github/xuhongzuo/DeepOD?branch=main :alt: Coveralls

.. image:: https://static.pepy.tech/personalized-badge/deepod?period=total&units=international_system&left_color=black&right_color=orange&left_text=下载量 :target: https://pepy.tech/project/deepod :alt: 下载量

.. image:: https://img.shields.io/badge/license-BSD2-blue :alt: 许可证

DeepOD 是一个基于深度学习的开源 Python 库，用于 离群点检测 <https://en.wikipedia.org/wiki/Anomaly_detection>_ 和 异常检测 <https://en.wikipedia.org/wiki/Anomaly_detection>_。DeepOD 支持表格数据和时间序列数据的异常检测。

DeepOD 包含 27 种基于深度学习的离群点检测/异常检测算法（采用无监督或弱监督范式）。未来还将加入更多基准算法。

DeepOD 的特点包括：

• 各种算法之间的 统一 API。
• 最先进的模型，涵盖基于重建、表示学习和自监督学习的最新深度学习方法。
• 全面的测试平台，可用于在基准数据集上直接测试不同的模型（非常推荐用于学术研究）。
• 多功能性，适用于多种数据类型，包括表格数据和时间序列数据（未来 DeepOD 还将支持图像、图、日志、轨迹等其他数据类型，欢迎提交 PR :telescope:）。
• 可以将 多样化的网络结构 插入到检测模型中，目前我们支持 LSTM、GRU、TCN、卷积神经网络和 Transformer 等用于时间序列数据的网络。（也欢迎提交 PR :sparkles:）

如果您对我们的项目感兴趣，我们非常高兴收到您的点赞和叉子 :thumbsup: :beers: .

安装

可以通过以下方式安装 DeepOD 框架：


.. code-block:: bash


    pip install deepod


安装开发版本（强烈推荐）


.. code-block:: bash


    git clone https://github.com/xuhongzuo/DeepOD.git
    cd DeepOD
    pip install .


用法

直接使用 DeepOD 中的检测模型： ::::::::::::::::::::::::::::::::::::::::::

使用 DeepOD 只需几行代码即可。这种 API 风格与 Sklean <https://github.com/scikit-learn/scikit-learn>_ 和 PyOD <https://github.com/yzhao062/pyod>_ 相同。

对于表格数据异常检测：

.. code-block:: python

# 无监督方法
from deepod.models.tabular import DeepSVDD
clf = DeepSVDD()
clf.fit(X_train, y=None)
scores = clf.decision_function(X_test)

# 弱监督方法
from deepod.models.tabular import DevNet
clf = DevNet()
clf.fit(X_train, y=semi_y) # semi_y 使用 1 表示已知异常，0 表示未标记数据
scores = clf.decision_function(X_test)

# 表格数据异常检测评估
from deepod.metrics import tabular_metrics
auc, ap, f1 = tabular_metrics(y_test, scores)

对于时间序列异常检测：

.. code-block:: python

# 时间序列异常检测方法
from deepod.models.time_series import TimesNet
clf = TimesNet()
clf.fit(X_train)
scores = clf.decision_function(X_test)

# 时间序列异常检测评估
from deepod.metrics import ts_metrics
from deepod.metrics import point_adjustment # 对时间序列异常进行点级调整
eval_metrics = ts_metrics(labels, scores)
adj_eval_metrics = ts_metrics(labels, point_adjustment(labels, scores))

测试平台用法： ::::::::::::::::::::::::::::::::::::::::::

测试平台包含了测试异常检测模型的完整流程，包括数据加载、预处理、异常检测和评估。

请参考 testbed/

• testbed/testbed_unsupervised_ad.py 用于测试无监督的表格数据异常检测模型。

• testbed/testbed_unsupervised_tsad.py 用于测试无监督的时间序列异常检测模型。

关键参数：

• --input_dir：包含数据集（.csv、.npy）的文件夹名称
• --dataset：FULL 表示测试文件夹中的所有文件，或者用逗号分隔的数据集名称列表（例如，“10_cover*,20_letter*”）
• --model：异常检测模型名称
• --runs：运行检测模型的次数，最终报告平均性能及标准差值

示例：

1. 下载 ADBench <https://github.com/Minqi824/ADBench/tree/main/adbench/datasets/>_ 数据集。
2. 将 dataset_root 变量修改为数据集所在的目录。
3. input_dir 是 dataset_root 下的子文件夹名称，例如“Classical”或“NLP_by_BERT”。
4. 在终端中使用以下命令

.. code-block:: bash

cd DeepOD
pip install .
cd testbed
python testbed_unsupervised_ad.py --model DeepIsolationForest --runs 5 --input_dir ADBench

已实现的模型

**表格数据异常检测模型：**

.. csv-table:: 
 :header: "模型", "会议/期刊", "年份", "类型", "标题"
 :widths: 4, 4, 4, 8, 20

Deep SVDD，ICML，2018年，无监督，深度单类分类  [#Ruff2018Deep]_
 REPEN，KDD，2018年，无监督，基于随机距离的异常检测中超高维数据表示学习 [#Pang2019Repen]_
 RDP，IJCAI，2020年，无监督，通过预测随机距离进行无监督表示学习 [#Wang2020RDP]_
 RCA，IJCAI，2021年，无监督，RCA：一种用于异常检测的深度协作自编码器方法 [#Liu2021RCA]_
 GOAD，ICLR，2020年，无监督，面向通用数据的基于分类的异常检测 [#Bergman2020GOAD]_
 NeuTraL，ICML，2021年，无监督，用于超越图像的深度异常检测的神经变换学习 [#Qiu2021Neutral]_
 ICL，ICLR，2022年，无监督，基于内部对比学习的表格数据异常检测 [#Shenkar2022ICL]_
 DIF，TKDE，2023年，无监督，用于异常检测的深度孤立森林 [#Xu2023DIF]_
 SLAD，ICML，2023年，无监督，引人入胜的监督信号及其来源：基于尺度学习的深度异常检测 [#Xu2023SLAD]_
 DevNet，KDD，2019年，弱监督，基于偏差网络的深度异常检测 [#Pang2019DevNet]_
 PReNet，KDD，2023年，弱监督，深度弱监督异常检测 [#Pang2023PreNet]_
 Deep SAD，ICLR，2020年，弱监督，深度半监督异常检测 [#Ruff2020DSAD]_
 FeaWAD，TNNLS，2021年，弱监督，用于弱监督异常检测的自编码器特征编码 [#Zhou2021FeaWAD]_
 RoSAS，IP&M，2023年，弱监督，RoSAS：具有抗污染连续监督的深度半监督异常检测 [#Xu2023RoSAS]_

**时间序列异常检测模型：**

.. csv-table:: 
 :header: "模型", "会议/期刊", "年份", "类型", "标题"
 :widths: 4, 4, 4, 8, 20 

 DCdetector，KDD，2023年，无监督，DCdetector：用于时间序列异常检测的双注意力对比表示学习 [#Yang2023dcdetector]_
 TimesNet，ICLR，2023年，无监督，TIMESNET：用于通用时间序列分析的时序二维变化建模 [#Wu2023timesnet]_
 AnomalyTransformer，ICLR，2022年，无监督，Anomaly Transformer：基于关联差异的时间序列异常检测 [#Xu2022transformer]_
 NCAD，IJCAI，2022年，无监督，用于时间序列的神经上下文异常检测 [#Carmona2022NCAD]_
 TranAD，VLDB，2022年，无监督，TranAD：用于多变量时间序列数据异常检测的深度Transformer网络 [#Tuli2022TranAD]_
 COUTA，TKDE，2024年，无监督，用于无监督时间序列异常检测的校准单类分类 [#Xu2024COUTA]_
 USAD，KDD，2020年，无监督，USAD：多变量时间序列上的无监督异常检测
 DIF，TKDE，2023年，无监督，用于异常检测的深度孤立森林 [#Xu2023DIF]_
 TcnED，TNNLS，2021年，无监督，多变量时间序列中的异常检测与诊断评估 [#Garg2021Evaluation]_
 Deep SVDD（TS），ICML，2018年，无监督，深度单类分类 [#Ruff2018Deep]_
 DevNet（TS），KDD，2019年，弱监督，基于偏差网络的深度异常检测 [#Pang2019DevNet]_
 PReNet（TS），KDD，2023年，弱监督，深度弱监督异常检测 [#Pang2023PreNet]_
 Deep SAD（TS），ICLR，2020年，弱监督，深度半监督异常检测 [#Ruff2020DSAD]_

注意：

- 对于Deep SVDD、DevNet、PReNet和DeepSAD，我们采用了能够处理时间序列数据的网络结构。这些模型的类中包含一个名为 ``network`` 的参数，通过更改该参数，可以使用不同的网络。

- 目前我们支持‘TCN’、‘GRU’、‘LSTM’、‘Transformer’、‘ConvSeq’和‘DilatedConv’。


引用
~~~~~~~~~~~~~~~~~
如果您在工作中使用了本库，请引用以下论文：

Xu, H., Pang, G., Wang, Y., & Wang, Y. (2023). 深度孤立森林用于异常检测。IEEE知识与数据工程汇刊，35(12)，12591-12604。

Xu, H., Wang, Y., Jian, S., Liao, Q., Wang, Y., & Pang, G. (2024). 用于无监督时间序列异常检测的校准单类分类。IEEE知识与数据工程汇刊。


您也可以使用下面的BibTex条目进行引用。

.. code-block:: bibtex

   @ARTICLE{xu2023deep,
      author={徐洪祚、庞冠松、王义杰、王永军},
      journal={IEEE知识与数据工程汇刊}, 
      title={用于异常检测的深度孤立森林}, 
      year={2023},
      volume={35},
      number={12},
      pages={12591--12604},
      doi={10.1109/TKDE.2023.3270293}
   }

.. code-block:: bibtex

   @ARTICLE{xu2024calibrated,
      title={用于无监督时间序列异常检测的校准单类分类},
      author={徐洪祚、王义杰、简松雷、廖青、王永军、庞冠松},
      journal={IEEE知识与数据工程汇刊},
      year={2024},
      publisher={IEEE}
}


星标历史
~~~~~~~~~~~~~~~~~

当前星标数：

.. image:: https://img.shields.io/github/stars/xuhongzuo/deepod?labelColor=black&color=red
   :alt: GitHub仓库星标数


.. image:: https://api.star-history.com/svg?repos=xuhongzuo/DeepOD&type=Date
   :target: https://star-history.com/#xuhongzuo/DeepOD&Date
   :align: center





参考文献
~~~~~~~~~~~~~~~~~

.. [#Ruff2018Deep] Ruff, Lukas, et al. “深度单类分类”。ICML。2018年。

.. [#Pang2019Repen] Pang, Guansong, et al. “基于随机距离的异常检测中超高维数据表示学习”。KDD（第2041–2050页）。2018年。

.. [#Wang2020RDP] Wang, Hu, et al. “通过预测随机距离进行无监督表示学习”。IJCAI（第2950–2956页）。2020年。

.. [#Liu2021RCA] Liu, Boyang, et al. “RCA：一种用于异常检测的深度协作自编码器方法”。IJCAI（第1505–1511页）。2021年。

.. [#Bergman2020GOAD] Bergman, Liron, 和 Yedid Hoshen. “面向通用数据的基于分类的异常检测”。ICLR。2020年。

.. [#Qiu2021Neutral] Qiu, Chen, et al. “用于超越图像的深度异常检测的神经变换学习”。ICML。2021年。

.. [#Shenkar2022ICL] Shenkar, Tom, et al. “基于内部对比学习的表格数据异常检测”。ICLR。2022年。

.. [#Pang2019DevNet] Pang, Guansong, et al. “基于偏差网络的深度异常检测”。KDD。2019年。

.. [#Pang2023PreNet] Pang, Guansong, et al. “深度弱监督异常检测”。KDD。2023年。

.. [#Ruff2020DSAD] Ruff, Lukas, et al. “深度半监督异常检测”。ICLR。2020年。

.. [#Zhou2021FeaWAD] Zhou, Yingjie, et al. “用于弱监督异常检测的自编码器特征编码”。TNNLS。2021年。

.. [#Xu2022transformer] Xu, Jiehui, et al. “Anomaly Transformer：基于关联差异的时间序列异常检测”。ICLR。2022年。

.. [#Wu2023timesnet] Wu, Haixu, et al. “TimesNet：用于通用时间序列分析的时序二维变化建模”。ICLR。2023年。

.. [#Yang2023dcdetector] 杨一元等.“DCdetector：用于时间序列异常检测的双注意力对比表征学习”。KDD，2023年。

.. [#Tuli2022TranAD] 图利·什雷什特等.“TranAD：用于多变量时间序列数据异常检测的深度Transformer网络”。VLDB，2022年。

.. [#Carmona2022NCAD] 卡尔莫纳·克里斯·U. 等.“面向时间序列的神经上下文异常检测”。IJCAI，2022年。

.. [#Garg2021Evaluation] 加格·阿斯塔等.“多变量时间序列中异常检测与诊断的评估”。TNNLS，2021年。

.. [#Xu2024COUTA] 徐洪佐等.“用于无监督时间序列异常检测的校准型一类分类方法”。TKDE，2024年。

.. [#Xu2023DIF] 徐洪佐等.“用于异常检测的深度孤立森林”。TKDE，2023年。

.. [#Xu2023SLAD] 徐洪佐等.“迷人的监督信号及其来源：基于尺度学习的深度异常检测”。ICML，2023年。

.. [#Xu2023RoSAS] 徐洪佐等.“RoSAS：具有抗污染连续监督的深度半监督异常检测方法”。IP&M，2023年。

DeepOD 快速上手指南

DeepOD 是一个基于深度学习的开源 Python 库，专注于表格数据和时间序列数据的异常检测（Outlier/Anomaly Detection）。它提供了统一的 API 接口，集成了 27 种先进的无监督及弱监督算法。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：建议 Python 3.8 及以上
• 核心依赖：
  • torch (PyTorch)
  • scikit-learn
  • numpy
  • pandas

提示：安装 DeepOD 时会自动处理大部分依赖。若需使用 GPU 加速，请确保已预先安装对应 CUDA 版本的 PyTorch。

安装步骤

方式一：通过 pip 安装（推荐稳定版）

pip install deepod

方式二：从源码安装（推荐开发版，获取最新功能）

git clone https://github.com/xuhongzuo/DeepOD.git
cd DeepOD
pip install .

国内加速建议：若下载速度较慢，可使用清华或阿里镜像源安装：

pip install deepod -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

DeepOD 的 API 设计风格与 Scikit-learn 和 PyOD 保持一致，仅需几行代码即可调用模型。

1. 表格数据异常检测 (Tabular Data)

支持无监督（Unsupervised）和弱监督（Weakly-supervised）模式。

# --- 无监督方法示例 (DeepSVDD) ---
from deepod.models.tabular import DeepSVDD

# 初始化模型
clf = DeepSVDD()
# 训练模型 (y=None 表示无标签)
clf.fit(X_train, y=None)
# 获取异常分数
scores = clf.decision_function(X_test)

# --- 弱监督方法示例 (DevNet) ---
from deepod.models.tabular import DevNet

clf = DevNet()
# semi_y: 已知异常点标记为 1，未标记数据标记为 0
clf.fit(X_train, y=semi_y)
scores = clf.decision_function(X_test)

# --- 结果评估 ---
from deepod.metrics import tabular_metrics

auc, ap, f1 = tabular_metrics(y_test, scores)

2. 时间序列异常检测 (Time-Series Data)

DeepOD 内置了多种网络结构（如 LSTM, GRU, TCN, Transformer 等）以适应时间序列特性。

from deepod.models.time_series import TimesNet

# 初始化模型
clf = TimesNet()
# 训练模型
clf.fit(X_train)
# 获取异常分数
scores = clf.decision_function(X_test)

# --- 结果评估 (含点位调整) ---
from deepod.metrics import ts_metrics
from deepod.metrics import point_adjustment

# 标准评估
eval_metrics = ts_metrics(labels, scores)
# 执行点位调整后的评估 (时间序列检测常用)
adj_eval_metrics = ts_metrics(labels, point_adjustment(labels, scores))

3. 进阶：使用测试床 (Testbed)

DeepOD 提供了一个完整的测试床工具，用于在基准数据集上批量测试不同模型的性能（适合学术研究）。

使用示例： 假设已下载 ADBench 数据集，并放置在 ADBench 文件夹中。

cd DeepOD
pip install .
cd testbed

# 运行 DeepIsolationForest 模型，重复实验 5 次，测试 ADBench 文件夹下的所有数据
python testbed_unsupervised_ad.py --model DeepIsolationForest --runs 5 --input_dir ADBench

关键参数说明：

• --input_dir: 包含数据集 (.csv, .npy) 的文件夹名称。
• --dataset: 指定数据集名称，"FULL" 表示测试文件夹下所有文件。
• --model: 要测试的异常检测模型名称。
• --runs: 运行次数，最终报告平均性能及标准差。