ppgtools

ppg_features

from_cycles(sig, peaks_locs, troughs_locs, sampling_rate, fiducials=None, feature_types=['Time', 'Stat'], prefix='ppg')

Calculates cycle-based PPG features.

Parameters:

• sig (ArrayLike) – PPG signal segment to be analyzed

• peaks_locs (ArrayLike) – PPG peak locations

• troughs_locs (ArrayLike) – PPG trough locations

• sampling_rate (float) – Sampling rate of the PPG signal.

• fiducials (dict, optional) – PPG fiducials. Defaults to None.

• feature_types (ArrayLike, optional) – Types of features to be calculated. Defaults to [‘Time’,’Stat’].

• prefix (str, optional) – Prefix for signal type. Defaults to ‘signal’.

Raises:

ValueError – If elements of feature_types are not ‘Time’ or ‘Stat’.

Returns:

Dictionary of calculated features.

Return type:

dict

from_segment(sig, sampling_rate, feature_types=['Stat', 'Freq', 'Time'], prefix='signal')

Calculates segment-based PPG features.

Parameters:

• sig (ArrayLike) – PPG signal segment to be analyzed

• sampling_rate (float) – Sampling rate of the PPG signal.

• feature_types (ArrayLike, optional) – Types of features to be calculated. Defaults to [‘Stat’,’Freq’,’Time’].

• prefix (str, optional) – Prefix for signal type. Defaults to ‘signal’.

Raises:

ValueError – if elements of feature_types are not ‘Time’, ‘Stat’ or ‘Freq’.

Returns:

Dictionary of calculated features.

Return type:

dict

get_domain_function(domain)

Parameters:

domain (str) –

Return type:

Callable

get_ppg_features(sig, sampling_rate, fiducials=None, input_types=['cycle', 'segment'], feature_domain={'cycle': ['Time', 'Stat'], 'segment': ['Stat', 'Freq', 'Time']}, prefix='ppg', **kwargs)

Calculates PPG features.

Parameters:

• sig (ArrayLike) – PPG signal.

• sampling_rate (float) – Sampling rate of the PPG signal (Hz).

• fiducials (dict, optional) – PPG fiducials. Defaults to None.

• input_types (list, optional) – Input types. It can be a list of ‘cycle’ and ‘segment’. Defaults to [‘cycle’, ‘segment’].

• feature_domain (_type_, optional) – Domain to calculate features. It should be provided for each input type seperately. Defaults to {‘cycle’:[‘Time’,’Stat’], ‘segment’:[‘Stat’,’Freq’,’Time’]}.

• prefix (str, optional) – Prefix for the features. Defaults to ‘ppg’.

Raises:

• ValueError – If sampling rate is not greater than 0.

• ValueError – If keyword arguments are missing.

Returns:

Dictionary of PPG features

Return type:

dict

ppg_filter

filter_ppg(sig, sampling_rate, method='bandpass')

Filters PPG signal using predefined filters.

Parameters:

• sig (ArrayLike) – PPG signal to be filtered.

• sampling_rate (float) – Sampling rate of the PPG signal.

• method (str, optional) – Filtering method. Defaults to ‘bandpass’.

Raises:

• ValueError – If sampling rate is not greater than zero.

• ValueError – If method is undefined.

Returns:

Filtered PPG signal.

Return type:

ArrayLike

ppg_freqdomain

ppg_freq_features(sig, sampling_rate, input_types, fiducials=None, prefix='ppg')

Calculates frequency-domain features

Segment-based features:

p_1: The amplitude of the first peak from the fft of the signal f_1: The frequency at which the first peak from the fft of the signal occurred p_2: The amplitude of the second peak from the fft of the signal f_2: The frequency at which the second peak from the fft of the signal occurred p_3: The amplitude of the third peak from the fft of the signal f_3: The frequency at which the third peak from the fft of the signal occurred pow: Power of the signal at a given range of frequencies ([0,2] Hz). rpow: Ratio of the powers of the signal at given ranges of frequencies ([0,2.25] Hz/[0,5] Hz).

Parameters:

• sig (ArrayLike) – Signal to be analyzed.

• sampling_rate (float) – Sampling rate of the signal (Hz).

• input_types (list) – Type of feature calculation, should be ‘segment’.

• fiducials (dict, optional) – Dictionary of fiducial point locations. Defaults to None.

• prefix (str, optional) – Prefix for signal type. Defaults to ‘ppg’.

Raises:

• ValueError – If sampling rate is not greater than 0.

• ValueError – If type is not ‘segment’.

Returns:

Dictionary of calculated features

Return type:

dict

ppg_peaks

apg_delineate(apg_sig, vpg_sig, vpg_fiducials, sampling_rate, th_a=0.45, th_w=0.5)

Detects fiducials of APG signal.

This function is an implementation of the method presented in: Abhishek Chakraborty, Deboleena Sadhukhan & Madhuchhanda Mitra (2019): An Automated Algorithm to Extract Time Plane Features From the PPG Signal and its Derivatives for Personal Health Monitoring Application, IETE Journal of Research, DOI: 10.1080/03772063.2019.1604178

Parameters:

• apg_sig (ArrayLike) – APG signal.

• vpg_sig (ArrayLike) – VPG signal.

• vpg_fiducials (dict) – VPG fiducials.

• sampling_rate (float) – Sampling rate of the APG signal (Hz).

• th_a (float, optional) – Threshold to detect a waves. Defaults to 0.45.

• th_w (float, optional) – Threshold to detect w waves. Defaults to 0.5.

Returns:

_description_

Return type:

dict

correct_missing_duplicate_peaks(locs_valleys, locs_peaks, peaks)

Detects missing or duplicate peaks in a given peak array using PPG onset locations as reference.

Parameters:

• locs_valleys (_SupportsArray[dtype] | _NestedSequence[_SupportsArray[dtype]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) –

• locs_peaks (_SupportsArray[dtype] | _NestedSequence[_SupportsArray[dtype]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) –

• peaks (_SupportsArray[dtype] | _NestedSequence[_SupportsArray[dtype]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) –

Return type:

tuple

peak_control(sig, peaks_locs, troughs_locs, type='peak')

Applies rules to check relative peak and onset locations.

First, trims the PPG segment as it starts and ends with a trough. Then, checks for missing or duplicate peaks taking the trough lcoations as reference. There must be one peak between successive troughs.

Parameters:

• sig (ArrayLike) – PPG signal

• peaks_locs (ArrayLike) – PPG peak locations

• troughs_locs (ArrayLike) – PPG trough locations

• type (str, optional) – Type of peaks. It can be ‘peak’ or ‘beat’. Defaults to ‘peak’.

Returns:

Dictionary of peak and trough locations.

Return type:

dict

ppg_delineate(ppg_sig, vpg_sig, vpg_fiducials, apg_sig, apg_fiducials, sampling_rate, locs_onsets=None)

Detects fiducials of PPG signal.

This function is an implementation of the method presented in: Abhishek Chakraborty, Deboleena Sadhukhan & Madhuchhanda Mitra (2019): An Automated Algorithm to Extract Time Plane Features From the PPG Signal and its Derivatives for Personal Health Monitoring Application, IETE Journal of Research, DOI: 10.1080/03772063.2019.1604178

Parameters:

• ppg_sig (ArrayLike) – PPG signal.

• vpg_sig (ArrayLike) – VPG signal.

• vpg_fiducials (dict) – VPG fiducials.

• apg_sig (ArrayLike) – APG signal.

• apg_fiducials (dict) – APG fiducials.

• sampling_rate (float) – Sampling rate of the PPG signal (Hz).

• locs_onsets (ArrayLike, optional) – PPG signal onset locations. Defaults to None.

Returns:

Dictionary of fiducial locations

Return type:

dict

ppg_detectbeats(sig, sampling_rate, method='peakdet', delta=None)

Detects PPG beats using the 1st derivative of the PPG signal. The detected locations correspond to the rising edge of the PPG beats.

Parameters:

• sig (ArrayLike) – Signal to be analyzed.

• sampling_rate (float) – Sampling rate of the signal (Hz).

• method (str, optional) – Peak detection method. Defaults to ‘peakdet’.

• delta (float, optional) – Delta parameter of the ‘peakdet’ method. Defaults to None.

Returns:

Beat locations.

Return type:

ArrayLike

ppg_detectpeaks(sig, sampling_rate, method='peakdet', correct_peaks=True, delta=None, type='peak')

Detects peaks and troughs of PPG signal.

Parameters:

• sig (ArrayLike) – PPG signal.

• sampling_rate (float) – Sampling rate of the PPG signal (Hz).

• method (str, optional) – Peak detection method. Should be one of ‘peakdet’, ‘heartpy’ and ‘scipy’. Defaults to ‘peakdet’. See https://gist.github.com/endolith/250860 to get information about ‘peakdet’ method.

• correct_peaks (bool, optional) – If True, peak locations are corrected relative to trough locations. Defaults to True.

• delta (float, optional) – Delta parameter of the ‘peakdet’ method. Defaults to None.

• type (str, optional) – Type of peaks. It can be ‘peak’ or ‘beat’. Defaults to ‘peak’.

Raises:

ValueError – If sampling rate is not greater than 0.

Returns:

Dictionary of peak and trough locations.

Return type:

dict

ppg_waves(sig, locs_onsets, sampling_rate, th_w=0.5, th_y=0.45, th_a=0.45)

Detects fiducials of PPG, VPG and APG signals.

Parameters:

• sig (ArrayLike) – PPG signal.

• locs_onsets (ArrayLike) – PPG signal onset locations

• sampling_rate (float) – Sampling rate of the PPG signal (Hz).

• th_w (float, optional) – Threshold to detect w waves. Defaults to 0.5.

• th_y (float, optional) – Threshold to detect y waves. Defaults to 0.45.

• th_a (float, optional) – Threshold to detect a waves. Defaults to 0.45.

Returns:

Dictionary of fiducial locations.

Return type:

dict

vpg_delineate(vpg_sig, sampling_rate, th_w=0.5, th_y=0.45)

Detects fiducials of VPG signal.

This function is an implementation of the method presented in: Abhishek Chakraborty, Deboleena Sadhukhan & Madhuchhanda Mitra (2019): An Automated Algorithm to Extract Time Plane Features From the PPG Signal and its Derivatives for Personal Health Monitoring Application, IETE Journal of Research, DOI: 10.1080/03772063.2019.1604178

Parameters:

• vpg_sig (ArrayLike) – VPG signal.

• sampling_rate (float) – Sampling rate of the VPG signal (Hz).

• th_w (float, optional) – Threshold to detect w waves. Defaults to 0.5.

• th_y (float, optional) – Threshold to detect y waves. Defaults to 0.45.

Returns:

Dictionary of fiducial locations.

Return type:

dict

ppg_plot

plot_ppg(signals, peaks=None, sampling_rate=None, timestamps=None, timestamp_resolution=None, method='matplotlib', show_peaks=True, figsize=(18.5, 10.5), width=800, height=440, rescale=False)

Generates plots for PPG signal.

Parameters:

• signals (dict) – The dictionary of signals to be plotted.

• peaks (dict, optional) – The dictionary of peaks to be plotted. Defaults to None.

• sampling_rate (float, optional) – Sampling rate of the signal. Defaults to None.

• timestamps (ArrayLike, optional) – Timestamp array. Defaults to None.

• timestamp_resolution (str, optional) – Timestamp resolution. Defaults to None.

• method (str, optional) – Package to generate plots. It can be ‘matplotlib’ or ‘plotly’. Defaults to ‘matplotlib’.

• show_peaks (bool, optional) – If True, peaks are plotted. Defaults to True.

• figsize (tuple, optional) – Figure size for matplotlib. Defaults to (18.5, 10.5) inches.

• width (float, optional) – Figure width for Plotly. Defaults to 800 pixels.

• height (float, optional) – Figure height for Plotly. Defaults to 440 pixels.

• rescale (bool) –

Raises:

• ValueError – If timestamps is not None and timestamp resolution is not provided.

• ValueError – If timestamps array and PPG signal have different lengths.

• ValueError – If method is not ‘matplotlib’ or ‘plotly’.

ppg_sqa

sqa_ppg(ppg_sig, sampling_rate, methods, **kwargs)

Assesses quality of PPG signal by applying rules based on morphological information.

Parameters:

• ppg_sig (ArrayLike) – Signal to be analyzed.

• sampling_rate (float) – Sampling rate of the PPG signal (Hz).

• methods (list) – Methods to be applied. It can be a list of ‘flatline’, ‘clipping’, ‘physiological’ and ‘template’. ‘flatline’: Detects beginning and end of flat segments. ‘clipping’: Detects beginning and end of clipped segments. ‘physiological’: Checks for physiological viability. ‘morphological’: Checks for morphological limits. ‘template’: Applies template matching method.

Return type:

dict

Kwargs:

threshold_pos (float): Threshold value for clipping detection. threshold_neg (float, optional): change_threshold (float): Threshold value for flatline detection. min_duration (float): Mimimum duration of flat segments for flatline detection. peaks_locs (float): R peak locations (sample). corr_th (float): Threshold for the correlation coefficient above which the signal is considered to be valid. Defaults to CORR_TH.

Raises:

• ValueError – If method is undefined.

• ValueError – If ‘change_threshold’ and/or ‘min_duration’ is missing and the method ‘flatline’ is selected.

• ValueError – If ‘threshold_pos’ is missing and the method ‘clipping’ is selected.

• ValueError – If ‘peaks_locs’ is missing and the method ‘physiological’ is selected.

• ValueError – If ‘peaks_locs’ and/or ‘troughs_locs’ is missing and the method ‘morphological’ is selected.

• ValueError – If ‘peaks_locs’ is missing and the method ‘template’ is selected.

Returns:

Dictionary of results for the applied methods.

Return type:

dict

Parameters:

• ppg_sig (_SupportsArray[dtype] | _NestedSequence[_SupportsArray[dtype]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) –

• sampling_rate (float) –

• methods (list) –

ppg_statistical

ppg_stat_features(sig, sampling_rate, input_types, fiducials=None, prefix='ppg', **kwargs)

Calculates statistical features.

Cycle-based features:

mean_peaks: Mean of the peak amplitudes std_peaks: Standard deviation of the peak amplitudes

Segment-based features:

mean: Mean value of the signal median: Median value of the signal std: Standard deviation of the signal pct_25: 25th percentile of the signal pct_75 75th percentile of the signal mad: Mean absolute deviation of the signal skewness: Skewness of the signal kurtosis: Kurtosis of the signal entropy: Entropy of the signal

Parameters:

• sig (ArrayLike) – Signal to be analyzed.

• sampling_rate (float) – Sampling rate of the signal (Hz).

• input_types (list) – Type of feature calculation, should be ‘segment’ or ‘cycle’.

• fiducials (dict, optional) – Dictionary of fiducial point locations. Defaults to None.

• prefix (str, optional) – Prefix for signal type. Defaults to ‘ppg’.

Return type:

dict

Kwargs:

peaks_locs (ArrayLike): Array of peak locations troughs_locs (ArrayLike): Array of trough locations

Raises:

• ValueError – If sampling rate is not greater than 0.

• ValueError – If ‘peaks_locs’ and/or ‘troughs_locs’ is not provided for the input_type ‘cycle’.

• ValueError – If type is not ‘cycle’ or ‘segment’.

Returns:

Dictionary of calculated features.

Return type:

dict

Parameters:

• sig (_SupportsArray[dtype] | _NestedSequence[_SupportsArray[dtype]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) –

• sampling_rate (float) –

• input_types (list) –

• fiducials (dict | None) –

• prefix (str) –

ppg_timedomain

ppg_time_features(sig, sampling_rate, input_types, fiducials=None, prefix='ppg', **kwargs)

Calculates time-domain features.

Cycle-based features:

a_S: Mean amplitude of the systolic peaks t_S: Mean systolic peak duration t_C: Mean cycle duration DW: Mean diastolic peak duration SW_10: The systolic peak duration at 10% of systolic amplitude SW_25: The systolic peak duration at 25% of systolic amplitude SW_33: The systolic peak duration at 33% of systolic amplitude SW_50: The systolic peak duration at 50% of systolic amplitude SW_66: The systolic peak duration at 66% of systolic amplitude SW_75: The systolic peak duration at 75% of systolic amplitude DW_10: The diastolic peak duration at 10% of systolic amplitude DW_25: The diastolic peak duration at 25% of systolic amplitude DW_33: The diastolic peak duration at 33% of systolic amplitude DW_50: The diastolic peak duration at 50% of systolic amplitude DW_66: The diastolic peak duration at 66% of systolic amplitude DW_75: The diastolic peak duration at 75% of systolic amplitude DW_SW_10: The ratio of diastolic peak duration to systolic peak duration at 10% of systolic amplitude DW_SW_25: The ratio of diastolic peak duration to systolic peak duration at 25% of systolic amplitude DW_SW_33: The ratio of diastolic peak duration to systolic peak duration at 33% of systolic amplitude DW_SW_50: The ratio of diastolic peak duration to systolic peak duration at 50% of systolic amplitude DW_SW_66: The ratio of diastolic peak duration to systolic peak duration at 66% of systolic amplitude DW_SW_75: The ratio of diastolic peak duration to systolic peak duration at 75% of systolic amplitude PR_mean: Mean pulse rate a_D: Mean amplitude of the diastolic peaks t_D: Mean difference between diastolic peak and onset r_D: Mean ratio of the diastolic peak amplitude to diastolic peak duration a_N: Mean amplitude of the dicrotic notchs t_N: Mean dicrotic notch duration r_N: Mean ratio of the dicrotic notch amplitude to dicrotic notch duration dT: Mean duration from systolic to diastolic peaks r_D_NC: Mean ratio of diastolic peak amplitudes to difference between ppg wave duration and dictoric notch duration r_N_NC: Mean ratio of dicrotic notch amplitudes to difference between ppg wave duration and dictoric notch duration a_N_S: Mean ratio of dicrotic notch amplitudes to systolic peak amplitudes AI: Mean ratio of diastolic peak amplitudes to systolic peak amplitudes AI_2: Mean ratio of difference between systolic and diastolic peak amplitudes to systolic peak amplitudes

Segment-based features:

zcr: Zero crossing rate snr: Signal to noise ratio

Parameters:

• sig (ArrayLike) – Signal to be analyzed.

• sampling_rate (float) – Sampling rate of the signal (Hz).

• input_types (str) – Type of feature calculation, should be ‘segment’ or ‘cycle’.

• fiducials (dict, optional) – Dictionary of fiducial point locations. Defaults to None.

• prefix (str, optional) – Prefix for signal type. Defaults to ‘ppg’.

Return type:

dict

Kwargs:

peaks_locs (ArrayLike): Array of peak locations troughs_locs (ArrayLike): Array of trough locations

Raises:

• ValueError – If sampling rate is not greater than 0.

• ValueError – If PPG onset locations is not provided.

• ValueError – If PPG S-peak locations is not provided.

• ValueError – If Type is not ‘cycle’ or ‘segment’.

Returns:

Dictionary of calculated features.

Return type:

dict

Parameters:

• sig (_SupportsArray[dtype] | _NestedSequence[_SupportsArray[dtype]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) –

• sampling_rate (float) –

• input_types (str) –

• fiducials (dict | None) –

• prefix (str) –