Package: gnnad
Graph Neural Network-Based Anomaly Detection (GNNAD)gnnadis 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 startAs an example we'll explore data collected within river network system. In particular data collected on the Herbert river network, at these sensor locations:The sensors measure water level, from within the river. Assuming we have pre-processed the data, we instantiate and fit the model:fromgnnad.graphanomalyimportGNNAD# run modelmodel=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 heretest_predict=fitted_model.test_result[0,:,i]We can visualise the predicted values vs. actual values, with helper functions in the plot module.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.2Check out full details in theexample notebookInstallationgnnadis compatible with python versions 3.8, 3.9, 3.10 and 3.11. You can install the latest release with pip:pipinstallgnnadIf you would like the latest development version you can install directly from github:pipinstallhttps://github.com/KatieBuc/gnnad.gitDeveloper installationYou'll needpoetry. Once you have it installed and
cloned the repo you can install with (from the repo directory):poetryinstall[^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.CitationMLA: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}
}