ecgtools

ecg_features

from_Rpeaks(sig, peaks_locs, sampling_rate, prefix='ecg', average=False)[source]

Calculates R-peak-based ECG features and returns a dictionary of features for each heart beat.

‘a_R’: Amplitude of R peak ‘RR0’: Previous RR interval ‘RR1’: Current RR interval ‘RR2’: Subsequent RR interval ‘RRm’: Mean of RR0, RR1 and RR2 ‘RR_0_1’: Ratio of RR0 to RR1 ‘RR_2_1’: Ratio of RR2 to RR1 ‘RR_m_1’: Ratio of RRm to RR1

Parameters:

sig (ArrayLike) – ECG signal segment.
peaks_locs (ArrayLike) – ECG R-peak locations.
sampling_rate (float) – Sampling rate of the ECG signal (Hz).
prefix (str, optional) – Prefix for the feature. Defaults to ‘ecg’.
average (bool, optional) – If True, averaged features are returned. Defaults to False.

Returns:

Dictionary of ECG features.

Return type:

dict

from_waves(sig, R_peaks, fiducials, sampling_rate, prefix='ecg', average=False)[source]

Calculates ECG features from the given fiducials and returns a dictionary of features.

‘t_PR’: Time between P and R peak locations ‘t_QR’: Time between Q and R peak locations ‘t_RS’: Time between R and S peak locations ‘t_RT’: Time between R and T peak locations ‘t_PQ’: Time between P and Q peak locations ‘t_PS’: Time between P and S peak locations ‘t_PT’: Time between P and T peak locations ‘t_QS’: Time between Q and S peak locations ‘t_QT’:Time between Q and T peak locations ‘t_ST’: Time between S and T peak locations ‘t_PT_QS’: Ratio of t_PT to t_QS ‘t_QT_QS’: Ratio of t_QT to t_QS ‘a_PQ’: Difference of P wave and Q wave amplitudes ‘a_QR’: Difference of Q wave and R wave amplitudes ‘a_RS’: Difference of R wave and S wave amplitudes ‘a_ST’: Difference of S wave and T wave amplitudes ‘a_PS’: Difference of P wave and S wave amplitudes ‘a_PT’: Difference of P wave and T wave amplitudes ‘a_QS’: Difference of Q wave and S wave amplitudes ‘a_QT’: Difference of Q wave and T wave amplitudes ‘a_ST_QS’: Ratio of a_ST to a_QS ‘a_RS_QR’: Ratio of a_RS to a_QR ‘a_PQ_QS’: Ratio of a_PQ to a_QS ‘a_PQ_QT’: Ratio of a_PQ to a_QT ‘a_PQ_PS’: Ratio of a_PQ to a_PS ‘a_PQ_QR’: Ratio of a_PQ to a_QR ‘a_PQ_RS’: Ratio of a_PQ to a_RS ‘a_RS_QS’: Ratio of a_RS to a_QS ‘a_RS_QT’: Ratio of a_RS to a_QT ‘a_ST_PQ’: Ratio of a_ST to a_PQ ‘a_ST_QT’: Ratio of a_ST to a_QT

Parameters:

sig (ArrayLike) – ECG signal segment.
R_peaks (ArrayLike) – ECG R-peak locations.
fiducials (dict) – Dictionary of fiducial locations (keys: “ECG_P_Peaks”, “ECG_Q_Peaks”, “ECG_S_Peaks”, “ECG_T_Peaks”).
sampling_rate (float) – Sampling rate of the ECG signal (Hz).
prefix (str, optional) – Prefix for the feature. Defaults to ‘ecg’.
average (bool, optional) – If True, averaged features are returned. Defaults to False.

Raises:

ValueError – If sampling rate is not greater than 0.

Returns:

Dictionary of ECG features.

Return type:

dict

ecg_filter

filter_ecg(sig, sampling_rate, method, **kwargs)[source]

Filters ECG signal using predefined filter parameters.

Parameters:

sig (ArrayLike) – ECG signal.
sampling_rate (float) – Sampling rate of the ECG signal (Hz).
method (str) – Filtering method. Should be one of [‘notch’, ‘bandpass’, ‘pantompkins’, ‘hamilton’, ‘elgendi].

Return type:

Kwargs:: f_notch (float) : Center frequency of the notch filter (w0). quality_factor (float): Quality factor (Q). It is calculated as Q = w0/bw where bw is the -3dB bandwidth.

Raises:

ValueError – If sampling rate is less than or equal to 0.
ValueError – If cut-off frequency is less than 0.
ValueError – If required parameters are not provided for the selected method.
ValueError – If filtering method is not one of [‘notch’, ‘pantompkins’, ‘hamilton’, ‘elgendi].

Returns:

Filtered ECG signal.

Return type:

ArrayLike

Parameters:

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

ecg_peaks

ecg_detectpeaks(sig, sampling_rate, method='pantompkins')[source]

Detects R peaks from ECG signal. Uses py-ecg-detectors package(https://github.com/berndporr/py-ecg-detectors/).

Parameters:

sig (ArrayLike) – ECG signal.
sampling_rate (float) – Sampling rate of the ECG signal (Hz).
method (str, optional) – Peak detection method. Should be ‘pantompkins’, ‘hamilton’ or ‘elgendi’. Defaults to ‘pantompkins’.
'pantompkins' – “Pan, J. & Tompkins, W. J.,(1985). ‘A real-time QRS detection algorithm’. IEEE transactions on biomedical engineering, (3), 230-236.”
'hamilton' – “Hamilton, P.S. (2002), ‘Open Source ECG Analysis Software Documentation’, E.P.Limited.”
'elgendi' – “Elgendi, M. & Jonkman, M. & De Boer, F. (2010). ‘Frequency Bands Effects on QRS Detection’, The 3rd International Conference on Bio-inspired Systems and Signal Processing (BIOSIGNALS2010). 428-431.

Raises:

ValueError – If sampling rate is not greater than 0.
ValueError – If method is not ‘pantompkins’, ‘hamilton’ or ‘elgendi’.

Returns:

R-peak locations

Return type:

ArrayLike

ecg_plot

plot_ecg(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)[source]

Generates plots for ECG 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. 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).
width (float, optional) – Figure width for Plotly. Defaults to 800.
height (float, optional) – Figure height for Plotly. Defaults to 440.

Raises:

ValueError – If timestamps is not None and timestamp resolution is not provided.
ValueError – If timestamps array and ECG signal have different lengths.
ValueError – If method is not ‘matplotlib’ or ‘plotly’.

ecg_sqa

sqa_ecg(ecg_sig, sampling_rate, methods, **kwargs)[source]

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

Parameters:

ecg_sig (ArrayLike) – Signal to be analyzed.
sampling_rate (float) – Sampling rate of the ECG 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. ‘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’ is missing and the method ‘template’ is selected.

Returns:

Dictionary of results for the applied methods.

Return type:

dict

Parameters:

ecg_sig (_SupportsArray[dtype] | _NestedSequence[_SupportsArray[dtype]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) –
sampling_rate (float) –
methods (list) –