Biomarkers

These modules are capable of computing individual biomarkers from various biological signals, including PPG, ECG, and SpO2.

pyPSG.biomarkers.get_ecg_bm

pyPSG.biomarkers.get_ecg_bm.get_ecg_biomarkers(signal, fs, matlab_path, get_hrv=True, get_peaks_only=False)

This function extracts ECG-based biomarkers from a raw ECG signal, and optionally heart rate variability (HRV) metrics.

Parameters:

signal (array-like) – The raw ECG signal (1D array-like).
fs (float) – Sampling frequency of the ECG signal in Hz.
matlab_path (str) – Path to the MATLAB executable.
get_hrv (bool, optional) – Whether to compute HRV metrics based on detected peaks.

Returns:

Dictionary containing ECG biomarkers and optionally HRV metrics. If get_hrv is True, returns a dict with ‘ecg’ and ‘hrv’ keys containing biomarkers. Otherwise, only the ECG biomarkers are returned.

pyPSG.biomarkers.get_hrv_bm

pyPSG.biomarkers.get_hrv_bm.get_hrv_biomarkers(peaks, fs, win_len, include_last_partial)

This function computes heart rate variability (HRV) biomarkers from peak indices. When applied to PPG signals, the function effectively computes Beat Rate Variability (BRV).

Parameters:

peaks (array-like) – Indices of heartbeat peaks in the signal in seconds(sample positions).
fs (float) – Sampling frequency of the signal in Hz.
win_len (float) – Window length in seconds.

Returns:

Dictionary of computed HRV metrics.

pyPSG.biomarkers.get_ppg_bm

pyPSG.biomarkers.get_ppg_bm.get_ppg_biomarkers(signal, fs, filtering=True, fL=0.5000001, fH=12, order=4, sm_wins={'apg': 10, 'jpg': 10, 'ppg': 50, 'vpg': 10}, correction=Empty DataFrame Columns: [] Index: [], get_brv=True, get_peaks_only=False)

This function extract PPG-based biomarkers and optionally beat rate variability (BRV) from a PPG signal.

Parameters:

signal (array-like) – The raw PPG signal
fs (float) – The sampling frequency of the PPG signal
get_brv (bool, optional) – Whether to compute beat rate variability (BRV) biomarkers
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

Returns:

If get_brv is True, returns a dict with ‘ppg’ and ‘brv’ keys containing biomarkers. Otherwise, returns only the PPG biomarkers object.

pyPSG.biomarkers.get_spo2_bm

pyPSG.biomarkers.get_spo2_bm.extract_biomarkers_per_signal(signal, patient, time_begin, time_end)

This function extracts SpO2 biomarkers per signal.

param signal:: The input SpO2 signal (oxygen saturation values).
type signal:: array-like
param time_begin:
param time_end:
return:: dictionary of SpO2 biomarkers

pyPSG.biomarkers.get_spo2_bm.features_all_desat(signal, time_signal, ODI_Threshold=6, hard_threshold=88, relative=True, desat_max_length=14400)

Extracts desaturation event features from a given oxygen saturation (SpO2) signal.

Parameters:

signal (array-like) – The input SpO2 signal (oxygen saturation values).
time_signal (array-like) – Time vector corresponding to the SpO2 signal samples.
ODI_Threshold (int, optional (default=6)) – Minimum relative drop in SpO2 (in %) to classify as a desaturation event.
hard_threshold (int, optional (default=88)) – Absolute SpO2 threshold. Values below this are considered desaturations regardless of relative drop.
relative (bool, optional (default=True)) – Whether to use a relative drop from baseline to detect desaturations.
desat_max_length (int, optional (default=14400)) – Maximum duration of a desaturation event (in sample points).

Returns:

A DataFrame containing detected desaturation events and their features. Columns include:

begin: Start time of the desaturation event.

end: End time of the desaturation event.

begin_idx: Start index in the signal.

end_idx: End index in the signal.

depth: Maximum depth of the desaturation.

length: Duration of the desaturation event.

area: Area under the desaturation curve based on maximum value.

pyPSG.biomarkers.get_spo2_bm.get_spo2_biomarkers(signal, fs, patient_name='Unknown')

This function preprocesses the SpO2 signal, then computes the biomarkers.

Parameters:

signal (np.ndarray) – SpO2 signal
fs (float) – sampling frequency

Returns:

dictionary of SpO2 biomarkers

pyPSG.biomarkers.all_BMs

pyPSG.biomarkers.all_BMs.biomarker_extractor(edf_path, matlab_path, channels={'ecg': '', 'ppg': '', 'spo2': ''})

Extracts physiological signal biomarkers from an EDF file for specified channels.

Parameters:

edf_path (str) – Path to the EDF file containing the physiological signals.
matlab_path (str) – Path to the MATLAB executable (required for ECG fiducial point detection).
channels (dict) – Dictionary mapping signal types to EDF channel names. Keys should be one or more of: “ppg”, “ecg”, “spo2”. Values are the corresponding channel names in the EDF file. If a value is an empty string, that channel will be ignored.

Returns:

Dictionary containing extracted biomarkers for each specified channel. Keys match the channel types (“ppg”, “ecg”, “spo2”), and values are the corresponding biomarker dictionaries returned by the channel-specific biomarker extraction functions.

Return type:

dict