Merge pull request #439 from ThomasMBury/main

Merge main into dev

.github/workflows/draft-pdf.yml

@@ -12,12 +12,12 @@ jobs:
         with:
           journal: joss
           # This should be the path to the paper within your repo.
-          paper-path: paper.md
+          paper-path: paper/paper.md
       - name: Upload
         uses: actions/upload-artifact@v1
         with:
           name: paper
           # This is the output path where Pandoc will write the compiled
           # PDF. Note, this should be the same directory as the input
           # paper.md
-          path: paper.pdf
+          path: paper/paper.pdf

.zenodo.json

@@ -0,0 +1,27 @@
+{
+    "description": "A Python package for early warning signals of bifurcations in time series data", 
+    "license": "CC BY 4.0", 
+    "title": "ewstools: A Python package for early warning signals of bifurcations in time series data", 
+    "version": "v2.1.1",
+    "upload_type": "software",
+    "publication_date": "2023-02-10", 
+    "creators": [
+        {
+            "affiliation": "McGill University", 
+            "name": "Thomas Bury"
+        }
+    ], 
+    "access_right": "open", 
+    "related_identifiers": [
+        {
+            "scheme": "url", 
+            "identifier": "https://github.com/ThomasMBury/ewstools/tree/v2.1.1", 
+            "relation": "isSupplementTo"
+        }, 
+        {
+            "scheme": "doi", 
+            "identifier": "10.5281/zenodo.2598517", 
+            "relation": "isVersionOf"
+        }
+    ]
+}

README.md

@@ -3,42 +3,40 @@
 [![Documentation Status](https://readthedocs.org/projects/ewstools/badge/?version=latest)](https://ewstools.readthedocs.io/en/latest/?badge=latest)
 [![tests](https://github.com/ThomasMBury/ewstools/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/ThomasMBury/ewstools/actions/workflows/tests.yml)
 [![codecov](https://codecov.io/gh/ThomasMBury/ewstools/branch/main/graph/badge.svg?token=Q5LGRV6TLF)](https://codecov.io/gh/ThomasMBury/ewstools)
+[![DOI](https://joss.theoj.org/papers/10.21105/joss.05038/status.svg)](https://doi.org/10.21105/joss.05038)
 
 # 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](https://www.nature.com/articles/nature08227)). 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](https://onlinelibrary.wiley.com/doi/full/10.1111/ele.12948)). More recently, deep learning classifiers have been trained and applied to detect bifurcations, with promising results ([Bury et al. 2021](https://www.pnas.org/doi/10.1073/pnas.2106140118)).
+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](https://www.nature.com/articles/nature08227)). This spurred massive interest in the subject, resulting in a multitude of different EWS for anticipating bifurcations ([Clements & Ozgul 2018](https://onlinelibrary.wiley.com/doi/full/10.1111/ele.12948)). 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](https://www.pnas.org/doi/10.1073/pnas.2106140118)).
 
-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](https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0041010)). We hope that having an EWS toolbox in Python will allow for additional testing, and appeal to those who primarily work in Python.
+`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](https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0041010)). Given the recent surge in popularity of the Python programming langauge ([PYPL, 2022](https://pypl.github.io/PYPL.html)), a Python-based implementation of EWS should be useful.
 
-Current functionality of *ewstools* includes
+The package provides:
 
+  - An intuitive, object-oriented framework for working with EWS in 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
-
   - Computation of Kendall tau values to quantify trends
-
-  - Application of deep learning classifiers for bifurcation prediction as in [Bury et al. (2022) PNAS](https://www.pnas.org/doi/10.1073/pnas.2106140118).
-
+  - Application of deep learning classifiers for bifurcation prediction as in [Bury et al. 2021](https://www.pnas.org/doi/10.1073/pnas.2106140118).
   - Block-bootstrapping of time-series to obtain confidence intervals on EWS estimates
-
   - Visualisation tools to display output
+  - Built-in theoretical models to test EWS
 
-*ewstools* makes use of [pandas](https://pandas.pydata.org/) for dataframe handling, [numpy](https://numpy.org/) for fast numerical computing, [plotly](https://plotly.com/graphing-libraries/) for visuliastion, [lmfit](https://lmfit.github.io/lmfit-py/) for least-squares minimisation, [arch](https://github.com/bashtage/arch) for bootstrapping methods, [statsmodels](https://www.statsmodels.org/stable/index.html) and [scipy](https://scipy.org/) for detrending methods, and [TensorFlow](https://www.tensorflow.org/install) for deep learning.
+`ewstools` makes use of [pandas](https://pandas.pydata.org/) for dataframe handling, [numpy](https://numpy.org/) for fast numerical computing, [plotly](https://plotly.com/graphing-libraries/) for visuliastion, [lmfit](https://lmfit.github.io/lmfit-py/) for least-squares minimisation, [arch](https://github.com/bashtage/arch) for bootstrapping methods, [statsmodels](https://www.statsmodels.org/stable/index.html) and [scipy](https://scipy.org/) for detrending methods, and [TensorFlow](https://www.tensorflow.org/install) for deep learning.
 
 
 ## Install
 
-Requires Python 3.7 or later. You can install *ewstools* with pip using the commands
+Requires Python 3.7 or later. You can install `ewstools` with pip using the commands
 
 ```bash
 pip install --upgrade pip
@@ -49,7 +47,7 @@ pip install ewstools
 ```bash
 pip install jupyter notebook
 ```
-Package dependencies of *ewstools* are
+Package dependencies are
 ```bash
 'pandas>=0.23.0',
 'numpy>=1.14.0',
@@ -61,7 +59,7 @@ Package dependencies of *ewstools* are
 ```
 and should be installed automatically. To use any of the deep learning functionality, you will need to install [TensorFlow](https://www.tensorflow.org/install) v2.0.0 or later.
 
-To install the latest *development* version of *ewstools*, use the command
+To install the latest *development* version, use the command
 ```bash
 pip install git+https://github.com/thomasmbury/ewstools.git#egg=ewstools
 ```
@@ -80,7 +78,7 @@ NB: the development version comes with the risk of undergoing continual changes,
 
 ## 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`](https://ewstools.readthedocs.io/en/latest/ewstools.html#ewstools-models-submodule).
+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`](https://ewstools.readthedocs.io/en/latest/ewstools.html#ewstools-models-submodule).
 ```python
 import ewstools
 from ewstools.models import simulate_ricker
@@ -131,10 +129,6 @@ This work is currently supported by an FRQNT (Fonds de recherche du Québec - Na
 
 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.](https://www.pnas.org/doi/abs/10.1073/pnas.2106140118)" *Proceedings of the National Academy of Sciences* 118.39 (2021): e2106140118.
-
-If your research computes spectral EWS using *ewstools*, please cite
+If your research makes use of it, please cite
 
-Bury, Thomas M., Chris T. Bauch, and Madhur Anand. "[Detecting and distinguishing tipping points using spectral early warning signals.](https://royalsocietypublishing.org/doi/full/10.1098/rsif.2020.0482)" *Journal of the Royal Society Interface* 17.170 (2020): 20200482.
+Bury, Thomas M. "[ewstools: A Python package for early warning signals of bifurcations in time series data.](https://joss.theoj.org/papers/10.21105/joss.05038.pdf)" *Journal of Open Source Software* 8.82 (2023): 5038.

codecov.yml

@@ -7,4 +7,7 @@ coverage:
       default:
         target: 60%
         threshold: 30%
+    patch:
+      default:
+        target: 80%  # new contributions should have a coverage at least equal to target
 

docs/source/conf.py

@@ -24,10 +24,9 @@
 copyright = '2022, Thomas M Bury'
 author = 'Thomas M Bury'
 
-# The short X.Y version
-version = '1.0.1'
-# The full version, including alpha/beta/rc tags
-release = '1.0.1'
+# Semantic version number
+version = '2.0.1'
+
 
 
 # -- General configuration ---------------------------------------------------

ewstools/__init__.py

@@ -8,3 +8,4 @@
 
 # Import specific classes and functions
 from .core import TimeSeries
+from .core import MultiTimeSeries