PPG#

Main#

ppg_process()#

ppg_process(ppg_signal, sampling_rate=1000, method='elgendi', report=None, **kwargs)[source]#

Process a photoplethysmogram (PPG) signal

Convenience function that automatically processes a photoplethysmogram signal.

Parameters:

ppg_signal (Union[list, np.array, pd.Series]) – The raw PPG channel.
sampling_rate (int) – The sampling frequency of ppg_signal() (in Hz, i.e., samples/second).
method (str) – The processing pipeline to apply. Can be one of "elgendi". Defaults to "elgendi".
report (str) – The filename of a report containing description and figures of processing (e.g. "myreport.html"). Needs to be supplied if a report file should be generated. Defaults to None. Can also be "text" to just print the text in the console without saving anything.
**kwargs – Other arguments to be passed to specific methods. For more information, see ppg_methods().

Returns:

signals (DataFrame) – A DataFrame of same length as ppg_signal() containing the following columns:
- "PPG_Raw": the raw signal.
- "PPG_Clean": the cleaned signal.
- "PPG_Rate": the heart rate as measured based on PPG peaks.
- "PPG_Peaks": the PPG peaks marked as “1” in a list of zeros.
info (dict) – A dictionary containing the information of peaks and the signals’ sampling rate.

See also

ppg_clean, ppg_findpeaks

Examples

In [1]: import neurokit2 as nk

In [2]: ppg = nk.ppg_simulate(duration=10, sampling_rate=1000, heart_rate=70)

In [3]: signals, info = nk.ppg_process(ppg, sampling_rate=1000)

In [4]: nk.ppg_plot(signals, info)

ppg_analyze()#

ppg_analyze(data, sampling_rate=1000, method='auto')[source]#

Photoplethysmography (PPG) Analysis.

Performs PPG analysis on either epochs (event-related analysis) or on longer periods of data such as resting-state data.

Parameters:

data (Union[dict, pd.DataFrame]) – A dictionary of epochs, containing one DataFrame per epoch, usually obtained via epochs_create(), or a DataFrame containing all epochs, usually obtained via epochs_to_df(). Can also take a DataFrame of processed signals from a longer period of data, typically generated by ppg_process() or bio_process(). Can also take a dict containing sets of separate periods of data.
sampling_rate (int) – The sampling frequency of the signal (in Hz, i.e., samples/second). Defaults to 1000Hz.
method (str) – Can be one of "event-related" for event-related analysis on epochs, or "interval-related" for analysis on longer periods of data. Defaults to "auto" where the right method will be chosen based on the mean duration of the data ("event-related" for duration under 10s).

Returns:

DataFrame – A dataframe containing the analyzed PPG features. If event-related analysis is conducted, each epoch is indicated by the Label column. See ppg_eventrelated() and ppg_intervalrelated() docstrings for details.

See also

bio_process, ppg_process, epochs_create, ppg_eventrelated, ppg_intervalrelated

Examples

In [1]: import neurokit2 as nk

# Example 1: Simulate data for event-related analysis
In [2]: ppg = nk.ppg_simulate(duration=20, sampling_rate=1000)

# Process data
In [3]: ppg_signals, info = nk.ppg_process(ppg, sampling_rate=1000)

In [4]: epochs = nk.epochs_create(ppg_signals, events=[5000, 10000, 15000],
   ...:                          epochs_start=-0.1, epochs_end=1.9)
   ...: 

# Analyze
In [5]: analyze_epochs = nk.ppg_analyze(epochs, sampling_rate=1000)

In [6]: analyze_epochs
Out[6]: 
  Label  Event_Onset  ...  PPG_Rate_Trend_Quadratic  PPG_Rate_Trend_R2
1     1         5000  ...                  0.703280           0.834346
2     2        10000  ...                  0.596680           0.966488
3     3        15000  ...                 -1.539925           0.975421

[3 rows x 12 columns]

# Example 2: Download the resting-state data
In [7]: data = nk.data("bio_resting_5min_100hz")

# Process the data
In [8]: df, info = nk.ppg_process(data["PPG"], sampling_rate=100)

# Analyze
In [9]: analyze_df = nk.ppg_analyze(df, sampling_rate=100)

In [10]: analyze_df
Out[10]: 
   PPG_Rate_Mean  HRV_MeanNN   HRV_SDNN  ...   HRV_HFD   HRV_KFD   HRV_LZC
0      86.401413  694.686775  49.380646  ...  1.834503  2.711044  0.852819

[1 rows x 92 columns]

ppg_simulate()#

ppg_simulate(duration=120, sampling_rate=1000, heart_rate=70, frequency_modulation=0.2, ibi_randomness=0.1, drift=0, motion_amplitude=0.1, powerline_amplitude=0.01, burst_number=0, burst_amplitude=1, random_state=None, random_state_distort='spawn', show=False)[source]#

Simulate a photoplethysmogram (PPG) signal

Phenomenological approximation of PPG. The PPG wave is described with four landmarks: wave onset, location of the systolic peak, location of the dicrotic notch and location of the diastolic peaks. These landmarks are defined as x and y coordinates (in a time series). These coordinates are then interpolated at the desired sampling rate to obtain the PPG signal.

Parameters:

duration (int) – Desired recording length in seconds. The default is 120.
sampling_rate (int) – The desired sampling rate (in Hz, i.e., samples/second). The default is 1000.
heart_rate (int) – Desired simulated heart rate (in beats per minute). The default is 70. Note that for the ECGSYN method, random fluctuations are to be expected to mimic a real heart rate. These fluctuations can cause some slight discrepancies between the requested heart rate and the empirical heart rate, especially for shorter signals.
frequency_modulation (float) – Float between 0 and 1. Determines how pronounced respiratory sinus arrythmia (RSA) is (0 corresponds to absence of RSA). The default is 0.3.
ibi_randomness (float) – Float between 0 and 1. Determines how much random noise there is in the duration of each PPG wave (0 corresponds to absence of variation). The default is 0.1.
drift (float) – Float between 0 and 1. Determines how pronounced the baseline drift (.05 Hz) is (0 corresponds to absence of baseline drift). The default is 1.
motion_amplitude (float) – Float between 0 and 1. Determines how pronounced the motion artifact (0.5 Hz) is (0 corresponds to absence of motion artifact). The default is 0.1.
powerline_amplitude (float) – Float between 0 and 1. Determines how pronounced the powerline artifact (50 Hz) is (0 corresponds to absence of powerline artifact). Note that powerline_amplitude > 0 is only possible if sampling_rate is >= 500. The default is 0.1.
burst_amplitude (float) – Float between 0 and 1. Determines how pronounced high frequency burst artifacts are (0 corresponds to absence of bursts). The default is 1.
burst_number (int) – Determines how many high frequency burst artifacts occur. The default is 0.
show (bool) – If True, returns a plot of the landmarks and interpolated PPG. Useful for debugging.
random_state (None, int, numpy.random.RandomState or numpy.random.Generator) – Seed for the random number generator. See for misc.check_random_state for further information.
random_state_distort ({‘legacy’, ‘spawn’}, None, int, numpy.random.RandomState or numpy.random.Generator) – Random state to be used to distort the signal. If "legacy", use the same random state used to generate the signal (discouraged as it creates dependent random streams). If "spawn", spawn independent children random number generators from the random_state argument. If any of the other types, generate independent children random number generators from the random_state_distort provided (this allows generating multiple version of the same signal distorted by different random noise realizations).

Returns:

ppg (array) – A vector containing the PPG.

See also

ecg_simulate, rsp_simulate, eda_simulate, emg_simulate

Examples

In [1]: import neurokit2 as nk

In [2]: ppg = nk.ppg_simulate(duration=40, sampling_rate=500, heart_rate=75, random_state=42)

ppg_plot()#

ppg_plot(ppg_signals, info=None, static=True)[source]#

Visualize photoplethysmogram (PPG) data

Visualize the PPG signal processing.

Parameters:

ppg_signals (DataFrame) – DataFrame obtained from ppg_process().
info (dict) – The information Dict returned by ppg_process(). Defaults to None.
static (bool) – If True, a static plot will be generated with matplotlib. If False, an interactive plot will be generated with plotly. Defaults to True.

Returns:

See ecg_plot() for details on how to access the figure, modify the size and save it.

See also

ppg_process

Examples

In [1]: import neurokit2 as nk

# Simulate data
In [2]: ppg = nk.ppg_simulate(duration=10, sampling_rate=100, heart_rate=70)

# Process signal
In [3]: signals, info = nk.ppg_process(ppg, sampling_rate=100)

# Plot
In [4]: nk.ppg_plot(signals, info)

Preprocessing#

ppg_clean()#

ppg_clean(ppg_signal, sampling_rate=1000, heart_rate=None, method='elgendi')[source]#

Clean a photoplethysmogram (PPG) signal

Prepare a raw PPG signal for systolic peak detection.

Parameters:

ppg_signal (Union[list, np.array, pd.Series]) – The raw PPG channel.
heart_rate (Union[int, float]) – The heart rate of the PPG signal. Applicable only if method is "nabian2018" to check that filter frequency is appropriate.
sampling_rate (int) – The sampling frequency of the PPG (in Hz, i.e., samples/second). The default is 1000.
method (str) – The processing pipeline to apply. Can be one of "elgendi", "nabian2018", or "none". The default is "elgendi". If "none" is passed, the raw signal will be returned without any cleaning.

Returns:

clean (array) – A vector containing the cleaned PPG.

See also

ppg_simulate, ppg_findpeaks

Examples

In [1]: import neurokit2 as nk

In [2]: import pandas as pd

In [3]: import matplotlib.pyplot as plt

# Simulate and clean signal
In [4]: ppg = nk.ppg_simulate(heart_rate=75, duration=30)

In [5]: ppg_elgendi = nk.ppg_clean(ppg, method='elgendi')

In [6]: ppg_nabian = nk.ppg_clean(ppg, method='nabian2018', heart_rate=75)

# Plot and compare methods
In [7]: signals = pd.DataFrame({'PPG_Raw' : ppg,
   ...:                         'PPG_Elgendi' : ppg_elgendi,
   ...:                         'PPG_Nabian' : ppg_nabian})
   ...: 

In [8]: signals.plot()
Out[8]: <Axes: >

References

Nabian, M., Yin, Y., Wormwood, J., Quigley, K. S., Barrett, L. F., & Ostadabbas, S. (2018). An open-source feature extraction tool for the analysis of peripheral physiological data. IEEE Journal of Translational Engineering in Health and Medicine, 6, 1-11.

ppg_peaks()#

ppg_peaks(ppg_cleaned, sampling_rate=1000, method='elgendi', correct_artifacts=False, show=False, **kwargs)[source]#

Find systolic peaks in a photoplethysmogram (PPG) signal

Find the peaks in an PPG signal using the specified method. You can pass an unfiltered PPG signals as input, but typically a filtered PPG (cleaned using ppg_clean()) will result in better results.

Note

Please help us improve the methods’ documentation and features.

Parameters:

ppg_cleaned (Union[list, np.array, pd.Series]) – The cleaned PPG channel as returned by ppg_clean().
sampling_rate (int) – The sampling frequency of ppg_cleaned (in Hz, i.e., samples/second). Defaults to 1000.
method (str) – The processing pipeline to apply. Can be one of "elgendi", "bishop". The default is "elgendi".
correct_artifacts (bool) – Whether or not to identify and fix artifacts, using the method by Lipponen & Tarvainen (2019).
show (bool) – If True, will show a plot of the signal with peaks. Defaults to False.
**kwargs – Additional keyword arguments, usually specific for each method.

Returns:

signals (DataFrame) – A DataFrame of same length as the input signal in which occurrences of R-peaks marked as 1 in a list of zeros with the same length as ppg_cleaned. Accessible with the keys "PPG_Peaks".
info (dict) – A dictionary containing additional information, in this case the samples at which R-peaks occur, accessible with the key "PPG_Peaks", as well as the signals’ sampling rate, accessible with the key "sampling_rate".

See also

ppg_clean, ppg_fixpeaks, signal_fixpeaks

Examples

In [1]: import neurokit2 as nk

In [2]: import numpy as np

In [3]: ppg = nk.ppg_simulate(heart_rate=75, duration=20, sampling_rate=50)

In [4]: ppg[400:600] = ppg[400:600] + np.random.normal(0, 1.25, 200)

# Default method (Elgendi et al., 2013)
In [5]: peaks, info = nk.ppg_peaks(ppg, sampling_rate=100, method="elgendi", show=True)

In [6]: info["PPG_Peaks"]
Out[6]: 
array([ 49,  91, 133, 174, 219, 265, 305, 350, 408, 447, 526, 576, 632,
       669, 705, 742, 776, 815, 849, 889, 926, 965])

# Method by Bishop et al., (2018)
In [7]: peaks, info = nk.ppg_peaks(ppg, sampling_rate=100, method="bishop", show=True)

# Correct artifacts
In [8]: peaks, info = nk.ppg_peaks(ppg, sampling_rate=100, correct_artifacts=True, show=True)

References

Elgendi, M., Norton, I., Brearley, M., Abbott, D., & Schuurmans, D. (2013). Systolic peak detection in acceleration photoplethysmograms measured from emergency responders in tropical conditions. PloS one, 8(10), e76585.
Bishop, S. M., & Ercole, A. (2018). Multi-scale peak and trough detection optimised for periodic and quasi-periodic neuroscience data. In Intracranial Pressure & Neuromonitoring XVI (pp. 189-195). Springer International Publishing.

Analysis#

ppg_eventrelated()#

ppg_eventrelated(epochs, silent=False)[source]#

Performs event-related PPG analysis on epochs

Parameters:

epochs (Union[dict, pd.DataFrame]) – A dict containing one DataFrame per event/trial, usually obtained via epochs_create(), or a DataFrame containing all epochs, usually obtained via epochs_to_df().
silent (bool) – If True, silence possible warnings.

Returns:

DataFrame – A dataframe containing the analyzed PPG features for each epoch, with each epoch indicated by the Label column (if not present, by the Index column). The analyzed features consist of the following:

"PPG_Rate_Baseline": the baseline heart rate (at stimulus onset).
"PPG_Rate_Max": the maximum heart rate after stimulus onset.
"PPG_Rate_Min": the minimum heart rate after stimulus onset.
"PPG_Rate_Mean": the mean heart rate after stimulus onset.
"PPG_Rate_SD": the standard deviation of the heart rate after stimulus onset.
"PPG_Rate_Max_Time": the time at which maximum heart rate occurs.
"PPG_Rate_Min_Time": the time at which minimum heart rate occurs.

We also include the following experimental features related to the parameters of a quadratic model:

"PPG_Rate_Trend_Linear": The parameter corresponding to the linear trend.
"PPG_Rate_Trend_Quadratic": The parameter corresponding to the curvature.
"PPG_Rate_Trend_R2": the quality of the quadratic model. If too low, the parameters might not be reliable or meaningful.

See also

events_find, epochs_create, ppg_process

Examples

In [1]: import neurokit2 as nk

# Example with simulated data
In [2]: ppg, info = nk.ppg_process(nk.ppg_simulate(duration=20))

# Process the data
In [3]: epochs = nk.epochs_create(ppg, events=[5000, 10000, 15000],
   ...:                          epochs_start=-0.1, epochs_end=1.9)
   ...: 

In [4]: nk.ppg_eventrelated(epochs)
Out[4]: 
  Label  Event_Onset  ...  PPG_Rate_Trend_Quadratic  PPG_Rate_Trend_R2
1     1         5000  ...                 -2.081449           0.743644
2     2        10000  ...                 -7.564859           0.810766
3     3        15000  ...                  1.140701           0.829557

[3 rows x 12 columns]

ppg_intervalrelated()#

ppg_intervalrelated(data, sampling_rate=1000)[source]#

Performs PPG analysis on longer periods of data (typically > 10 seconds), such as resting-state data

Parameters:

data (Union[dict, pd.DataFrame]) – A DataFrame containing the different processed signal(s) as different columns, typically generated by ppg_process(). Can also take a dict containing sets of separately processed DataFrames.
sampling_rate (int) – The sampling frequency of the signal (in Hz, i.e., samples/second).

Returns:

DataFrame – A dataframe containing the analyzed PPG features. The analyzed features consist of the following:

"PPG_Rate_Mean": the mean heart rate.
"HRV": the different heart rate variability metrices.

See hrv() docstrings for details.

See also

ppg_process

Examples

In [1]: import neurokit2 as nk

# Download data
In [2]: data = nk.data("bio_resting_5min_100hz")

# Process the data
In [3]: df, info = nk.ppg_process(data["PPG"], sampling_rate=100)

# Single dataframe is passed
In [4]: nk.ppg_intervalrelated(df, sampling_rate=100)
Out[4]: 
   PPG_Rate_Mean  HRV_MeanNN   HRV_SDNN  ...   HRV_HFD   HRV_KFD   HRV_LZC
0      86.401413  694.686775  49.380646  ...  1.834503  2.711044  0.852819

[1 rows x 92 columns]

In [5]: epochs = nk.epochs_create(df, events=[0, 15000], sampling_rate=100,
   ...:                           epochs_end=150)
   ...: 

In [6]: nk.ppg_intervalrelated(epochs)
Out[6]: 
  Label  PPG_Rate_Mean  HRV_MeanNN  ...   HRV_HFD   HRV_KFD   HRV_LZC
1     1      86.483842   69.395349  ...  1.808904  2.306391  0.792838
2     2      86.318983   69.488372  ...  1.867149  3.207983  0.973029

[2 rows x 93 columns]

Miscellaneous#

ppg_findpeaks()#

ppg_findpeaks(ppg_cleaned, sampling_rate=1000, method='elgendi', show=False, **kwargs)[source]#

Find systolic peaks in a photoplethysmogram (PPG) signal

Low-level function used by ppg_peaks() to identify peaks in a PPG signal using a different set of algorithms. Use the main function and see its documentation for details.

Parameters:

ppg_cleaned (Union[list, np.array, pd.Series]) – The cleaned PPG channel as returned by ppg_clean().
sampling_rate (int) – The sampling frequency of the PPG (in Hz, i.e., samples/second). The default is 1000.
method (str) – The processing pipeline to apply. Can be one of "elgendi", "bishop". The default is "elgendi".
show (bool) – If True, returns a plot of the thresholds used during peak detection. Useful for debugging. The default is False.

Returns:

info (dict) – A dictionary containing additional information, in this case the samples at which systolic peaks occur, accessible with the key "PPG_Peaks".

See also

ppg_simulate, ppg_clean

Examples

In [1]: import neurokit2 as nk

In [2]: import matplotlib.pyplot as plt

In [3]: ppg = nk.ppg_simulate(heart_rate=75, duration=20, sampling_rate=50)

In [4]: ppg_clean = nk.ppg_clean(ppg, sampling_rate=50)

In [5]: peaks = nk.ppg_findpeaks(ppg_clean, sampling_rate=100, show=True)

# Method by Bishop et al., (2018)
In [6]: peaks = nk.ppg_findpeaks(ppg, method="bishop", show=True)

References

Elgendi, M., Norton, I., Brearley, M., Abbott, D., & Schuurmans, D. (2013). Systolic peak detection in acceleration photoplethysmograms measured from emergency responders in tropical conditions. PloS one, 8(10), e76585.
Bishop, S. M., & Ercole, A. (2018). Multi-scale peak and trough detection optimised for periodic and quasi-periodic neuroscience data. In Intracranial Pressure & Neuromonitoring XVI (pp. 189-195). Springer International Publishing.

Any function appearing below this point is not explicitly part of the documentation and should be added. Please open an issue if there is one.

Submodule for NeuroKit.

ppg_methods(sampling_rate=1000, method='elgendi', method_cleaning='default', method_peaks='default', **kwargs)[source]#

PPG Preprocessing Methods

This function analyzes and specifies the methods used in the preprocessing, and create a textual description of the methods used. It is used by ppg_process() to dispatch the correct methods to each subroutine of the pipeline and ppg_report() to create a preprocessing report.

Parameters:

sampling_rate (int) – The sampling frequency of the raw PPG signal (in Hz, i.e., samples/second).
method (str) – The method used for cleaning and peak finding if "method_cleaning" and "method_peaks" are set to "default". Can be one of "elgendi". Defaults to "elgendi".
method_cleaning (str) – The method used to clean the raw PPG signal. If "default", will be set to the value of "method". Defaults to "default". For more information, see the "method" argument of ppg_clean().
method_peaks (str) – The method used to find peaks. If "default", will be set to the value of "method". Defaults to "default". For more information, see the "method" argument of ppg_findpeaks().
**kwargs – Other arguments to be passed to ppg_clean() and ppg_findpeaks().

Returns:

report_info (dict) – A dictionary containing the keyword arguments passed to the cleaning and peak finding functions, text describing the methods, and the corresponding references.

Examples

In [1]: import neurokit2 as nk

In [2]: methods = nk.ppg_methods(sampling_rate=100, method="elgendi", method_cleaning="nabian2018")

In [3]: print(methods["text_cleaning"])
 was preprocessed using a lowpass filter (with a cutoff frequency of 40 Hz, butterworth 2nd order; following Nabian et al., 2018).

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

ppg_segment(ppg_cleaned, peaks=None, sampling_rate=1000, show=False, **kwargs)[source]#

Segment an PPG signal into single heartbeats

Segment a PPG signal into single heartbeats. Convenient for visualizing all the heart beats.

Parameters:

ppg_cleaned (Union[list, np.array, pd.Series]) – The cleaned PPG channel as returned by ppg_clean().
peaks (dict) – The samples at which the R-peaks occur. Dict returned by ppg_peaks(). Defaults to None.
sampling_rate (int) – The sampling frequency of ppg_cleaned (in Hz, i.e., samples/second). Defaults to 1000.
show (bool) – If True, will return a plot of heartbeats. Defaults to False.
**kwargs – Other arguments to be passed.

Returns:

dict – A dict containing DataFrames for all segmented heartbeats.

See also

ppg_clean, ppg_plot

Examples

In [1]: import neurokit2 as nk

In [2]: ppg = nk.ppg_simulate(duration=30, sampling_rate=100, heart_rate=80)

In [3]: ppg_epochs = nk.ppg_segment(ppg, sampling_rate=100, show=True)

PPG

Contents

PPG#

Main#

ppg_process()#

ppg_analyze()#

ppg_simulate()#

ppg_plot()#

Preprocessing#

ppg_clean()#

ppg_peaks()#

Analysis#

ppg_eventrelated()#

ppg_intervalrelated()#

Miscellaneous#

ppg_findpeaks()#