ewstools

A Python package for early warning signals (EWS) of bifurcations in time series data.

Overview

Many systems across nature and society have the capacity to undergo an abrupt and profound change in their dynamics. From a dynamical systemes perspective, these events are often associated with the crossing of a bifurcation. Early warning signals (EWS) for bifurcations are therefore in high demand. Two commonly used EWS for bifurcations are variance and lag-1 autocorrelation, that are expected to increase prior to many bifurcations due to critical slowing down (Scheffer et al. 2009). There now exist a wealth of other EWS based on changes in time series dynamics that are expected to occur prior to bifurcations (see e.g. Clements & Ozgul 2018). More recently, deep learning classifiers have been trained and applied to detect bifurcations, with promising results (Bury et al. 2021).

The goal of this Python package is to provide a an accessible toolbox for computing, analysing and visulaising EWS in time series data. It complements an existing EWS package in R (Dakos et al. 2012). We hope that having an EWS toolbox in Python will allow for additional testing, and appeal to those who primarily work in Python.

Current functionality of ewstools includes

• Time series detrending methods using

  • A Gaussian kernel
  • LOWESS (Locally Weighted Scatterplot Smoothing)

• Computation of CSD-based early warning signals including:

  • Variance and associated metrics (standard deviation, coefficient of variation)
  • Autocorrelation (at specified lag times)
  • Higher-order statistical moments (skewness, kurtosis)
  • Power spectrum and associated metrics

• Computation of Kendall tau values to quantify trends

• Application of deep learning classifiers for bifurcation prediction as in Bury et al. (2022) PNAS.

• Block-bootstrapping of time-series to obtain confidence intervals on EWS estimates

• Visualisation tools to display output

ewstools makes use of pandas for dataframe handling, numpy for fast numerical computing, plotly for visuliastion, lmfit for least-squares minimisation, arch for bootstrapping methods, statsmodels and scipy for detrending methods, and TensorFlow for deep learning.

Install

Requires Python 3.7 or later. You can install ewstools with pip using the commands

pip install --upgrade pip
pip install ewstools

Jupyter notebook is required for the tutorials, and can be installed with the command

pip install jupyter notebook

Package dependencies of ewstools are

'pandas>=0.23.0',
'numpy>=1.14.0',
'plotly>=2.3.0',
'lmfit>=0.9.0', 
'arch>=4.4',
'statsmodels>=0.9.0',
'scipy>=1.0.1',

and should be installed automatically. To use any of the deep learning functionality, you will need to install TensorFlow v2.0.0 or later.

To install the latest development version of ewstools, use the command

pip install git+https://github.com/thomasmbury/ewstools.git#egg=ewstools

NB: the development version comes with the risk of undergoing continual changes, and has not undergone the level of scrutiny of official releases.

Tutorials

1. Introduction to ewstools
2. Spectral EWS
3. Deep learning classifiers for bifurcation prediction

Quick demo

First we need to import ewstools and collect the data we wish to analyse. Here we will run a simulation of the Ricker model, one of the model functions stored in ewstools.models.

import ewstools
from ewstools.models import simulate_ricker
series = simulate_ricker(tmax=500, F=[0,2.7])
series.plot();

We then make a TimeSeries object, which takes in our data and a transition time (if desired). EWS are not computed beyond the transition time.

ts = ewstools.TimeSeries(data=series, transition=440)

We can then detrend, compute EWS and calculate Kendall tau statistics by applying methods to the TimeSeries object:

ts.detrend(method='Lowess', span=0.2)
ts.compute_var(rolling_window=0.5)
ts.compute_auto(lag=1, rolling_window=0.5)
ts.compute_auto(lag=2, rolling_window=0.5)
ts.compute_ktau()

Finally, we can view output as an interactive Plotly figure (when run in a Jupyter notebook) using

ts.make_plotly()

More detailed demonstrations can be found in the tutorials, and all methods are listed in the documentation.

Documentation

Available on ReadTheDocs.

Issues

If you have any suggestions or find any bugs, please post them on the issue tracker. I also welcome any contributions - please get in touch if you are interested, or submit a pull request if you are familiar with that process.

Acknowledgements

This work is currently supported by an FRQNT (Fonds de recherche du Québec - Nature et Technologies) postdoctoral research scholarship awarded to Dr. Thomas Bury. In the past, it has also been supported by NSERC (Natural Sciences and Engineering Research Council) Discovery Grants awarded to Dr. Chris Bauch and Dr. Madhur Anand.

Citation info

If you like the respoitory, please give it a star :D

If your research uses the deep learning functionality of ewstools, please cite

Bury, Thomas M., et al. "Deep learning for early warning signals of tipping points." Proceedings of the National Academy of Sciences 118.39 (2021): e2106140118.

If your research computes spectral EWS using ewstools, please cite

Bury, Thomas M., Chris T. Bauch, and Madhur Anand. "Detecting and distinguishing tipping points using spectral early warning signals." Journal of the Royal Society Interface 17.170 (2020): 20200482.