ewstools 2.0.1

Python package to compute early warning signals (EWS)

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 changes corresopond to bifurcations, which carry some generic features that can be picked up on in time series data (Scheffer et al. 2009). Two commonly used metrics include variance and lag-1 autocorrelation, though there exist many others (see e.g. Clements & Ozgul 2018). More recently, deep learning methods have been developed to provide early warning signals, whilst also signalling the type of bifurcation approaching (Bury et al. 2021).

The goal of this Python package is to provide a user-friendly toolbox for computing early warning signals in time series data. It complements an existing early warning signals package in R (Dakos et al. 2012). We hope that having an early warning signal toolbox in Python will allow for additional testing, and appeal to those who primarily work in Python. I will try to keep it updated with the latest methods.

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>=1.2.0',
'numpy>=1.20.0',
'plotly>=5.3.0',
'lmfit>=0.9', 
'arch>=4.7',
'statsmodels>=0.12.0',
'scipy>=1.5.0',

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/Demonstrations

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 was supported by NSERC (Natural Sciences and Engineering Research Council) Discovery Grants awarded to Dr. Chris Bauch and Dr. Madhur Anand.

Citation info

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.