.. image:: https://raw.githubusercontent.com/pygod-team/pygod/main/docs/pygod_logo.png :width: 1050 :alt: PyGOD Logo :align: center

|badge_pypi| |badge_docs| |badge_stars| |badge_forks| |badge_downloads| |badge_testing| |badge_coverage| |badge_license|

.. |badge_pypi| image:: https://img.shields.io/pypi/v/pygod.svg?color=brightgreen :target: https://pypi.org/project/pygod/ :alt: PyPI版本

.. |badge_docs| image:: https://readthedocs.org/projects/py-god/badge/?version=latest :target: https://docs.pygod.org/en/latest/?badge=latest :alt: 文档状态

.. |badge_stars| image:: https://img.shields.io/github/stars/pygod-team/pygod?style=flat :target: https://github.com/pygod-team/pygod/stargazers :alt: GitHub星标

.. |badge_forks| image:: https://img.shields.io/github/forks/pygod-team/pygod?style=flat :target: https://github.com/pygod-team/pygod/network :alt: GitHub叉子

.. |badge_downloads| image:: https://static.pepy.tech/personalized-badge/pygod?period=total&units=international_system&left_color=grey&right_color=blue&left_text=Downloads :target: https://pepy.tech/project/pygod :alt: PyPI下载量

.. |badge_testing| image:: https://github.com/pygod-team/pygod/actions/workflows/testing.yml/badge.svg :target: https://github.com/pygod-team/pygod/actions/workflows/testing.yml :alt: 测试

.. |badge_coverage| image:: https://coveralls.io/repos/github/pygod-team/pygod/badge.svg?branch=main :target: https://coveralls.io/github/pygod-team/pygod?branch=main :alt: 覆盖率状态

.. |badge_license| image:: https://img.shields.io/github/license/pygod-team/pygod.svg :target: https://github.com/pygod-team/pygod/blob/master/LICENSE :alt: 许可证

---

PyGOD是一个用于图异常检测（离群点检测）的Python库。 这一充满挑战又极具吸引力的研究领域有着广泛的应用，例如在社交网络[#Dou2020Enhancing]_ 和安全系统[#Cai2021Structural]_ 中检测可疑活动。

PyGOD包含10多种图异常检测算法。 为保持一致性和易用性，PyGOD基于PyTorch Geometric (PyG) <https://www.pyg.org/>_ 和 PyTorch <https://pytorch.org/>_ 开发，并遵循 PyOD <https://github.com/yzhao062/pyod>_ 的API设计。 下面通过示例展示如何仅用5行代码使用PyGOD进行异常检测！

PyGOD的特点包括：

• 统一的API、详尽的文档和交互式示例，覆盖多种基于图的算法。
• 全面的算法覆盖，支持10余种图异常检测器。
• 多层级检测支持，涵盖节点级、边级和图级任务。
• 大规模图处理的可扩展设计，通过小批量处理和采样实现高效计算。
• 与PyG数据对象完全兼容，可无缝集成到PyG的数据处理流程中。

使用PyGOD进行异常检测：只需5行代码\ :

.. code-block:: python

# 训练一个DOMINANT检测器
from pygod.detector import DOMINANT

model = DOMINANT(num_layers=4, epoch=20)  # 可在此设置超参数
model.fit(train_data)  # 输入数据为PyG数据对象

# 在训练数据上获取异常分数（直推式设置）
score = model.decision_score_

# 在测试数据上预测标签和分数（归纳式设置）
pred, score = model.predict(test_data, return_score=True)

引用PyGOD\ :

我们的软件论文 <https://jmlr.org/papers/v25/23-0963.html>_ 和 基准论文 <https://proceedings.neurips.cc/paper_files/paper/2022/hash/acc1ec4a9c780006c9aafd595104816b-Abstract-Datasets_and_Benchmarks.html>_ 已公开发布。 如果您在科学出版物中使用了PyGOD或BOND，我们非常感谢您引用以下论文：

@article{JMLR:v25:23-0963,
  author  = {Kay Liu and Yingtong Dou and Xueying Ding and Xiyang Hu and Ruitong Zhang and Hao Peng and Lichao Sun and Philip S. Yu},
  title   = {{PyGOD}: A {Python} Library for Graph Outlier Detection},
  journal = {Journal of Machine Learning Research},
  year    = {2024},
  volume  = {25},
  number  = {141},
  pages   = {1--9},
  url     = {http://jmlr.org/papers/v25/23-0963.html}
}
@inproceedings{NEURIPS2022_acc1ec4a,
 author = {Liu, Kay and Dou, Yingtong and Zhao, Yue and Ding, Xueying and Hu, Xiyang and Zhang, Ruitong and Ding, Kaize and Chen, Canyu and Peng, Hao and Shu, Kai and Sun, Lichao and Li, Jundong and Chen, George H and Jia, Zhihao and Yu, Philip S},
 booktitle = {Advances in Neural Information Processing Systems},
 editor = {S. Koyejo and S. Mohamed and A. Agarwal and D. Belgrave and K. Cho and A. Oh},
 pages = {27021--27035},
 publisher = {Curran Associates, Inc.},
 title = {{BOND}: Benchmarking Unsupervised Outlier Node Detection on Static Attributed Graphs},
 url = {https://proceedings.neurips.cc/paper_files/paper/2022/file/acc1ec4a9c780006c9aafd595104816b-Paper-Datasets_and_Benchmarks.pdf},
 volume = {35},
 year = {2022}
}

或者：

刘凯、窦英彤、丁雪莹、胡西阳、张瑞通、彭浩、孙立超、于Philip S., 2024. PyGOD：用于图异常检测的Python库。机器学习研究期刊，第25卷，第141期，第1–9页。
刘凯、窦英彤、赵悦、丁雪莹、胡西阳、张瑞通、丁凯泽、陈灿宇、彭浩、舒凯、孙立超、李俊东、陈乔治H、贾志豪、于Philip S., 2022. BOND：静态属性图上无监督节点异常检测的基准测试。神经信息处理系统进展，第35卷，第27021–27035页。

---

安装 ^^^^^^^^

关于PyG和PyTorch的安装说明\ : PyGOD依赖于torch <https://https://pytorch.org/get-started/locally/>_ 和 torch_geometric（包括其可选依赖项） <https://pytorch-geometric.readthedocs.io/en/latest/install/installation.html#>_。 为简化安装过程，PyGOD不会自动为您安装这些库。 请务必从上述链接安装以下库以运行PyGOD：

• torch>=2.0.0
• torch_geometric>=2.3.0

建议使用pip进行安装。 请确保安装的是最新版本，因为PyGOD会频繁更新：

.. code-block:: bash

pip install pygod # 普通安装 pip install --upgrade pygod # 或根据需要更新

此外，您也可以克隆仓库并运行setup.py文件：

.. code-block:: bash

git clone https://github.com/pygod-team/pygod.git cd pygod pip install .

所需依赖\ :

• python>=3.8
• numpy>=1.24.3
• scikit-learn>=1.2.2
• scipy>=1.10.1
• networkx>=3.1

---

使用PyGOD快速开始异常检测 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

“闪电入门” <https://docs.pygod.org/en/latest/tutorials/1_intro.html#sphx-glr-tutorials-1-intro-py>_ 通过DOMINANT检测器展示了PyGOD的基本API。需要注意的是，所有其他算法的API都保持一致或相似。

---

API速查表及参考 ^^^^^^^^^^^^^^^^^^^^^^^^^^

完整的 API 参考：(https://docs.pygod.org)。所有检测器的 API 备忘录：

• fit(data)\ ：使用训练数据拟合检测器。
• predict(data)\ ：使用已拟合的检测器对测试数据进行预测（如果未提供测试数据，则使用训练数据）。

已拟合检测器的关键属性：

• decision_score_\ ：输入数据的异常分数。异常值通常具有较高的分数。
• label_\ ：输入数据的二元标签。0 表示内点，1 表示异常点。
• threshold_\ ：确定的二分类阈值。高于该阈值的分数被视为异常值。

PyGOD 的输入：请传入一个 PyG Data 对象 <https://pytorch-geometric.readthedocs.io/en/latest/generated/torch_geometric.data.Data.html#torch_geometric.data.Data>。 请参阅 PyG 数据处理示例 <https://pytorch-geometric.readthedocs.io/en/latest/notes/introduction.html#data-handling-of-graphs>。

已实现的算法 ^^^^^^^^^^^^^^

================== ===== =========== =========== ======================================== 缩写 年份 主干网络 采样策略 参考文献 ================== ===== =========== =========== ======================================== SCAN 2007 聚类 无 [#Xu2007Scan]_ GAE 2016 GNN+AE 是 [#Kipf2016Variational]_ Radar 2017 矩阵分解 无 [#Li2017Radar]_ ANOMALOUS 2018 矩阵分解 无 [#Peng2018Anomalous]_ ONE 2019 矩阵分解 无 [#Bandyopadhyay2019Outlier]_ DOMINANT 2019 GNN+AE 是 [#Ding2019Deep]_ DONE 2020 MLP+AE 是 [#Bandyopadhyay2020Outlier]_ AdONE 2020 MLP+AE 是 [#Bandyopadhyay2020Outlier]_ AnomalyDAE 2020 GNN+AE 是 [#Fan2020AnomalyDAE]_ GAAN 2020 GAN 是 [#Chen2020Generative]_ DMGD 2020 GNN+AE 是 [#Bandyopadhyay2020Integrating]_ OCGNN 2021 GNN 是 [#Wang2021One]_ CoLA 2021 GNN+AE+SSL 是 [#Liu2021Anomaly]_ GUIDE 2021 GNN+AE 是 [#Yuan2021Higher]_ CONAD 2022 GNN+AE+SSL 是 [#Xu2022Contrastive]_ GADNR 2024 GNN+AE 是 [#Roy2024Gadnr]_ CARD 2024 GNN+SSL+AE 是 [#Wang2024Card]_ ================== ===== =========== =========== ========================================

---

如何贡献 ^^^^^^^^^

欢迎为这个令人兴奋的项目做出贡献：

更多信息请参阅 贡献指南 <https://github.com/pygod-team/pygod/blob/main/CONTRIBUTING.rst>_。

---

PyGOD 团队 ^^^^^^^^^^

PyGOD 是由来自 UIC、IIT、BUAA、ASU 和 CMU 的研究人员共同完成的一项杰出团队合作成果。 我们的核心团队成员包括：

Kay Liu (UIC) <https://kayzliu.com/>, Yingtong Dou (UIC) <http://ytongdou.com/>, Yue Zhao (CMU) <https://www.andrew.cmu.edu/user/yuezhao2/>, Xueying Ding (CMU) <https://scholar.google.com/citations?user=U9CMsh0AAAAJ&hl=en>, Xiyang Hu (CMU) <https://www.andrew.cmu.edu/user/xiyanghu/>, Ruitong Zhang (BUAA) <https://github.com/pygod-team/pygod>, Kaize Ding (ASU) <https://www.public.asu.edu/~kding9/>, Canyu Chen (IIT) <https://github.com/pygod-team/pygod>，

您可以通过提交问题报告或发送电子邮件至 dev@pygod.org 与我们联系。

---

参考文献 ^^^^^^^^^

.. [#Dou2020Enhancing] Dou, Y., Liu, Z., Sun, L., Deng, Y., Peng, H. and Yu, P.S., 2020年10月. 增强基于图神经网络的欺诈检测器以应对伪装欺诈者. 在第29届ACM国际信息与知识管理会议(CIKM)论文集中.

.. [#Cai2021Structural] Cai, L., Chen, Z., Luo, C., Gui, J., Ni, J., Li, D. and Chen, H., 2021年10月. 用于动态图异常检测的结构化时序图神经网络. 在第30届ACM国际信息与知识管理会议(CIKM)论文集中.

.. [#Xu2007Scan] Xu, X., Yuruk, N., Feng, Z. and Schweiger, T.A., 2007年8月. SCAN：一种用于网络的结构化聚类算法. 在第13届ACM SIGKDD国际知识发现与数据挖掘会议(KDD)论文集中.

.. [#Kipf2016Variational] Kipf, T.N. and Welling, M., 2016. 变分图自编码器. arXiv预印本arXiv:1611.07308.

.. [#Li2017Radar] Li, J., Dani, H., Hu, X. and Liu, H., 2017年8月. Radar：用于属性网络异常检测的残差分析. 在第二十六届国际人工智能联合会议(IJCAI)论文集中.

.. [#Peng2018Anomalous] Peng, Z., Luo, M., Li, J., Liu, H. and Zheng, Q., 2018年7月. ANOMALOUS：一种用于属性网络异常检测的联合建模方法. 在第二十七届国际人工智能联合会议(IJCAI)论文集中.

.. [#Bandyopadhyay2019Outlier] Bandyopadhyay, S., Lokesh, N. and Murty, M.N., 2019年7月. 面向属性网络的异常感知网络嵌入. 在AAAI人工智能会议论文集中.

.. [#Ding2019Deep] Ding, K., Li, J., Bhanushali, R. and Liu, H., 2019年5月. 属性网络上的深度异常检测. 在SIAM国际数据挖掘会议(SDM)论文集中.

.. [#Bandyopadhyay2020Outlier] Bandyopadhyay, S., Vivek, S.V. and Murty, M.N., 2020年1月. 抗异常的无监督深度架构用于属性网络嵌入. 在国际网络搜索与数据挖掘会议(WSDM)论文集中.

.. [#Fan2020AnomalyDAE] Fan, H., Zhang, F. and Li, Z., 2020年5月. AnomalyDAE：用于属性网络异常检测的双自编码器. 在IEEE国际声学、语音和信号处理会议(ICASSP)论文集中.

.. [#Chen2020Generative] Chen, Z., Liu, B., Wang, M., Dai, P., Lv, J. and Bo, L., 2020年10月. 生成对抗网络在属性网络异常检测中的应用. 在第29届ACM国际信息与知识管理会议(CIKM)论文集中.

.. [#Bandyopadhyay2020Integrating] Bandyopadhyay, S., Vishal Vivek, S. and Murty, M.N., 2020. 通过多类别图描述整合网络嵌入与社区异常检测. 《人工智能与应用前沿》(FAIA).

.. [#Wang2021One] Wang, X., Jin, B., Du, Y., Cui, P., Tan, Y. and Yang, Y., 2021. 单类图神经网络用于属性网络的异常检测. 《神经计算与应用》杂志.

.. [#Liu2021Anomaly] Liu, Y., Li, Z., Pan, S., Gong, C., Zhou, C. and Karypis, G., 2021. 通过对比自监督学习在属性网络上进行异常检测. IEEE神经网络与学习系统汇刊(TNNLS).

.. [#Yuan2021Higher] Yuan, X., Zhou, N., Yu, S., Huang, H., Chen, Z. 和 Xia, F., 2021年12月. 基于高阶结构的属性网络异常检测. 载于2021年IEEE大数据国际会议（Big Data）.

.. [#Xu2022Contrastive] Xu, Z., Huang, X., Zhao, Y., Dong, Y. 和 Li, J., 2022年. 基于数据增强的对比式属性网络异常检测. 载于第26届亚太知识发现与数据挖掘大会（PAKDD）论文集.

.. [#Roy2024Gadnr] Roy, A., Shu, J., Li, J., Yang, C., Elshocht, O., Smeets, J. 和 Li, P., 2024年. GAD-NR：基于邻居重构的图异常检测. 载于第17届ACM国际网络搜索与数据挖掘大会（WSDM）论文集.

.. [#Wang2024Card] Wang Y., Wang X., He C., Chen X., Luo Z., Duan L., Zuo J., 2024年. 面向属性网络异常检测的社区引导对比学习与异常感知重建. 载于高级应用数据库系统会议（DASFAA）.

PyGOD 快速上手指南

PyGOD 是一个基于 Python 的图异常检测（Graph Outlier Detection）库，内置了 10+ 种主流算法。它构建于 PyTorch Geometric (PyG) 之上，API 设计遵循 PyOD 风格，支持节点、边和图级别的异常检测任务。

环境准备

在安装 PyGOD 之前，请确保满足以下系统要求和前置依赖。注意：PyGOD 不会自动安装 PyTorch 和 PyG，需手动预先安装。

系统要求

• Python: >= 3.8
• 核心依赖:
  • torch >= 2.0.0
  • torch_geometric >= 2.3.0
  • numpy >= 1.24.3
  • scikit-learn >= 1.2.2
  • scipy >= 1.10.1
  • networkx >= 3.1

前置依赖安装建议

由于 PyTorch 和 PyG 的版本匹配较为严格，建议先访问 PyTorch 官网 获取适合你环境的安装命令。

国内加速方案： 推荐使用清华或阿里镜像源加速安装：

pip install torch torchvision torchaudio --index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip install torch_geometric -f https://data.pyg.org/whl/torch-2.0.0+cpu.html
# 请将上述命令中的 torch 版本替换为你实际安装的版本

安装步骤

确保前置依赖安装完成后，使用 pip 安装 PyGOD。

标准安装：

pip install pygod

升级安装（如果已安装旧版）：

pip install --upgrade pygod

源码安装（可选）：

git clone https://github.com/pygod-team/pygod.git
cd pygod
pip install .

基本使用

PyGOD 的 API 设计非常简洁，所有检测器均遵循统一的 fit -> predict 流程。输入数据需为 PyG Data 对象。

以下示例展示了如何使用 DOMINANT 算法在 5 行代码内完成异常检测：

# 导入检测器
from pygod.detector import DOMINANT

# 初始化模型并设置超参数
model = DOMINANT(num_layers=4, epoch=20)

# 训练模型 (输入数据为 PyG Data 对象)
model.fit(train_data)

# 获取训练数据的异常分数 (直推式设置)
score = model.decision_score_

# 预测测试数据的标签和分数 (归纳式设置)
pred, score = model.predict(test_data, return_score=True)

关键属性说明

模型拟合后，可通过以下属性获取结果：

• decision_score_: 输入数据的异常分数（分数越高越可能是异常点）。
• label_: 二分类标签（0 代表正常点，1 代表异常点）。
• threshold_: 判定异常的二分类阈值。

提示：PyGOD 内置了包括 SCAN, GAE, Radar, ANOMALOUS, ONE, DONE, AdONE, AnomalyDAE, GAAN, DMGD, OCGNN, CoLA, GUIDE, CONAD, GADNR, CARD 等在内的多种算法，只需将 DOMINANT 替换为其他算法类名即可切换模型。