ThomasMBury / ewstools

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

ewstools

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

Overview

Many systems in nature and society have the capacity to undergo critical transitions--sudden and profound changes in dynamics that are hard to reverse. Examples include the outbreak of disease, the collapse of an ecosystem, or the onset of a cardiac arrhythmia. From a mathematical perspective, these transitions may be understood as the crossing of a bifurcation (tipping point) in an appropriate dynamical system model. In 2009, Scheffer and colleagues proposed early warning signals (EWS) for bifurcations based on statistics of noisy fluctuations in time series data (Scheffer et al. 2009). This spurred massive interest in the subject, resulting in a multitude of different EWS for anticipating bifurcations (Clements & Ozgul 2018). More recently, EWS from deep learning classifiers have outperformed conventional EWS on several model and empirical datasets, whilst also providing information on the type of bifurcation (Bury et al. 2021).

ewstools is an accessible toolbox for computing, analysing and visualising EWS in time series data. It complements an existing EWS package in R (Dakos et al. 2012). Given the recent surge in popularity of the Python programming langauge (PYPL, 2022), a Python-based implementation of EWS should be useful.

The package provides:

• An intuitive, object-oriented framework for computing EWS for a given time series
• 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
  • Various entropy measures
• Computation of Kendall tau values to quantify trends
• Application of deep learning classifiers for bifurcation prediction as in Bury et al. 2021.
• Visualisation tools to display output
• Built-in theoretical models to test EWS

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, EntropyHub for entropy computations, 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 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 the deep learning functionality, you will need to install TensorFlow with version later than 2.0 and earlier than 2.12.

To install the latest development version, 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 data to analyse. Here we will run a simulation of the Ricker model, one of the models 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 makes use of it, please cite

Bury, Thomas M. "ewstools: A Python package for early warning signals of bifurcations in time series data." Journal of Open Source Software 8.82 (2023): 5038.