ewstools

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

Overview

Many systems in nature and society can undergo critical transitions—sudden, often irreversible shifts in dynamics. Examples include the outbreak of disease, ecosystem collapse, and cardiac arrhythmias. Mathematically, such transitions often correspond to bifurcations (tipping points) in an underlying dynamical system.

Scheffer et al. (2009) proposed early warning signals (EWS) for bifurcations based on noisy fluctuations in time series data, sparking a surge of related ways to predict bifurcations (see Dakos et al. (2024) for a recent review). More recently, deep learning has shown great potential for predicting bifurcations and their type (Bury et al. 2021).

ewstools is a Python package for computing and visualizing EWS in time series. It complements the R package by (Dakos et al. 2012) and meets growing demand for Python-based tools (PYPL, 2022).

Features include:

• An intuitive, object-oriented framework for computing EWS
• Detrending methods:
  • Gaussian kernel smoothing
  • LOWESS (Locally Weighted Scatterplot Smoothing)
• Computation of critical slowing down (CSD) indicators:
  • Variance, standard deviation, coefficient of variation
  • Autocorrelation (at specified lags)
  • Skewness, kurtosis
  • Power spectra metrics
  • Entropy measures
  • Detrended Fluctuation Analysis (DFA)
• Kendall tau statistics to quantify trends
• Deep learning classifiers for bifurcation prediction (Bury et al. 2021)
• Visualization tools
• Built-in dynamical system models for testing EWS

ewstools uses pandas for dataframe handling, numpy for fast numerical computing, plotly for visualisation, 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.9–3.12. Install via:

pip install --upgrade pip
pip install ewstools

For tutorials, install Jupyter notebook:

pip install jupyter notebook

To enable deep learning features, install TensorFlow:

pip install ewstools[tf]

Note: TensorFlow for ewstools is currently supported on Linux and macOS only.

To install the latest development version:

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

(Development versions may be unstable.)

Tutorials

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

Quick demo

Code available in ./quick_demo.ipynb. Import ewstools and simulate a time series (e.g., the Ricker model):

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

Create a TimeSeries object:

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

Detrend, compute EWS, and calculate trends:

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()

Get predictions from deep learning classifiers

for idx, classifier in enumerate(list_classifiers):
    ts.apply_classifier_inc(classifier, inc=10, verbose=0, name=str(idx))

Make an interactive visualization in Plotly:

ts.make_plotly()

For detailed demonstrations, see the tutorials.

Documentation

Full documentation available on ReadTheDocs.

Issues

Found a bug or have a suggestion? Please post it on the issue tracker.

Contributions are welcome! Feel free to reach out or submit a pull request.

Acknowledgements

This work is supported by an FRQNT postdoctoral research scholarship awarded to Dr. Thomas Bury. Previous support was provided by NSERC Discovery Grants awarded to Dr. Chris Bauch and Dr. Madhur Anand.

Citation info

If you find ewstools useful, please consider starring the repository ⭐ and citing:

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.