Merge pull request #17 from embodied-computation-group/dev

v0.2.0

.gitignore

@@ -1,3 +1,11 @@
 *.pyc
 *-checkpoint.ipynb
-mypyreports/
+mypyreports/
+build/
+dist/
+systole.egg-info/
+htmlcov/
+.coverage
+.vscode/
+source/auto_examples
+source/generated

.pre-commit-config.yaml

@@ -1,11 +1,11 @@
 repos:
 -   repo: https://github.com/pre-commit/mirrors-isort
-    rev: v4.3.21
+    rev: v5.9.3
     hooks:
     - id: isort
       files: ^systole/
 -   repo: https://github.com/ambv/black
-    rev: stable
+    rev: 21.9b0
     hooks:
     - id: black
       language_version: python3
@@ -16,7 +16,7 @@ repos:
     - id: flake8
       files: ^systole/
 -   repo: https://github.com/pre-commit/mirrors-mypy
-    rev: ''  # Use the sha / tag you want to point at
+    rev: 'v0.910'  # Use the sha / tag you want to point at
     hooks:
     - id: mypy 
       files: ^systole/

README.rst

@@ -33,14 +33,17 @@
 
 ================
 
-**Systole** is an open-source Python package providing simple tools to record and analyze, cardiac signals for psychophysiology.
-In particular, the package provides tools to pre-process, analyze, and synchronize cardiac data from psychophysiology research.
-This includes tools for data epoching, heart-rate variability, and synchronizing stimulus presentation with different cardiac phases via psychopy.
+**Systole** is an open-source Python package implementing simple tools for working with cardiac signals for 
+psychophysiology research. In particular, the package provides tools to pre-process, visualize, and analyze cardiac data. 
+This includes tools for data epoching, artefact detection, artefact correction, evoked heart-rate analyses, heart-rate 
+variability analyses, circular statistical approaches to analysing cardiac cycles, and synchronising stimulus 
+presentation with different cardiac phases via the psychopy.
+
 
 The documentation can be found under the following `link <https://systole-docs.github.io/>`_.
 
 Installation
-============
+++++++++++++
 
 Systole can be installed using pip:
 
@@ -53,91 +56,128 @@ The following packages are required to use Systole:
 * `Numpy <https://numpy.org/>`_ (>=1.15)
 * `SciPy <https://www.scipy.org/>`_ (>=1.3.0)
 * `Pandas <https://pandas.pydata.org/>`_ (>=0.24)
-* `Matplotlib <https://matplotlib.org/>`_ (>=3.0.2)
+* `Numba <http://numba.pydata.org/>`_ (>=0.51.2)
 * `Seaborn <https://seaborn.pydata.org/>`_ (>=0.9.0)
-* `py-ecg-detectors <https://github.com/berndporr/py-ecg-detectors>`_ (>=1.0.2)
 
-Interactive plotting functions and reports generation will also require the following packages to be installed:
+Required when using `Matplotlib` plotting backend:
+* `Matplotlib <https://matplotlib.org/>`_ (>=3.0.2)
+Required when using `Bokeh` plotting backend:
+* `Bokeh <https://docs.bokeh.org/en/latest/index.html#>`_ (>=2.3.3)
 
-* `Plotly <https://plotly.com/>`_ (>=4.8.0)
 
-Tutorial
-========
+Tutorials
+=========
 
-For an overview of all the recording functionalities, you can refer to the following examples:
+For an introduction to Systole and cardiac signal analysis, you can refer to the following tutorial:
 
-* Recording
-* Artefacts detection and artefacts correction
-* Heart rate variability
+1. Cardiac signal analysis - |Colab badge 1|
+2. Detecting cardiac cycles - |Colab badge 2|
+3. Detecting and correcting artefats - |Colab badge 3|
+4. Heart rate variability - |Colab badge 4|
+5. Instantaneous and evoked heart rate - |Colab badge 5|
 
-For an introduction to Systole and cardiac signal analysis, you can refer to the following tutorial:
+.. |Colab badge 1| image:: https://colab.research.google.com/assets/colab-badge.svg
+  :target: https://colab.research.google.com/github/embodied-computation-group/systole/blob/dev/source/notebooks/1-PhysiologicalSignals.ipynb
 
-* Introduction to cardiac signal analysis - |Colab badge| - `Jupyter Book <https://legrandnico.github.io/Notebooks/IntroductionCardiacSignalAnalysis.html>`_ 
+.. |Colab badge 2| image:: https://colab.research.google.com/assets/colab-badge.svg
+  :target: https://colab.research.google.com/github/embodied-computation-group/systole/blob/dev/source/notebooks/2-DetectingCycles.ipynb
 
-.. |Colab badge| image:: https://colab.research.google.com/assets/colab-badge.svg
-  :target: https://colab.research.google.com/github/LegrandNico/Notebooks/blob/main/IntroductionCardiacSignalAnalysis.ipynb
+.. |Colab badge 3| image:: https://colab.research.google.com/assets/colab-badge.svg
+  :target: https://colab.research.google.com/github/embodied-computation-group/systole/blob/dev/source/notebooks/3-DetectingAndCorrectingArtefacts.ipynb
 
-Recording
-=========
+.. |Colab badge 4| image:: https://colab.research.google.com/assets/colab-badge.svg
+  :target: https://colab.research.google.com/github/embodied-computation-group/systole/blob/dev/source/notebooks/4-HeartRateVariability.ipynb
 
-Systole natively supports recording of physiological signals from the following setups:
-* `Nonin 3012LP Xpod USB pulse oximeter <https://www.nonin.com/products/xpod/>`_ together with the `Nonin 8000SM 'soft-clip' fingertip sensors <https://www.nonin.com/products/8000s/>`_ (USB).
-* Remote Data Access (RDA) via BrainVision Recorder together with `Brain product ExG amplifier <https://www.brainproducts.com/>`_ (Ethernet).
+.. |Colab badge 5| image:: https://colab.research.google.com/assets/colab-badge.svg
+  :target: https://colab.research.google.com/github/embodied-computation-group/systole/blob/dev/source/notebooks/5-InstantaneousHeartRate.ipynb
 
-Artefact correction
-===================
 
-Systole implements systolic peak detection inspired by van Gent et al. (2019) [#]_ and the artefact rejection method recently proposed by Lipponen & Tarvainen (2019) [#]_.
+Getting started
++++++++++++++++
 
 .. code-block:: python
 
-  from systole import simulate_rr
-  from systole.plotting import plot_subspaces
+  from systole import import_dataset1
 
-  rr = simulate_rr()
-  plot_subspaces(rr)
+  # Import ECg recording
+  signal = import_dataset1(modalities=['ECG']).ecg.to_numpy()
 
-.. figure::  https://github.com/embodied-computation-group/systole/raw/master/Images/subspaces.png
-   :align:   center
 
-Interactive visualization
-=========================
+Signal extraction and interactive plotting
+==========================================
+The package integrates a set of functions for interactive or non interactive data visualization based on `Matplotlib <https://matplotlib.org/>`_ and `Bokeh <https://docs.bokeh.org/en/latest/index.html#>`_.
+
+.. code-block:: python
+
+  from systole.plots plot_raw
 
-Systole integrates a set of functions for interactive data visualization based on `Plotly <https://plotly.com/>`_.
+  plot_raw(signal[60000 : 120000], modality="ecg", backend="bokeh", 
+              show_heart_rate=True, show_artefacts=True, figsize=300)
 
-.. figure::  https://github.com/embodied-computation-group/systole/raw/master/Images/systole.gif
+.. figure:: https://github.com/embodied-computation-group/systole/blob/dev/source/images/raw.png
    :align:   center
 
-Heartrate variability
-======================
 
-Systole supports basic time-domain, frequency-domain and non-linear extraction indices.
+Artefacts detection and rejection
+=================================
+Artefacts can be detected and corrected in the RR interval time series or the peaks vector using the method proposed by Lipponen & Tarvainen (2019).
+
+.. code-block:: python
+
+  from systole.detection import ecg_peaks
+  from systole.plots plot_subspaces
+
+  # R peaks detection
+  signal, peaks = ecg_peaks(signal, method='pan-tompkins', sfreq=1000)
 
-All time-domain and non-linear indices have been tested against Kubios HVR 2.2 (<https://www.kubios.com>). The frequency-domain indices can slightly differ. We recommend to always check your results against another software.
+  plot_subspaces(peaks, input_type="peaks", backend="bokeh")
+
+.. figure:: https://github.com/embodied-computation-group/systole/blob/dev/source/images/subspaces.png
+   :align:   center
+
+
+Heart rate variability analysis
+===============================
+Systole implements time-domain, frequency-domain and non-linear HRV indices, as well as tools for evoked heart rate analysis.
 
 .. code-block:: python
 
-  from systole.plotting import plot_psd
+  from bokeh.layouts import row
+  from systole.plots plot_frequency, plot_pointcare
 
-  plot_psd(rr)
+  row(
+      plot_frequency(peaks, input_type="peaks", backend="bokeh", figsize=(300, 200)),
+      plot_pointcare(peaks, input_type="peaks", backend="bokeh", figsize=(200, 200)),
+      )
 
-.. figure::  https://github.com/embodied-computation-group/systole/raw/master/Images/psd.png
+.. figure:: https://github.com/embodied-computation-group/systole/blob/dev/source/images/hrv.png
    :align:   center
 
+
+Online systolic peak detection, cardiac-stimulus synchrony, and cardiac circular analysis
+=========================================================================================
+
+The package natively supports recording of physiological signals from the following setups:
+- `Nonin 3012LP Xpod USB pulse oximeter <https://www.nonin.com/products/xpod/>`_ together with the `Nonin 8000SM 'soft-clip' fingertip sensors <https://www.nonin.com/products/8000s/>`_ (USB).
+- Remote Data Access (RDA) via BrainVision Recorder together with `Brain product ExG amplifier <https://www.brainproducts.com/>`_ (Ethernet).
+
+
 Development
-===========
++++++++++++
 
 This module was created and is maintained by Nicolas Legrand and Micah Allen (ECG group, https://the-ecg.org/). If you want to contribute, feel free to contact one of the developers, open an issue or submit a pull request.
 
 This program is provided with NO WARRANTY OF ANY KIND.
 
 Contributors
-============
+++++++++++++
 
 - Jan C. Brammer (jan.c.brammer@gmail.com)
+- Gidon Levakov (gidonlevakov@gmail.com)
+- Peter Doggart (peter.doggart@pulseai.io)
 
 Acknowledgements
-================
+++++++++++++++++
 
 This software and the ECG are supported by a Lundbeckfonden Fellowship (R272-2017-4345), and the AIAS-COFUND II fellowship programme that is supported by the Marie Skłodowska-Curie actions under the European Union’s Horizon 2020 (Grant agreement no 754513), and the Aarhus University Research Foundation.
 
@@ -153,13 +193,17 @@ Systole was largely inspired by pre-existing toolboxes dedicated to heartrate va
 
 * Pingouin: https://pingouin-stats.org/
 
-References
-==========
+* NeuroKit2: https://github.com/neuropsychology/NeuroKit
+
+================
 
-**Peak detection (PPG signal)**
+|AU| |lundbeck| |lab|
 
-.. [#] van Gent, P., Farah, H., van Nes, N., & van Arem, B. (2019). HeartPy: A novel heart rate algorithm for the analysis of noisy signals. *Transportation Research Part F: Traffic Psychology and Behaviour, 66, 368–378*. https://doi.org/10.1016/j.trf.2019.09.015
+.. |AU| image::  https://github.com/embodied-computation-group/systole/raw/dev/Images/au_clinisk_logo.png
+   :width: 100%
 
-**Artefact detection and correction:**
+.. |lundbeck| image::  https://github.com/embodied-computation-group/systole/raw/dev/Images/lundbeckfonden_logo.png
+   :width: 10%
 
-.. [#] Lipponen, J. A., & Tarvainen, M. P. (2019). A robust algorithm for heart rate variability time series artefact correction using novel beat classification. *Journal of Medical Engineering & Technology, 43(3), 173–181*. https://doi.org/10.1080/03091902.2019.1640306
+.. |lab| image::  https://github.com/embodied-computation-group/systole/raw/dev/Images/LabLogo.png
+   :width: 20%

examples/Artefacts/README.txt

@@ -0,0 +1,2 @@
+Artefacts
++++++++++

source/auto_examples/plot_ArtefactsDetection.py → examples/Artefacts/plot_ArtefactsDetection.py

@@ -12,7 +12,7 @@
 
 #%%
 from systole.detection import rr_artefacts
-from systole.plotting import plot_subspaces
+from systole.plots import plot_subspaces
 from systole.utils import simulate_rr
 
 #%%
@@ -52,7 +52,7 @@
 # panel plot subspaces that will be more sensitive to long or short beats,
 # comprizing the extra and missed beats.
 
-plot_subspaces(rr)
+plot_subspaces(rr, figsize=(12, 6))
 
 #%%
 # References