Canari is an open-source library for online change point detection in univariate time series. It has been developed in the context of long-term online monitoring where we aim for the early detection of subtle change points in the baseline response, while limiting to a minimum the number of false alarms.
Because Canari’s probabilistic change-point detection relies on 1-step ahead predictions, it is inherently capable of performing short- and long-term forecasting, as well as online data imputation; One-step ahead predictions can either rely solely on a target time series, or on explanatory time series that can be non-linearly related to the target.
In addition to change-point detection and forecasting capabilities, it returns an interpretable decomposition of time series into baseline components representing the irreversible responses, recurrent pattern components caused by external effects, and residual components allowing the characterization of both the model prediction and the observation uncertainties.
The methodological core behind the canary library consists of a seamless integration between state-space models (SSM) and Bayesian neural networks. On the one hand, the Gaussian SSM theory enables modelling baseline responses and residuals, while on the other, Tractable Approximate Gaussian Inference (TAGI) also enables treating all parameters and hidden states in neural networks as Gaussians.
Canari uses LSTM neural networks to model recurrent patterns as well as non-linear dependencies with respect to explanatory variables. Because both the SSM and LSTM rely on the same Gaussian conditional inference mechanism, their hidden states can be inferred analytically in a same unified probabilistic framework.
The figure above presents an example where the raw data in red is decomposed in a baseline that is characterized by a baseline “level” component where its rate of change is described by the “trend”. The recurrent pattern is modelled by a LSTM Bayesian neural network where the training and validation set consists only in 4 years of data. The residual characterizing the model errors is itself modelled by a white “noise” component. The change point detection can be performed either online or offline after the training and validation period; The presence of change points is indicated by the probability of regime switches that rise toward 1 on several occasions.
You can get started with Canari by going through our tutorials covering all the main features of the library.
Canari available on PyPI, for installation, execute the following command in Terminal:
pip install pycanari
For more info. on how to install, visit our installation guide.
The principal developer of canary is Van Dai Vuong with the mentoring of Luong Ha Nguyen and oversight by James-A. Goulet. The major contributors to the library are:
- Zhanwen Xin (Online AR, Bounded AR & several+++ bug fixes through PRs)
- David Wardan (SLSTM component & several+++ bug fixes through PRs)
We acknowledge the financial support from Hydro-Québec and the Natural Sciences and Engineering Research Council of Canada in the development of the Canari library.
Canari is released under the MIT license. THIS IS AN OPEN SOURCE SOFTWARE FOR RESEARCH PURPOSES ONLY. THIS IS NOT A PRODUCT. NO WARRANTY EXPRESSED OR IMPLIED.
- Coupling LSTM Neural Networks and State-Space Models through Analytically Tractable Inference (Van Dai Vuong, Luong-Ha Nguyen and James-A. Goulet. International Journal of Forecasting, 2024)
- Enhancing structural anomaly detection using a bounded autoregressive component(Zhanwen Xin and James-A. Goulet, 2024)
- Analytically tractable heteroscedastic uncertainty quantification in Bayesian neural networks for regression tasks (Bhargob Deka, Luong-Ha Nguyen and James-A. Goulet. Neurocomputing, 2024)
- Approximate Gaussian Variance Inference for State-Space Models (Bhargob Deka and James-A. Goulet, 2023)
- The Gaussian multiplicative approximation for state-space models(Bhargob Deka, Luong Ha Nguyen, Saeed Amiri, and James-A. Goulet, 2021)
- Anomaly Detection with the Switching Kalman Filter for Structural Health Monitoring (Luong Ha Nguyen and James-A. Goulet, 2018)
- Bayesian dynamic linear models for structural health monitoring(James-A. Goulet, 2017)
*Analytically Tractable Bayesian Recurrent Neural Networks with Structural Health Monitoring Applications (Van-Dai Vuong, 2024)
- Analytical Bayesian Parameter Inference for Probabilistic Models with Engineering Applications (Bhargob Deka, 2022)
- Real-time Anomaly Detection in the Behaviour of Structures (Luong Ha Nguyen, 2019)
- Probabilistic machine learning for civil engineers (chapter 12 - SSM) (James-A. Goulet. 2020)