Documentation

Author: LegrandNico

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,98 +56,131 @@ 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)
-* `Seaborn <https://seaborn.pydata.org/>`_ (>=0.9.0)
 * `Numba <http://numba.pydata.org/>`_ (>=0.51.2)
+* `Seaborn <https://seaborn.pydata.org/>`_ (>=0.9.0)
 
-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)
 
-Tutorial
-========
 
-For an overview of all the recording functionalities, you can refer to the following examples:
-
-* Recording
-* Artefacts detection and artefacts correction
-* Heart rate variability
+Tutorials
+=========
 
 For an introduction to Systole and cardiac signal analysis, you can refer to the following tutorial:
 
-* Introduction to cardiac signal analysis - |Colab badge| - `Jupyter Book <https://legrandnico.github.io/Notebooks/IntroductionCardiacSignalAnalysis.html>`_ 
+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|
 
-.. |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 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
 
-Recording
-=========
+.. |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
 
-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 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
+
+.. |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
 
-Artefact correction
-===================
+.. |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
 
-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.plots 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#>`_.
 
-Systole integrates a set of functions for interactive data visualization based on `Bokeh <https://docs.bokeh.org/en/latest/index.html#>`_.
+.. code-block:: python
 
-.. figure::  https://github.com/embodied-computation-group/systole/raw/master/Images/systole.gif
-   :align:   center
+  from systole.plots plot_raw
 
-Heartrate variability
-======================
+  plot_raw(signal[60000 : 120000], modality="ecg", backend="bokeh", 
+              show_heart_rate=True, show_artefacts=True, figsize=300)
 
 .. raw:: html
-   :file: source/images/hrv.html
+   :file: source/images/raw.html
 
-.. figure:: source/images/hrv.png
 
-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 following the algorythm proposed by Lipponen & Tarvainen (2019).
 
-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.
+.. 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)
+
+  plot_subspaces(peaks, input_type="peaks", backend="bokeh")
+
+.. raw:: html
+   :file: source/images/subspaces.html
+
+Instantaneous and evoked heart rate
+===================================
+
+
+Heart rate variability analysis
+===============================
+Systole implemetns basic time-domain, frequency-domain and non-linear HRV indices.
 
 .. code-block:: python
 
-  from systole.plots import plot_frequency
+  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=(600, 400)),
+      plot_pointcare(peaks, input_type="peaks", backend="bokeh", figsize=(400, 400)),
+      )
+
+.. raw:: html
+   :file: source/images/hrv.html
+
+
+Online systolic peak detection, cardiac-stimulus synchrony, and cardiac circular analysis
+=========================================================================================
+
+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).
 
-.. figure::  https://github.com/embodied-computation-group/systole/raw/master/Images/psd.png
-   :align:   center
 
 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 ([email protected])
 - Gidon Levakov ([email protected])
 - Peter Doggart ([email protected])
 
 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.
 
@@ -158,4 +194,19 @@ Systole was largely inspired by pre-existing toolboxes dedicated to heartrate va
 
 * ECG-detector: https://github.com/berndporr/py-ecg-detectors
 
-* Pingouin: https://pingouin-stats.org/
+* Pingouin: https://pingouin-stats.org/
+
+* NeuroKit2: https://github.com/neuropsychology/NeuroKit
+
+================
+
+|AU| |lundbeck| |lab|
+
+.. |AU| image::  https://github.com/embodied-computation-group/systole/raw/dev/Images/au_clinisk_logo.png
+   :width: 100%
+
+.. |lundbeck| image::  https://github.com/embodied-computation-group/systole/raw/dev/Images/lundbeckfonden_logo.png
+   :width: 10%
+
+.. |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
++++++++++

examples/plot_ArtefactsDetection.py renamed to examples/Artefacts/plot_ArtefactsDetection.py

@@ -3,9 +3,4 @@
 Example gallery
 ===============
 
-This section demonstrates some of the basic functionality of **systole**.
-If you want to see the tutorials in action, you can also click on the link below and navigate to the ``tutorials/`` folder to launch one of the interactive Jupyter notebooks.
-
-.. contents:: Contents
-   :local:
-   :depth: 3
+This section demonstrates some of the basic functionality of **systole**.

examples/plot_PeaksCorrection.py renamed to examples/Artefacts/plot_PeaksCorrection.py

@@ -0,0 +1,2 @@
+Recording
++++++++++

examples/plot_RRCorrection.py renamed to examples/Artefacts/plot_RRCorrection.py

@@ -0,0 +1,98 @@
+"""
+Recording PPG signal
+====================
+
+The py:class:systole.recording.Oximeter class can be used to read incoming PPG signal 
+from `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/>`_. This function can easily 
+be integrated with other stimulus presentation software lie `PsychoPy
+<https://www.psychopy.org/>`_ to record cardiac activity during psychological 
+experiments, or to synchronize stimulus delivery around cardiac phases (e.g. systole or
+diastole).
+
+"""
+
+# Author: Nicolas Legrand <[email protected]>
+# Licence: GPL v3
+
+
+#%%
+# Recording PPG singal
+# --------------------
+
+from systole.recording import Oximeter
+from systole import serialSim
+#%%
+# Recording and plotting your first PPG time-series only require a few lines of code:
+# First, open a serial port. Note that here we are using Systole's PPG simulation 
+# function so the example can run without any device plugged on the computer for the
+# demonstration. If you want to connect to an actual Nonin pulse oximeter, you simply
+# have to provide the port reference it is plugged in (see commented lines below). 
+
+ser = serialSim()  # Simulate a device
+
+# Use a USB device
+#import serial
+#ser = serial.Serial("COM4")  # Use this line for USB recording
+
+#%%
+# Once the reference of the port created, you can create a recording instance, 
+# initialize it and read some incoming signal in just one line of code. 
+
+oxi = Oximeter(serial=ser).setup().read(duration=10)
+
+#%% The recording instance also interface with systole's plotting module so the signal
+# can be directly plotted using built-in functions.
+oxi.plot_raw(show_heart_rate=True, figsize=(13, 8))
+
+#%%
+# Interfacing with PsychoPy
+# -------------------------
+# One nice feature provided by Systole is that it can run the recording of PPG signal
+# together with other Python scripts like Psychopy, which can be used to build 
+# psychological experiments. There are two ways for interfacing with other scripts, it
+# can be done either in a serial or in a (pseudo-) parallel way.
+
+# - The ``read()`` method will record for a predefined amount of time
+# (specified by the ``duration`` parameter, in seconds). This 'serial mode'
+# is the easiest and most robust method, but it does not allow the execution
+# of other instructions in the meantime.
+
+# Code 1 {}
+oxi.read(duration=10)
+# Code 2 {}
+
+# - The ``readInWaiting()`` method will only read the bytes temporally stored
+# in the USB buffer. For the Nonin device, this represents up to 10 seconds of
+# recording (this procedure should be executed at least one time every 10
+# seconds for a continuous recording). When inserted into a while loop, it can
+# record PPG signal almost in parallel with other commands.
+
+import time
+tstart = time.time()
+while time.time() - tstart < 10:
+    oxi.readInWaiting()
+    # Insert code here {...}
+
+#%%
+# Online detection
+# ----------------
+# The recording instance is also detecting heartbeats automatically in the background, 
+# and this information can be accessed in real-time to deliver stimuli time-locked to 
+# specific cardiac phases. Note that the delay between the actual heartbeat and the 
+# execution of computer code (here the `print` command in the example below) can be 
+# important. Also, it is important to note that the systolic peak detected in the PPG
+# signal is delayed relative to the R peaks observed in the ECG signal.
+
+# Create an Oxymeter instance and initialize recording
+oxi = Oximeter(serial=ser, sfreq=75, add_channels=4).setup()
+
+# Online peak detection - run for 10 seconds
+tstart = time.time()
+while time.time() - tstart < 10:
+    while oxi.serial.inWaiting() >= 5:
+        paquet = list(oxi.serial.read(5))
+        oxi.add_paquet(paquet[2])  # Add new data point
+        if oxi.peaks[-1] == 1:
+            print("Heartbeat detected")