Skip to main content

A Python Library for Graph Outlier Detection (Anomaly Detection)

Project description

PyGOD Logo PyPI version Documentation status GitHub stars GitHub forks PyPI downloads testing Coverage Status License

PyGOD is a Python library for graph outlier detection (anomaly detection). This exciting yet challenging field has many key applications, e.g., detecting suspicious activities in social networks [1] and security systems [2].

PyGOD includes 10+ graph outlier detection algorithms. For consistency and accessibility, PyGOD is developed on top of PyTorch Geometric (PyG) and PyTorch, and follows the API design of PyOD. See examples below for detecting outliers with PyGOD in 5 lines!

PyGOD is featured for:

  • Unified APIs, detailed documentation, and interactive examples across various graph-based algorithms.

  • Comprehensive coverage of 10+ graph outlier detectors.

  • Full support of detections at multiple levels, such as node-, edge-, and graph-level tasks.

  • Scalable design for processing large graphs via mini-batch and sampling.

  • Streamline data processing with PyG–fully compatible with PyG data objects.

Outlier Detection Using PyGOD with 5 Lines of Code:

# train a dominant detector
from pygod.detector import DOMINANT

model = DOMINANT(num_layers=4, epoch=20)  # hyperparameters can be set here
model.fit(train_data)  # input data is a PyG data object

# get outlier scores on the training data (transductive setting)
score = model.decision_score_

# predict labels and scores on the testing data (inductive setting)
pred, score = model.predict(test_data, return_score=True)

Citing PyGOD:

Our software paper and benchmark paper are publicly available. If you use PyGOD or BOND in a scientific publication, we would appreciate citations to the following papers:

@article{liu2022pygod,
  title={PyGOD: A Python Library for Graph Outlier Detection},
  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 Chen, George H. and Jia, Zhihao and Yu, Philip S.},
  journal={arXiv preprint arXiv:2204.12095},
  year={2022}
}
@article{liu2022bond,
  title={Bond: Benchmarking unsupervised outlier node detection on static attributed graphs},
  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.},
  journal={Advances in Neural Information Processing Systems},
  volume={35},
  pages={27021--27035},
  year={2022}
}

or:

Liu, K., Dou, Y., Zhao, Y., Ding, X., Hu, X., Zhang, R., Ding, K., Chen, C., Peng, H., Shu, K. and Chen, G.H., Jia, Z., and Yu, P.S. 2022. PyGOD: A Python Library for Graph Outlier Detection. arXiv preprint arXiv:2204.12095.
Liu, K., Dou, Y., Zhao, Y., Ding, X., Hu, X., Zhang, R., Ding, K., Chen, C., Peng, H., Shu, K. and Sun, L., Li, J., Chen, G.H., Jia, Z., and Yu, P.S. 2022. Bond: Benchmarking unsupervised outlier node detection on static attributed graphs. Advances in Neural Information Processing Systems, 35, pp.27021-27035.

Installation

Note on PyG and PyTorch Installation: PyGOD depends on torch and torch_geometric (including its optional dependencies). To streamline the installation, PyGOD does NOT install these libraries for you. Please install them from the above links for running PyGOD:

  • torch>=2.0.0

  • torch_geometric>=2.3.0

It is recommended to use pip for installation. Please make sure the latest version is installed, as PyGOD is updated frequently:

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

Alternatively, you could clone and run setup.py file:

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

Required Dependencies:

  • python>=3.8

  • numpy>=1.24.3

  • scikit-learn>=1.2.2

  • scipy>=1.10.1

  • networkx>=3.1


Quick Start for Outlier Detection with PyGOD

“A Blitz Introduction” demonstrates the basic API of PyGOD using the DOMINANT detector. It is noted that the API across all other algorithms are consistent/similar.


API Cheatsheet & Reference

Full API Reference: (https://docs.pygod.org). API cheatsheet for all detectors:

  • fit(data): Fit the detector with train data.

  • predict(data): Predict on test data (train data if not provided) using the fitted detector.

Key Attributes of a fitted detector:

  • decision_score_: The outlier scores of the input data. Outliers tend to have higher scores.

  • label_: The binary labels of the input data. 0 stands for inliers and 1 for outliers.

  • threshold_: The determined threshold for binary classification. Scores above the threshold are outliers.

Input of PyGOD: Please pass in a PyG Data object. See PyG data processing examples.

Implemented Algorithms

Abbr

Year

Backbone

Sampling

Ref

SCAN

2007

Clustering

No

[3]

GAE

2016

GNN+AE

Yes

[4]

Radar

2017

MF

No

[5]

ANOMALOUS

2018

MF

No

[6]

ONE

2019

MF

No

[7]

DOMINANT

2019

GNN+AE

Yes

[8]

DONE

2020

MLP+AE

Yes

[9]

AdONE

2020

MLP+AE

Yes

[9]

AnomalyDAE

2020

GNN+AE

Yes

[10]

GAAN

2020

GAN

Yes

[11]

DMGD

2020

GNN+AE

Yes

[12]

OCGNN

2021

GNN

Yes

[13]

CoLA

2021

GNN+AE+SSL

Yes

[14]

GUIDE

2021

GNN+AE

Yes

[15]

CONAD

2022

GNN+AE+SSL

Yes

[16]

GADNR

2024

GNN+AE

Yes

[17]


How to Contribute

You are welcome to contribute to this exciting project:

See contribution guide for more information.


PyGOD Team

PyGOD is a great team effort by researchers from UIC, IIT, BUAA, ASU, and CMU. Our core team members include:

Kay Liu (UIC), Yingtong Dou (UIC), Yue Zhao (CMU), Xueying Ding (CMU), Xiyang Hu (CMU), Ruitong Zhang (BUAA), Kaize Ding (ASU), Canyu Chen (IIT),

Reach out us by submitting an issue report or send an email to dev@pygod.org.


Reference

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pygod-1.1.0.tar.gz (55.1 kB view hashes)

Uploaded Source

Built Distribution

pygod-1.1.0-py3-none-any.whl (86.8 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page