Skip to main content

Graph Neural Network-Based Anomaly Detection (GNNAD)

Project description

Graph Neural Network-Based Anomaly Detection (GNNAD)

gnnad is a package for anomaly detection on multivariate time series data.

This model builds on the recently-proposed Graph Deviation Network (GDN)[^2], a graph neural network model that uses embeddings to capture inter-sensor relationships as a learned graph, and employs graph attention-based forecasting to predict future sensor behaviour. Anomalies are flagged when the error scores are above a calculated threshold value. By learning the interdependencies among variables and predicting based on the typical patterns of the system, this approach is able to detect deviations when the expected spatial dependencies are disrupted. As such, GDN offers the ability to detect even the small-deviation anomalies generally overlooked by other distance based and density based anomaly detection methods for time series.

This package accompanies work that further develops this model[^1], and introduces an alternate anomaly threshold criteria based on the learned graph, with the improved ability to detect anomalies in multivariate timeseries data.

Quick start

As an example we'll explore data collected within river network system. In particular data collected on the Herbert river network, at these sensor locations:

Herbert river sensor locations

The sensors measure water level, from within the river. Assuming we have pre-processed the data, we instantiate and fit the model:

from gnnad.graphanomaly import GNNAD

# run model
model = GNNAD(threshold_type="max_validation", topk=6, slide_win=200)
fitted_model = model.fit(X_train, X_test, y_test)

# the predicted values can be accessed here
test_predict = fitted_model.test_result[0, :, i]

We can visualise the predicted values vs. actual values, with helper functions in the plot module.

Herbert river sensor locations

Note that some locations closer to the outlet are influenced by tidal patterns. The error scores that are obtained from this forecasting model are then transformed and, if they exceed the calculated threshold, flagged as an anomaly. The bottom indicates if any sensor flagged an anomaly, and compares this to the ground truth labels, for the test data.

The performance of the anomaly detection classification model can be analysed by:

fitted_model.print_eval_metrics()
>>> recall: 30.4
>>> precision: 59.3
>>> accuracy: 49.7
>>> specificity: 73.9
>>> f1: 40.2

Check out full details in the example notebook

Installation

gnnad is compatible with python versions 3.8, 3.9, 3.10 and 3.11. You can install the latest release with pip:

pip install gnnad

If you would like the latest development version you can install directly from github:

pip install https://github.com/KatieBuc/gnnad.git

Developer installation

You'll need poetry. Once you have it installed and cloned the repo you can install with (from the repo directory):

poetry install

[^1]: Buchhorn, Katie, et al. "Graph Neural Network-Based Anomaly Detection for River Network Systems" Under review. [^2]: Deng, Ailin, and Bryan Hooi. "Graph neural network-based anomaly detection in multivariate time series." Proceedings of the AAAI conference on artificial intelligence. Vol. 35. No. 5. 2021.

Citation

MLA:

Buchhorn, Katie, et al. "Graph Neural Network-Based Anomaly Detection for River Network Systems"
arXiv preprint arXiv:2304.09367 (2023).

BibTeX:

@article{buchhorn2023graph,
  title={Graph Neural Network-Based Anomaly Detection for River Network Systems},
  author={Buchhorn, Katie and Mengersen, Kerrie and Santos-Fernandez, Edgar and Salomone, Robert},
  journal={arXiv preprint arXiv:2304.09367},
  year={2023}
}

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

gnnad-0.1.1.tar.gz (17.7 kB view details)

Uploaded Source

Built Distribution

gnnad-0.1.1-py3-none-any.whl (17.3 kB view details)

Uploaded Python 3

File details

Details for the file gnnad-0.1.1.tar.gz.

File metadata

  • Download URL: gnnad-0.1.1.tar.gz
  • Upload date:
  • Size: 17.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.1 CPython/3.11.3

File hashes

Hashes for gnnad-0.1.1.tar.gz
Algorithm Hash digest
SHA256 f3c50822072870f82b6f2ada5c124ed55b290646c73f570688e9a73bf4eb4050
MD5 8b44da29161c46c29d4018b7a2252603
BLAKE2b-256 49138c28d72cb2511ee4a843aade0f03f64311ac35a4cf38ad7d0989dae0a9df

See more details on using hashes here.

File details

Details for the file gnnad-0.1.1-py3-none-any.whl.

File metadata

  • Download URL: gnnad-0.1.1-py3-none-any.whl
  • Upload date:
  • Size: 17.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.1 CPython/3.11.3

File hashes

Hashes for gnnad-0.1.1-py3-none-any.whl
Algorithm Hash digest
SHA256 04599ae98de516bcbec5453bd4606e0bea4900e322d7ec260bffd68cd1c5ee03
MD5 d5e21ef84d757ef2d622e73733ed7e81
BLAKE2b-256 59fb19f108fafa3cf699c09d51f3aaa89ee0223404b36a304ed07b851204aa9b

See more details on using hashes here.

Supported by

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