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:
  1. Loading a raw PPG signal: various file formats such as .mat, .csv, .txt, or .edf.

  2. Get Fiducial points: extract the fiducial points of PPG, PPG’, PPG’’ and PPG’” signals

  3. Plot Fiducial Points

  4. Get Biomarkers: extract 74 PPG biomarkers in four categories:
    • PPG signal

    • Signal ratios

    • PPG derivatives

    • Derivatives ratios

  5. Get Statistics: summary of the 74 PPG biomarkers

  6. SQI calculation: calculates the PPG Signal Quality Index

  7. 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

get_s()[source]

This function retrieves the dictionary of the PPG signal.

Returns:

s: dictionary of the PPG signal

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

get_fp()[source]

This function retrieves the struct of the fiducial points.

Returns:

fp: DataFrame of the fiducial points

get_row(row_index: int)[source]

This function retrieves the specified row from the DataFrame of fiducial points.

Parameters:

row_index (int) – the index corresponding to the row in the fiducial points DataFrame

Returns:

the corresponding row in the fiducial points DataFrame

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

get_bm()[source]

This function retrieves the dictionary of the biomarkers.

Returns:

bm: dictionary of the biomarkers

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:

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

Subpackages