pyPPG package
pyPPG.example
- pyPPG.example.ppg_example(data_path='', fs=0, start_sig=0, end_sig=-1, fiducials=Empty DataFrame Columns: [] Index: [], process_type='both', channel='Pleth', filtering=True, fL=0.5000001, fH=12, order=4, sm_wins={'apg': 10, 'jpg': 10, 'ppg': 50, 'vpg': 10}, correction=Empty DataFrame Columns: [] Index: [], plotfig=True, savingfolder='temp_dir', savefig=True, show_fig=True, savingformat='both', print_flag=True, use_tk=False, check_ppg_len=True, saved_fiducials='', savedata=True)[source]
- This is an example code for PPG analysis. The main parts:
Loading a raw PPG signal: various file formats such as .mat, .csv, .txt, or .edf.
Get Fiducial points: extract the fiducial points of PPG, PPG’, PPG’’ and PPG’” signals
Plot Fiducial Points
- Get Biomarkers: extract 74 PPG biomarkers in four categories:
PPG signal
Signal ratios
PPG derivatives
Derivatives ratios
Get Statistics: summary of the 74 PPG biomarkers
SQI calculation: calculates the PPG Signal Quality Index
Save data: save the extracted Fiducial points, Biomarkers, and Statistics into .csv file
- Parameters:
data_path (str) – path of the PPG signal
fs (int) – sampling_frequency
start_sig (int) – beginning the of signal in sample
end_sig (int) – end of the signal in sample
fiducials (pyPPG.Fiducials DataFrame) – DataFrame of the fiducial points
process_type (str) – the type of the process, which can be “fiducials”, “biomarkers”, or “both”
channel (channel of the .edf file) – channel of the .edf file
filtering (bool) – a bool for filtering
fL (float) – Lower cutoff frequency (Hz)
fH (float) – Upper cutoff frequency (Hz)
order (int) – Filter order
sm_wins (dict) – dictionary of smoothing windows in millisecond: - ppg: window for PPG signal - vpg: window for PPG’ signal - apg: window for PPG” signal - jpg: window for PPG’” signal
correction (DataFrame) – DataFrame where the key is the name of the fiducial points and the value is bool
plotfig (bool) – a bool for plot figure
savingfolder (str) – location of the saved data
savefig (bool) – a bool for current figure saving
show_fig (bool) – a bool for show figure
savingformat (str) – file format of the saved date, the provided file formats .mat, .csv, or both
print_flag (bool) – a bool for print message
use_tk (bool) – a bool for using tkinter interface
check_ppg (bool) – a bool for checking ppg length and sampling frequency
saved_fiducials (str) – path of the file of the saved fiducial points
savedata (bool) – a bool for saving data
- Returns:
file_names: dictionary of the saved file names
Example:
from pyPPG.example import ppg_example # run example code ppg_example()
pyPPG
- class pyPPG.PPG(s={}, check_ppg_len=True)[source]
Bases:
object
This is class for the input PPG parameters.
- Parameters:
s (DotMap) –
dictionary of the PPG signal:
s.start_sig: beginning of the signal in sample
s.end_sig: end of the signal in sample
s.v: a vector of PPG values
s.fs: the sampling frequency of the PPG in Hz
s.name: name of the record
s.v: 1-d array, a vector of raw PPG values
s.fs: the sampling frequency of the PPG in Hz
s.ppg: 1-d array, a vector of the filtered PPG values
s.vpg: 1-d array, a vector of the filtered PPG’ values
s.apg: 1-d array, a vector of the filtered PPG” values
s.jpg: 1-d array, a vector of the filtered PPG’” values
s.filtering: a bool for filtering
s.fL: Lower cutoff frequency (Hz)
s.fH: Upper cutoff frequency (Hz)
s.order: Filter order
- s.sm_wins: dictionary of smoothing windows in millisecond:
ppg: window for PPG signal
vpg: window for PPG’ signal
apg: window for PPG” signal
jpg: window for PPG’” signal
s.correction: DataFrame where the key is the name of the fiducial points and the value is bool
check_ppg_len (bool) – a bool for checking ppg length and sampling frequency
- class pyPPG.Fiducials(fp: DataFrame)[source]
Bases:
object
This is class for the PPG fiducial points.
- Parameters:
fiducials (DataFrame) –
DataFrame where the key is the name of the fiducial points and the value is the list of fiducial points PPG Fiducials Points
PPG signal (fp.on, fp.sp, fp.dn, fp.dp): List of pulse onset, systolic peak, dicrotic notch, diastolic peak
1st derivative (fp.u, fp.v, fp.w): List of points of 1st maximum and minimum in 1st derivitive between the onset to onset intervals
2nd derivative (fp.a, fp.b, fp.c, fp.d, fp.e, fp.f): List of maximum and minimum points in 2nd derivitive between the onset to onset intervals
3rd derivative (fp.p1, fp.p2): List of points of 1st maximum and minimum in 3rd derivitive between the onset to onset intervals
- class pyPPG.Biomarkers(bm_defs={}, bm_vals={}, bm_stats={})[source]
Bases:
object
This is class for the PPG biomarkers.
- This class constitutes a comprehensive dictionary encompassing biomarker definitions, values, and statistics. Each dictionary is organized into the subsequent subdirectories:
ppg_sig: description for the PPG signal
sig_ratios: description for the Signal ratios
ppg_derivs: description for the PPG derivatives
derivs_ratios: description for the Derivatives ratios
- Parameters:
bm_defs (dict) – dictionary with name, definition and unit of biomarkers in different categories:
bm_vals (dict) – dictionary with values of biomarkers in different categories:
bm_stats (dict) – data frame with summary of PPG features
pyPPG.preproc
- class pyPPG.preproc.Preprocess(fL=0.5000001, fH=12, order=4, sm_wins={'apg': 10, 'jpg': 10, 'ppg': 50, 'vpg': 10})[source]
Bases:
object
The purpose of the Preprocess class is to filter and calculate the PPG, PPG’, PPG”, and PPG’” signals.
- Parameters:
fL (float) – Lower cutoff frequency (Hz)
fH (float) – Upper cutoff frequency (Hz)
order (int) – Filter order
sm_wins (dict) – dictionary of smoothing windows in millisecond: - ppg: window for PPG signal - vpg: window for PPG’ signal - apg: window for PPG” signal - jpg: window for PPG’” signal
- get_signals(s: DotMap)[source]
This function calculates the preprocessed PPG, PPG’, PPG”, and PPG’” signals.
- Parameters:
s (DotMap) – a struct of PPG signal: - s.v: a vector of PPG values - s.fs: the sampling frequency of the PPG in Hz - s.filtering: a bool for filtering
- Returns:
ppg, vpg, apg, jpg: preprocessed PPG, PPG’, PPG”, and PPG’”
pyPPG.fiducials
- class pyPPG.fiducials.FpCollection(s: PPG)[source]
The purpose of the FiducialPoints class is to calculate the fiducial points.
- Parameters:
s (pyPPG.PPG object) – object of PPG signal
- get_fiducials(s: PPG)[source]
- This function calculates the PPG Fiducial Points.
Original signal: List of systolic peak, pulse onset, dicrotic notch, and diastolic peak
1st derivative: List of points of 1st maximum and minimum in 1st derivitive between the onset to onset intervals (u,v)
2nd derivative: List of maximum and minimum points in 2nd derivitive between the onset to onset intervals (a, b, c, d, e)
- Parameters:
s (pyPPG.PPG object) – object of PPG signal
- Returns:
fiducial points: DataFrame where the key is the name of the fiducial pints and the value is the list of fiducial points
pyPPG.biomarkers
- class pyPPG.biomarkers.BmCollection(s: PPG, fp: Fiducials)[source]
Bases:
object
The purpose of the Biomarkers class is to calculate the PPG biomarkers.
- Parameters:
s (pyPPG.PPG object) – object of PPG signal
fp (pyPPG.Fiducials object) – object of fiducial points
- get_biomarkers(get_stat=True)[source]
This function retrieves the list of biomarkers, computes their values, and calculates associated statistics.
- Parameters:
get_stat (bool) – a bool for calculating the statistics of biomarkers
- Returns:
bm_defs: dictionary of biomarkers with name, definition and unit
bm_vals: dictionary of biomarkers with values
bm_stats: dictionary of biomarkers with statistics
pyPPG.ppg_sqi
- pyPPG.ppg_sqi.get_ppgSQI(ppg: list, fs: int, annotation: list)[source]
PPG Signal Quality Index based on beat template correlation.
- Parameters:
ppg (int) – a vector of PPG values
fs (int) – Samples frequency
annotation (list) – PPG annotation time(samples)
- Returns:
psqi: PPG Signal Quality Index
Reference:
Original Matlab implementation: Qiao Li, November 10, 2014.
Python implementation: Márton Áron Goda, PhD, November 11, 2022.
- pyPPG.ppg_sqi.use_template(wave, annotation: list, fs: int)[source]
PPG waveform template creation. Written by Qiao Li, February 21, 2011
- Parameters:
wave – a vector of PPG wave
fs (int) – Samples frequency
annotation – PPG annotation time(sample)
- Returns:
template: PPG waveform template based on normal - length beats
valid: 1 for valid template, 0 for invalid template
pyPPG.datahandling
- pyPPG.datahandling.load_data(data_path='', fs=nan, start_sig=0, end_sig=-1, channel='Pleth', use_tk=True, print_flag=True)[source]
Load raw PPG data.
- Parameters:
data_path (str) – path of the file containing the PPG signal
start_sig (int) – the first sample of the signal to be analysed
fs (int) – the sampling frequency of the PPG in Hz
end_sig (int) – the last sample of the signal to be analysed
channel (channel of the .edf file) – channel of the .edf file
use_tk (bool) – a bool for using tkinter interface
print_flag (bool) – a bool for print message
- Returns:
s: dictionary of the PPG signal:
s.start_sig: the first sample of the signal to be analysed
s.end_sig: the last sample of the signal to be analysed
s.v: a vector of PPG values
s.fs: the sampling frequency of the PPG in Hz
s.name: name of the record
s.v: 1-d array, a vector of PPG values
s.fs: the sampling frequency of the PPG in Hz
s.ppg: 1-d array, a vector of the filtered PPG values
s.vpg: 1-d array, a vector of the filtered PPG’ values
s.apg: 1-d array, a vector of the filtered PPG” values
s.jpg: 1-d array, a vector of the filtered PPG’” values
s.filtering: a bool for filtering
s.correct: a bool for correcting fiducial points
- pyPPG.datahandling.plot_fiducials(s: PPG, fp: Fiducials, savefig=True, savingfolder='temp_dir', show_fig=True, print_flag=True, use_tk=False, new_fig=True, marker=[], title='Detection', legend_loc='upper right', legend_fontsize=20, marker_size=60, facecolor=False, subtext={}, canvas=nan)[source]
Plot fiducial points of the filtered PPG signal.
- Parameters:
s (pyPPG.PPG object) – object of PPG signal
fp (pyPPG.Fiducials object) – object of fiducial points
savefig (bool) – a bool for save figure
savingfolder – location of the saved figure
show_fig (bool) – a bool for show figure
print_flag (bool) – a bool for print message
use_tk (bool) – a bool for using tkinter interface
new_fig (bool) – a bool for creating new figure
marker (list) – list of fiducial points markers
title (str) – title of the legend
legend_loc (str) – location of the legend
legend_fontsize (int) – fontsize of the legends
marker_size (int) – size of markers
facecolor (bool) – a bool for facecolor of markers
subtext (dict) – dictionary for subplots text
canvas (FigureCanvas) – canvas of the figure
- pyPPG.datahandling.save_data(savingformat: str, savingfolder: str, print_flag=True, s={}, fp=Empty DataFrame Columns: [] Index: [], bm=Empty DataFrame Columns: [] Index: [])[source]
Save the results of the filtered PPG analysis.
- Parameters:
savingformat (str) – file format of the saved date, the provided file formats .mat and .csv
savingfolder (str) – location of the saved data
print_flag (bool) – a bool for print message
s (DotMap) – a struct of PPG signal
fp (pyPPG.Fiducial object) – a struct of fiducial points
bm (pyPPG.Biomarkers object) – a dictionary of biomarkers
- Returns:
file_names: dictionary of the saved file names
- pyPPG.datahandling.load_fiducials(saved_fiducials='')[source]
- Parameters:
saved_fiducials (str) – path of the matlab struct of the saved fiducial points, where the name field is ‘PPG_fiducials’
- Returns:
fiducial points: DataFrame where the key is the name of the fiducial pints and the value is the list of fiducial points