Metadata-Version: 2.1
Name: pyPPG
Version: 1.0.24
Summary: pyPPG: a python toolbox for PPG morphological analysis.
Home-page: https://github.com/godamartonaron/GODA_pyPPG
Author: Marton A. Goda, PhD; Peter H. Charlton
Author-email: marton.goda@campus.technion.ac.il
Project-URL: Bug Tracker, https://github.com/pypa/sampleproject/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
License-File: AUTHORS.rst
Requires-Dist: scipy (==1.9.1)
Requires-Dist: numpy (==1.23.2)
Requires-Dist: dotmap (==1.3.30)
Requires-Dist: pandas (==1.4.4)
Requires-Dist: wfdb (==3.4.0)
Requires-Dist: mne (==0.23.4)
Requires-Dist: Eel (==0.14.0)
Requires-Dist: Jinja2 (==3.1.2)
Requires-Dist: MarkupSafe (==2.1.1)
Requires-Dist: Pillow (==9.2.0)
Requires-Dist: altgraph (==0.17.3)
Requires-Dist: appdirs (==1.4.4)
Requires-Dist: attrs (==22.1.0)
Requires-Dist: auto-py-to-exe (==2.23.1)
Requires-Dist: boltons (==21.0.0)
Requires-Dist: bottle (==0.12.23)
Requires-Dist: bottle-websocket (==0.2.9)
Requires-Dist: certifi (==2022.9.24)
Requires-Dist: cffi (==1.15.1)
Requires-Dist: chardet (==5.0.0)
Requires-Dist: charset-normalizer (==2.1.1)
Requires-Dist: colorama (==0.4.5)
Requires-Dist: contourpy (==1.0.5)
Requires-Dist: cycler (==0.11.0)
Requires-Dist: decorator (==5.1.1)
Requires-Dist: dotteddict (==2016.3.11)
Requires-Dist: face (==20.1.1)
Requires-Dist: fonttools (==4.37.1)
Requires-Dist: future (==0.18.2)
Requires-Dist: gevent (==21.12.0)
Requires-Dist: gevent-websocket (==0.10.1)
Requires-Dist: glom (==22.1.0)
Requires-Dist: greenlet (==1.1.3)
Requires-Dist: heartpy (==1.2.7)
Requires-Dist: idna (==3.4)
Requires-Dist: joblib (==1.2.0)
Requires-Dist: kiwisolver (==1.4.4)
Requires-Dist: matplotlib (==3.6.1)
Requires-Dist: mpldatacursor (==0.7.1)
Requires-Dist: packaging (==21.3)
Requires-Dist: parallel-map (==0.2.1)
Requires-Dist: patsy (==0.5.3)
Requires-Dist: pefile (==2022.5.30)
Requires-Dist: pip (==21.3.1)
Requires-Dist: pooch (==1.6.0)
Requires-Dist: pycparser (==2.21)
Requires-Dist: pyinstaller (==5.5)
Requires-Dist: pyinstaller-hooks-contrib (==2022.10)
Requires-Dist: pyparsing (==3.0.9)
Requires-Dist: python-dateutil (==2.8.2)
Requires-Dist: pytz (==2022.4)
Requires-Dist: pywin32-ctypes (==0.2.0)
Requires-Dist: requests (==2.28.1)
Requires-Dist: scikit-learn (==1.1.3)
Requires-Dist: setuptools (==60.2.0)
Requires-Dist: six (==1.16.0)
Requires-Dist: soundfile (==0.11.0)
Requires-Dist: statsmodels (==0.13.2)
Requires-Dist: threadpoolctl (==3.1.0)
Requires-Dist: tqdm (==4.64.1)
Requires-Dist: urllib3 (==1.26.12)
Requires-Dist: wheel (==0.37.1)
Requires-Dist: whichcraft (==0.6.1)
Requires-Dist: zope.event (==4.5.0)
Requires-Dist: zope.interface (==5.4.0)


# *pyPPG* toolbox documentation

A toolbox for photoplethysmogram (PPG) analysis, including beat detection, fiducial point detection, and comprehensive assessment of standard biomarkers.

If you use the pyPPG resource, please cite:

_Goda M, Charlton PH, and Behar J, **'pyPPG: A Python toolbox for comprehensive
photoplethysmography signal analysis'**, [Under review]_

## Introduction
***pyPPG*** is a standardised toolbox to analyze long-term finger PPG recordings in real-time. The toolbox extracts state-of-the-art PPG biomarkers (_i.e._ pulse wave features) from PPG signals. The algorithms implemented in the *pyPPG* toolbox have been validated on freely available PPG databases.
Consequently, *pyPPG* offers robust and comprehensive assessment of clinically relevant biomarkers from continuous PPG signals.

## Description
The following steps are implemented in the ***pyPPG*** toolbox:

1. **Loading a raw PPG signal**: The toolbox can accept PPG signals in various file formats such as *.mat*, *.txt*, *.csv*, or *.edf*. These files should contain raw PPG data along with the corresponding sampling rate.
   * *.mat*: Data should be stored in two variables within the file: (i) 'Fs' representing the sampling frequency, and (ii) 'Data', a vector containing the raw PPG signal.
   * *.txt*: The raw PPG signal should be stored in tabular form (single tab or space-delimited), and you need to provide the sampling frequency as an input parameter to the script using 'fs'.
   * *.csv*: This format stores raw PPG signal data with comma separation. Similar to .txt, the sampling frequency must be provided as an input parameter to the script using 'fs'.
   * *.edf*: The [European Data Format](https://www.edfplus.info/) is supported, and it applies 'Pleth' channel by default. However, if using a different channel name, then the user needs to define it themselves.
3. **Preprocessing**: The raw signal is filtered to remove unwanted noise and artifacts. Subsequently, the signal is resampled to 75 Hz.
3. **Pulse wave segmentation**: The toolbox employs a peak detector to identify the systolic peaks. It uses an [improved version](https://arxiv.org/abs/2307.10398) of a beat detection algorithm originally proposed in [(*Aboy et al. 2005*)](https://doi.org/10.1109/TBME.2005.855725). Based on the peak locations, the toolbox also detects the pulse onsets and offsets, which indicate the start and end of the PPG pulse waves.
4. **Fiducial points identification**: For each pulse wave, the toolbox detects a set of fiducial points.
5. **Biomarker engineering**: Based on the fiducial points, a set of 74 PPG digital biomarkers (_i.e._ pulse wave features) are calculated.

The *pyPPG* toolbox also provides an optional PPG signal quality index based on the Matlab implementation of the work by [(*Li et al. 2015*)](https://github.com/MIT-LCP/PhysioNetChallengePublic/blob/master/2015/sample-submission/ppgSQI.m).

![](figs/pyPPG_pipeline.svg)

The toolbox identifies individual pulse waves in a PPG signal by identifying ***systolic peaks (sp)***, and then
identifying the ***pulse onset (on)*** and ***offset (off)*** on either side of each systolic peak which indicate the
start and end of the pulse wave, respectively.

![](figs/PPG_sample.svg)

## Installation
Available on pip, with the command:
***pip install pyPPG***

pip project: https://pypi.org/project/pyPPG/

For more details see the [pyPPG example code](https://pyppg.readthedocs.io/en/latest/tutorials/pyPPG_example.html)

## Requirements
### Python Requirements:

Python >= 3.10

scipy == 1.9.1

numpy == 1.23.2

dotmap == 1.3.30

pandas == 1.5.0

wfdb == 4.0.0

mne == 1.2.0

All the python requirements are installed when the toolbox is installed, so there is no need for any additional commands.

## Documentation:
https://pyppg.readthedocs.io/en/latest/

## The main components:
1. **Software**
    - An open-source algorithmic ***pyPPG*** toolbox, which loads a PPG signal, preprocesses it, segments individual pulse waves, identifies fiducial points, and calculates a set of biomarkers. This can be used within your own data analysis code using the ***pyPPG*** API.
2. **Databases**
    - The ***pyPPG*** signal analysis is based on the following datasets:
      - [BIDMC Dataset](https://physionet.org/content/bidmc/1.0.0/)
      - [MESA Dataset](https://sleepdata.org/datasets/mesa)
    - Further PPG datasets:
      - [Collection of Peter Charlton](https://peterhcharlton.github.io/post/ppg_datasets/)
      - [Collection of Physionet](https://physionet.org/content/?topic=ppg)

All PPG measures can be further adapted for the analysis for efficient heart rate measurement as well as health assessment with clinically relevant biomarkers.

## Acknowledgments

This work was supported by the Estate of Zofia (Sophie) Fridman and funding from the Israel Innovation Authority, and the British Heart Foundation (grant FS/20/20/34626).
