/heartrate_analysis_python

Python Heart Rate Analysis Package, for both PPG and ECG signals

Primary LanguagePythonGNU General Public License v3.0GPL-3.0

HeartPy - Python Heart Rate Analysis Toolkit

DOI Build Status codecov PyPI - Python Version

Structural update

HeartPy V1.2 has landed! The structure of the package has been reworked to be in separate modules now in preparation of the next big update, which will feature many analysis expansions and the first steps towards a GUI for HeartPy. HeartPy has been growing steadily and had reached the point where it became cluttered and unwieldy to keep in a single file. The API remains unchanged.

An 'Examples' folder has been added to the repo which will be expanded soon. Now there's two notebooks explaining how to analyse ppg signals from smartwatches and smart rings.

Colorblind support has been added, see this notebook in the examples folder

Installation

python setup.py install

Alternatively, we're also on PIP:

python -m pip install heartpy

That's it! Note that Github always has the newest version.

Documentation

The official documentation is online! You can find the official documentation here

Python 2.7 support

The module compiles and and runs fine on Python 2.7, but the unit tests fail due to formatting differences in outputs between Python 2 and Python 3. You can still install and use HeartPy on Python 2.7 if you want.

Tutorial notebooks are now available in Examples/

These show how to handle various analysis tasks with HeartPy, from smartwatch data, smart ring data, regular PPG, and regular (and very noisy) ECG. The notebooks sometimes don't render through the github engine, so either open them locally, or use an online viewer like nbviewer.

We recommend you follow the notebooks in order:

More information

HeartPy, the Python Heart Rate Analysis Toolkit is a module for heart rate analysis in Python. It started as pure-python implementation to analyse physiological data taken in naturalistic driving and cycling experiments.

The module takes a discrete heart rate signal and outputs time-domain and frequency-domain measures often found in scientific literature:

Time domain:

  • beats per minute, BPM
  • interbeat interval, IBI
  • standard deviation if intervals between adjacent beats, SDNN
  • standard deviation of successive differences between adjacent R-R intervals, SDSD
  • root mean square of successive differences between adjacend R-R intervals, RMSSD
  • proportion of differences between R-R intervals greater than 20ms, 50ms, pNN20, pNN50
  • median absolute deviation, MAD
  • Poincare analysis (SD1, SD2, S, SD1/SD1)
  • Poincare plotting

Frequency domain

  • low frequency component (0.04-0.15Hz), LF
  • high frequency component (0.16-0.5Hz), HF
  • lf/hf ratio, Lf/HF

When using the package in your research, please cite:

van Gent, P., Farah, H., van Nes, N., & van Arem, B. (2018). Heart Rate Analysis for Human Factors: Development and Validation of an Open Source Toolkit for Noisy Naturalistic Heart Rate Data. In Proceedings of the 6th HUMANIST Conference (pp. 173–178).

van Gent, P., Farah, H., van Nes, N., & van Arem, B. (2019). Analysing Noisy Driver Physiology Real-Time Using Off-the-Shelf Sensors: Heart Rate Analysis Software from the Taking the Fast Lane Project. Journal of Open Research Software, 7(1), 32. DOI: http://doi.org/10.5334/jors.241

Documentation

You can find the official documentation here

The module is also to some extent described in my tutorial series:

License

The module is licensed under the GNU General Public License Version3, GPL-v3

Validation

Initial results of the validation have been reported in [1, 2]. Updates here are soon to follow once the papers are published.

[1]van Gent, P., Farah, H., van Nes, N., & van Arem, B. (2018). Heart Rate Analysis for Human Factors: Development and Validation of an Open Source Toolkit for Noisy Naturalistic Heart Rate Data. In Proceedings of the 6th HUMANIST Conference (pp. 173–178).

[2] van Gent, P. Van, Farah, H., Nes, N. Van, & Arem, B. Van. (manuscript submitted for publication). A Novel Heart Rate Algorithm for the Analysis of Noisy Signals.

To-do

The module is still in active development. See the changelog for past changes. The to-do for the coming months is:

to do before V1.3

  • Same but for PPG - morphology too variable, method unstable
  • clean_rr method now removes incorrect values, update to allow for replacement by median of surrounding data points
  • Report validation performance on repo (published paper + key-points document once published)
  • Change backend structure in anticipation of GUI development
  • Develop GUI for HeartPy