- 📌Note:
Starting from v0.3.1 the development and maintenance of the package has been moved to this repository. The package is available on PyPI and can be installed using pip the same way.
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 Psychopy.
The documentation can be found under the following link.
If you have questions, you can ask them in the discussion section of this repository.
How to cite?
If you are using Systole in a publication we ask you to cite the following paper:
Legrand et al., (2022). Systole: A python package for cardiac signal synchrony and analysis. Journal of Open Source Software, 7(69), 3832, https://doi.org/10.21105/joss.03832
Installation
Systole can be installed using pip:
pip install systoleThe following packages are required to use Systole:
Numpy (>=1.21,<=1.26)
SciPy (>=1.3.0)
Pandas (>=0.24)
Numba (>=0.58.0)
Seaborn (>=0.9.0)
Matplotlib (>=3.0.2)
Bokeh (>=3.0.0)
pyserial (>=3.4)
setuptools (>=38.4)
requests (>=2.26.0)
tabulate (>=0.8.9)
The Python version should be 3.7 or higher.
Tutorials
For an introduction to Systole and cardiac signal analysis, you can refer to the following tutorial:
Cardiac signal analysis |
|
Detecting cardiac cycles |
|
Detecting and correcting artefats |
|
Heart rate variability |
|
Instantaneous and evoked heart rate |
|
Working with BIDS folders |
Getting started
from systole import import_dataset1
# Import ECg recording
signal = import_dataset1(modalities=['ECG']).ecg.to_numpy()Signal extraction and interactive plotting
The package integrates a set of functions for interactive or non interactive data visualization based on Matplotlib and Bokeh.
from systole.plots import plot_raw
plot_raw(signal[60000 : 120000], modality="ecg", backend="bokeh",
show_heart_rate=True, show_artefacts=True, figsize=300)
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).
from systole.detection import ecg_peaks
from systole.plots import plot_subspaces
# R peaks detection
signal, peaks = ecg_peaks(signal, method='pan-tompkins', sfreq=1000)
plot_subspaces(peaks, input_type="peaks", backend="bokeh")
Heart rate variability analysis
Systole implements time-domain, frequency-domain and non-linear HRV indices, as well as tools for evoked heart rate analysis.
from bokeh.layouts import row
from systole.plots import plot_frequency, plot_poincare
row(
plot_frequency(peaks, input_type="peaks", backend="bokeh", figsize=(300, 200)),
plot_poincare(peaks, input_type="peaks", backend="bokeh", figsize=(200, 200)),
)
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 together with the Nonin 8000SM ‘soft-clip’ fingertip sensors (USB).
Remote Data Access (RDA) via BrainVision Recorder together with Brain product ExG amplifier (Ethernet).
As of version 0.3.1, the package also includes a class to support the Nonin 3231 USB.
Interactive visualization of BIDS structured datasets
from systole.viewer import Viewer
view = Viewer(
input_folder="/BIDS/folder/path/",
pattern="task-mytask",
modality="beh",
signal_type="ECG"
)
Inserting and removing peaks
Annotating bad segments
Development
This repository is a fork of the original Systole repository and is maintained by Nicolas Legrand. 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.
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.
Systole was largely inspired by pre-existing toolboxes dedicated to heartrate variability and signal analysis.
HeartPy: https://python-heart-rate-analysis-toolkit.readthedocs.io/en/latest/
ECG-detector: https://github.com/berndporr/py-ecg-detectors
Pingouin: https://pingouin-stats.org/
NeuroKit2: https://github.com/neuropsychology/NeuroKit
1 maintainer
Metadata
1 maintainer
Release files for systole 0.3.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| systole-0.3.1.tar.gz | 5.8 MB | Details |
Release files / systole-0.3.1.tar.gz
| Download URL | systole-0.3.1.tar.gz |
|---|---|
| Size | 5.8 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9bc145f7b87caa57b53e45f34276bcfefec101bc1c662e4e104f53fdfa5a405a
|
|
BLAKE2b-256 checksum How to use checksums |
dbf191738b0927b1055f2efc7afbac8233493b32d7c3dd943eb80a7e715c21d0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 7, 2025.
Transparency log
