biosppy.signals.ppg

biosppy.signals.ppg

This module provides methods to process Photoplethysmogram (PPG) signals.

copyright:

  1. 2015-2026 by Instituto de Telecomunicacoes

license:

BSD 3-clause, see LICENSE for more details.

Functions

find_onsets_elgendi2013([signal, ...])

Determines onsets of PPG pulses.

find_onsets_kavsaoglu2016([signal, ...])

Determines onsets of PPG pulses.

ppg([signal, sampling_rate, units, show])

Process a raw PPG signal and extract relevant signal features using default parameters.

ppg_segmentation([signal, sampling_rate, ...])

Segments a filtered PPG signal.
biosppy.signals.ppg.find_onsets_elgendi2013(signal=None, sampling_rate=1000.0, peakwindow=0.111, beatwindow=0.667, beatoffset=0.02, mindelay=0.3)[source]

Determines onsets of PPG pulses.

Parameters:

  • signal (array) – Input filtered PPG signal.

  • sampling_rate (int, float, optional) – Sampling frequency (Hz).

  • peakwindow (float) – Parameter W1 on referenced article Optimized at 0.111

  • beatwindow (float) – Parameter W2 on referenced article Optimized at 0.667

  • beatoffset (float) – Parameter beta on referenced article Optimized at 0.2

  • mindelay (float) – Minimum delay between peaks. Avoids false positives

Returns:

  • onsets (array) – Indices of PPG pulse onsets.

  • params (dict) – Input parameters of the function

References

[Elgendi2013] (1,2)

Elgendi M, Norton I, Brearley M, Abbott D, Schuurmans D. Systolic Peak Detection in Acceleration Photoplethysmograms Measured from Emergency Responders in Tropical Conditions. PLoS ONE, 8(10):e76585, 2013. doi:10.1371/journal.pone.0076585.

Notes

Optimal ranges for signal filtering (from [Elgendi2013]): “Optimization of the beat detector’s spectral window for the lower frequency resulted in a value within 0.5– 1 Hz with the higher frequency within 7–15 Hz”

All the number references below between curly brackets {…} by the code refer to the line numbers of code in “Table 2 Algorithm IV: DETECTOR (PPG signal, F1, F2, W1, W2, b)” from [Elgendi2013] for a better comparison of the algorithm

biosppy.signals.ppg.find_onsets_kavsaoglu2016(signal=None, sampling_rate=1000.0, alpha=0.2, k=4, init_bpm=90, min_delay=0.6, max_BPM=150)[source]

Determines onsets of PPG pulses.

Parameters:

  • signal (array) – Input filtered PPG signal.

  • sampling_rate (int, float, optional) – Sampling frequency (Hz).

  • alpha (float, optional) – Low-pass filter factor. Avoids abrupt changes of BPM.

  • k (int, float, optional) – Number of segments by pulse. Width of each segment = Period of pulse according to current BPM / k

  • init_bpm (int, float, optional) – Initial BPM. Higher value results in a smaller segment width.

  • min_delay (float) – Minimum delay between peaks as percentage of current BPM pulse period. Avoids false positives

  • max_bpm (int, float, optional) – Maximum BPM. Maximum value accepted as valid BPM.

Returns:

  • onsets (array) – Indices of PPG pulse onsets.

  • window_marks (array) – Indices of segments window boundaries.

  • params (dict) – Input parameters of the function

References

[Kavsaoglu2016]

Kavsaoglu A, Polat K, Bozkurt M. An innovative peak detection algorithm for photoplethysmography signals: an adaptive segmentation method. Turkish Journal of Electrical Engineering and Computer Sciences, 24:1782-1796, 2016. doi:10.3906/elk-1310-177.

Notes

This algorithm is an adaptation of the one described in [Kavsaoglu2016]. This version takes into account a minimum delay between peaks and builds upon the adaptive segmentation by using a low-pass filter for BPM changes. This way, even if the algorithm wrongly detects a peak, the BPM value will stay relatively constant so the next pulse can be correctly segmented.

biosppy.signals.ppg.ppg(signal=None, sampling_rate=1000.0, units=None, show=True)[source]

Process a raw PPG signal and extract relevant signal features using default parameters.

Parameters:

  • signal (array) – Raw PPG signal.

  • sampling_rate (int, float, optional) – Sampling frequency (Hz).

  • units (str, optional) – The units of the input signal. If specified, the plot will have the y-axis labeled with the corresponding units.

  • show (bool, optional) – If True, show a summary plot.

Returns:

  • ts (array) – Signal time axis reference (seconds).

  • filtered (array) – Filtered PPG signal.

  • peaks (array) – Indices of PPG pulse peaks.

  • templates_ts (array) – Templates time axis reference (seconds).

  • templates (array) – Extracted heartbeat templates.

  • heart_rate_ts (array) – Heart rate time axis reference (seconds).

  • heart_rate (array) – Instantaneous heart rate (bpm).

biosppy.signals.ppg.ppg_segmentation(signal=None, sampling_rate=1000.0, peaks=None, selection=False, peak_threshold=None)[source]

Segments a filtered PPG signal. Segmentation filtering is achieved by taking into account segments selected by peak height and pulse morphology.

Parameters:

  • signal (array) – Filtered PPG signal.

  • sampling_rate (int, float, optional) – Sampling frequency (Hz).

  • peaks (array) – List of PPG systolic peaks.

  • selection (bool, optional) – If True, performs selection with peak height and pulse morphology.

  • peak_threshold (int, float, optional) – If selection is True, selects peaks with height greater than defined threshold.

Returns:

  • onsets (array) – Indices of PPG pulse onsets (i.e., start of beats) of the selected segments.

  • peaks (array) – List of PPG systolic peaks of the selected segments.

  • segments_loc (array) – Start and end indices for each selected pulse segment.