Package: ewstools
ewstoolsA Python package for early warning signals (EWS) of bifurcations in time series data.OverviewMany 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).ewstoolsis 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 working with EWS in a given time seriesTime series detrending methods usingA Gaussian kernelLOWESS (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 metricsComputation of Kendall tau values to quantify trendsApplication of deep learning classifiers for bifurcation prediction as inBury et al. 2021.Block-bootstrapping of time-series to obtain confidence intervals on EWS estimatesVisualisation tools to display outputBuilt-in theoretical models to test EWSewstoolsmakes use ofpandasfor dataframe handling,numpyfor fast numerical computing,plotlyfor visuliastion,lmfitfor least-squares minimisation,archfor bootstrapping methods,statsmodelsandscipyfor detrending methods, andTensorFlowfor deep learning.InstallRequires Python 3.7 or later. You can installewstoolswith pip using the commandspipinstall--upgradepip
pipinstallewstoolsJupyter notebookis required for the tutorials, and can be installed with the commandpipinstalljupyternotebookPackage 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 any of the deep learning functionality, you will need to installTensorFlowv2.0.0 or later.To install the latestdevelopmentversion, use the commandpipinstallgit+https://github.com/thomasmbury/ewstools.git#egg=ewstoolsNB: the development version comes with the risk of undergoing continual changes, and has not undergone the level of scrutiny of official releases.TutorialsIntroduction toewstoolsSpectral EWSDeep learning classifiers for bifurcation predictionQuick demoFirst we need to importewstoolsand collect data to analyse. Here we will run a simulation of the Ricker model, one of the models stored inewstools.models.importewstoolsfromewstools.modelsimportsimulate_rickerseries=simulate_ricker(tmax=500,F=[0,2.7])series.plot();We then make aTimeSeriesobject, 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 theTimeSeriesobject: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 interactivePlotlyfigure (when run in a Jupyter notebook) usingts.make_plotly()More detailed demonstrations can be found in the tutorials, and all methods are listed in the documentation.DocumentationAvailable onReadTheDocs.IssuesIf you have any suggestions or find any bugs, please post them on theissue 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.AcknowledgementsThis 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 infoIf you like the respoitory, please give it a star :DIf your research uses the deep learning functionality ofewstools, please citeBury, Thomas M., et al. "Deep learning for early warning signals of tipping points."Proceedings of the National Academy of Sciences118.39 (2021): e2106140118.If your research computes spectral EWS usingewstools, please citeBury, Thomas M., Chris T. Bauch, and Madhur Anand. "Detecting and distinguishing tipping points using spectral early warning signals."Journal of the Royal Society Interface17.170 (2020): 20200482.