processing

The processing subpackage contains signal-processing tools.

Basic Utility

Basic signal processing functions

wfdb.processing.resample_ann(ann_sample, fs, fs_target)

Compute the new annotation indices.

ann_sample : ndarray
Array of annotation locations.
fs : int
The starting sampling frequency.
fs_target : int
The desired sampling frequency.
ndarray
Array of resampled annotation locations.
wfdb.processing.resample_sig(x, fs, fs_target)

Resample a signal to a different frequency.

x : ndarray
Array containing the signal.
fs : int, float
The original sampling frequency.
fs_target : int, float
The target frequency.
resampled_x : ndarray
Array of the resampled signal values.
resampled_t : ndarray
Array of the resampled signal locations.
wfdb.processing.resample_singlechan(x, ann, fs, fs_target)

Resample a single-channel signal with its annotations.

x: ndarray
The signal array.
ann : WFDB Annotation
The WFDB annotation object.
fs : int, float
The original frequency.
fs_target : int, float
The target frequency.
resampled_x : ndarray
Array of the resampled signal values.
resampled_ann : WFDB Annotation
Annotation containing resampled annotation locations.
wfdb.processing.resample_multichan(xs, ann, fs, fs_target, resamp_ann_chan=0)

Resample multiple channels with their annotations.

xs: ndarray
The signal array.
ann : WFDB Annotation
The WFDB annotation object.
fs : int, float
The original frequency.
fs_target : int, float
The target frequency.
resample_ann_channel : int, optional
The signal channel used to compute new annotation indices.
ndarray
Array of the resampled signal values.
resampled_ann : WFDB Annotation
Annotation containing resampled annotation locations.
wfdb.processing.normalize_bound(sig, lb=0, ub=1)

Normalize a signal between the lower and upper bound.

sig : ndarray
Original signal to be normalized.
lb : int, float, optional
Lower bound.
ub : int, float, optional
Upper bound.
ndarray
Normalized signal.
wfdb.processing.get_filter_gain(b, a, f_gain, fs)

Given filter coefficients, return the gain at a particular frequency.

b : list
List of linear filter b coefficients.
a : list
List of linear filter a coefficients.
f_gain : int, float, optional
The frequency at which to calculate the gain.
fs : int, float, optional
The sampling frequency of the system.
gain : int, float
The passband gain at the desired frequency.

Heart Rate

wfdb.processing.compute_hr(sig_len, qrs_inds, fs)

Compute instantaneous heart rate from peak indices.

sig_len : int
The length of the corresponding signal.
qrs_inds : ndarray
The QRS index locations.
fs : int, float
The corresponding signal’s sampling frequency.
heart_rate : ndarray
An array of the instantaneous heart rate, with the length of the corresponding signal. Contains numpy.nan where heart rate could not be computed.

Peaks

wfdb.processing.find_peaks(sig)

Find hard peaks and soft peaks in a signal, defined as follows:

  • Hard peak: a peak that is either /or /.
  • Soft peak: a peak that is either /-or -/. In this case we define the middle as the peak.
sig : np array
The 1d signal array.
hard_peaks : ndarray
Array containing the indices of the hard peaks.
soft_peaks : ndarray
Array containing the indices of the soft peaks.
wfdb.processing.find_local_peaks(sig, radius)

Find all local peaks in a signal. A sample is a local peak if it is the largest value within the <radius> samples on its left and right. In cases where it shares the max value with nearby samples, the middle sample is classified as the local peak.

sig : ndarray
1d numpy array of the signal.
radius : int
The radius in which to search for defining local maxima.
ndarray
The locations of all of the local peaks of the input signal.
wfdb.processing.correct_peaks(sig, peak_inds, search_radius, smooth_window_size, peak_dir='compare')

Adjust a set of detected peaks to coincide with local signal maxima.

sig : ndarray
The 1d signal array.
peak_inds : np array
Array of the original peak indices.
search_radius : int
The radius within which the original peaks may be shifted.
smooth_window_size : int
The window size of the moving average filter applied on the signal. Peak distance is calculated on the difference between the original and smoothed signal.
peak_dir : str, optional

The expected peak direction: ‘up’ or ‘down’, ‘both’, or ‘compare’.

  • If ‘up’, the peaks will be shifted to local maxima.
  • If ‘down’, the peaks will be shifted to local minima.
  • If ‘both’, the peaks will be shifted to local maxima of the rectified signal.
  • If ‘compare’, the function will try both ‘up’ and ‘down’ options, and choose the direction that gives the largest mean distance from the smoothed signal.
shifted_peak_inds : ndarray
Array of the corrected peak indices.

QRS Detectors

class wfdb.processing.XQRS(sig, fs, conf=None)

The QRS detector class for the XQRS algorithm. The XQRS.Conf class is the configuration class that stores initial parameters for the detection. The XQRS.detect method runs the detection algorithm.

The process works as follows:

  • Load the signal and configuration parameters.
  • Bandpass filter the signal between 5 and 20 Hz, to get the filtered signal.
  • Apply moving wave integration (MWI) with a Ricker (Mexican hat) wavelet onto the filtered signal, and save the square of the integrated signal.
  • Conduct learning if specified, to initialize running parameters of noise and QRS amplitudes, the QRS detection threshold, and recent R-R intervals. If learning is unspecified or fails, use default parameters. See the docstring for the _learn_init_params method of this class for details.
  • Run the main detection. Iterate through the local maxima of the MWI signal. For each local maxima:
    • Check if it is a QRS complex. To be classified as a QRS, it must come after the refractory period, cross the QRS detection threshold, and not be classified as a T-wave if it comes close enough to the previous QRS. If successfully classified, update running detection threshold and heart rate parameters.
    • If not a QRS, classify it as a noise peak and update running parameters.
    • Before continuing to the next local maxima, if no QRS was detected within 1.66 times the recent R-R interval, perform backsearch QRS detection. This checks previous peaks using a lower QRS detection threshold.
sig : 1d ndarray
The input ECG signal to apply the QRS detection on.
fs : int, float
The sampling frequency of the input signal.
conf : XQRS.Conf object, optional
The configuration object specifying signal configuration parameters. See the docstring of the XQRS.Conf class.
>>> import wfdb
>>> from wfdb import processing
>>> sig, fields = wfdb.rdsamp('sample-data/100', channels=[0])
>>> xqrs = processing.XQRS(sig=sig[:,0], fs=fields['fs'])
>>> xqrs.detect()
>>> wfdb.plot_items(signal=sig, ann_samp=[xqrs.qrs_inds])
class Conf(hr_init=75, hr_max=200, hr_min=25, qrs_width=0.1, qrs_thr_init=0.13, qrs_thr_min=0, ref_period=0.2, t_inspect_period=0)

Initial signal configuration object for this QRS detector.

hr_init : int, float, optional
Initial heart rate in beats per minute. Used for calculating recent R-R intervals.
hr_max : int, float, optional
Hard maximum heart rate between two beats, in beats per minute. Used for refractory period.
hr_min : int, float, optional
Hard minimum heart rate between two beats, in beats per minute. Used for calculating recent R-R intervals.
qrs_width : int, float, optional
Expected QRS width in seconds. Used for filter widths indirect refractory period.
qrs_thr_init : int, float, optional
Initial QRS detection threshold in mV. Use when learning is False, or learning fails.
qrs_thr_min : int, float, string, optional
Hard minimum detection threshold of QRS wave. Leave as 0 for no minimum.
ref_period : int, float, optional
The QRS refractory period.
t_inspect_period : int, float, optional
The period below which a potential QRS complex is inspected to see if it is a T-wave. Leave as 0 for no T-wave inspection.
detect(sampfrom=0, sampto='end', learn=True, verbose=True)

Detect QRS locations between two samples.

sampfrom : int, optional
The starting sample number to run the detection on.
sampto : int, optional
The final sample number to run the detection on. Set as ‘end’ to run on the entire signal.
learn : bool, optional
Whether to apply learning on the signal before running the main detection. If learning fails or is not conducted, the default configuration parameters will be used to initialize these variables. See the XQRS._learn_init_params docstring for details.
verbose : bool, optional
Whether to display the stages and outcomes of the detection process.

N/A

wfdb.processing.xqrs_detect(sig, fs, sampfrom=0, sampto='end', conf=None, learn=True, verbose=True)

Run the ‘xqrs’ QRS detection algorithm on a signal. See the docstring of the XQRS class for algorithm details.

sig : ndarray
The input ECG signal to apply the QRS detection on.
fs : int, float
The sampling frequency of the input signal.
sampfrom : int, optional
The starting sample number to run the detection on.
sampto : str
The final sample number to run the detection on. Set as ‘end’ to run on the entire signal.
conf : XQRS.Conf object, optional
The configuration object specifying signal configuration parameters. See the docstring of the XQRS.Conf class.
learn : bool, optional
Whether to apply learning on the signal before running the main detection. If learning fails or is not conducted, the default configuration parameters will be used to initialize these variables.
verbose : bool, optional
Whether to display the stages and outcomes of the detection process.
qrs_inds : ndarray
The indices of the detected QRS complexes.
>>> import wfdb
>>> from wfdb import processing
>>> sig, fields = wfdb.rdsamp('sample-data/100', channels=[0])
>>> qrs_inds = processing.xqrs_detect(sig=sig[:,0], fs=fields['fs'])
wfdb.processing.gqrs_detect(sig=None, fs=None, d_sig=None, adc_gain=None, adc_zero=None, threshold=1.0, hr=75, RRdelta=0.2, RRmin=0.28, RRmax=2.4, QS=0.07, QT=0.35, RTmin=0.25, RTmax=0.33, QRSa=750, QRSamin=130)

Detect QRS locations in a single channel ecg. Functionally, a direct port of the GQRS algorithm from the original WFDB package. Accepts either a physical signal, or a digital signal with known adc_gain and adc_zero. See the notes below for a summary of the program. This algorithm is not being developed/supported.

sig : 1d numpy array, optional
The input physical signal. The detection algorithm which replicates the original, works using digital samples, and this physical option is provided as a convenient interface. If this is the specified input signal, automatic adc is performed using 24 bit precision, to obtain the d_sig, adc_gain, and adc_zero parameters. There may be minor differences in detection results (ie. an occasional 1 sample difference) between using sig and d_sig. To replicate the exact output of the original GQRS algorithm, use the d_sig argument instead.
fs : int, float, optional
The sampling frequency of the signal.
d_sig : 1d numpy array, optional
The input digital signal. If this is the specified input signal rather than sig, the adc_gain and adc_zero parameters must be specified.
adc_gain : int, float, optional
The analogue to digital gain of the signal (the number of adus per physical unit).
adc_zero : int, optional
The value produced by the ADC given a 0 Volt input.
threshold : int, float, optional
The relative amplitude detection threshold. Used to initialize the peak and QRS detection threshold.
hr : int, float, optional
Typical heart rate, in beats per minute.
RRdelta : int, float, optional
Typical difference between successive RR intervals in seconds.
RRmin : int, float, optional
Minimum RR interval (“refractory period”), in seconds.
RRmax : int, float, optional
Maximum RR interval, in seconds. Thresholds will be adjusted if no peaks are detected within this interval.
QS : int, float, optional
Typical QRS duration, in seconds.
QT : int, float, optional
Typical QT interval, in seconds.
RTmin : int, float, optional
Minimum interval between R and T peaks, in seconds.
RTmax : int, float, optional
Maximum interval between R and T peaks, in seconds.
QRSa : int, float, optional
Typical QRS peak-to-peak amplitude, in microvolts.
QRSamin : int, float, optional
Minimum QRS peak-to-peak amplitude, in microvolts.
qrs_locs : ndarray
Detected QRS locations.

This function should not be used for signals with fs <= 50Hz.

The algorithm theoretically works as follows:

  • Load in configuration parameters. They are used to set/initialize the:

    • allowed R-R interval limits (fixed)
    • initial recent R-R interval (running)
    • QRS width, used for detection filter widths (fixed)
    • allowed R-T interval limits (fixed)
    • initial recent R-T interval (running)
    • initial peak amplitude detection threshold (running)
    • initial QRS amplitude detection threshold (running)
    • Note: this algorithm does not normalize signal amplitudes, and hence is highly dependent on configuration amplitude parameters.
  • Apply trapezoid low-pass filtering to the signal.

  • Convolve a QRS matched filter with the filtered signal.

  • Run the learning phase using a calculated signal length: detect QRS and non-qrs peaks as in the main detection phase, without saving the QRS locations. During this phase, running parameters of recent intervals and peak/qrs thresholds are adjusted.

  • Run the detection:

    if a sample is bigger than its immediate neighbors and larger than the peak detection threshold, it is a peak.

    if it is further than RRmin from the previous QRS, and is a primary peak.

    if it is further than 2 standard deviations from the previous QRS, do a backsearch for a missed low amplitude beat.

    return the primary peak between the current sample and the previous QRS if any.

    if it surpasses the QRS threshold, it is a QRS complex

    save the QRS location. update running R-R interval and QRS amplitude parameters. look for the QRS complex’s T-wave and mark it if found.

    else if it is not a peak.

    lower the peak detection threshold if the last peak found was more than RRmax ago, and not already at its minimum.

A peak is secondary if there is a larger peak within its neighborhood (time +- rrmin), or if it has been identified as a T-wave associated with a previous primary peak. A peak is primary if it is largest in its neighborhood, or if the only larger peaks are secondary.

The above describes how the algorithm should theoretically work, but there are bugs which make the program contradict certain parts of its supposed logic. A list of issues from the original c, code and hence this python implementation can be found here:

https://github.com/bemoody/wfdb/issues/17

>>> import numpy as np
>>> import wfdb
>>> from wfdb import processing
>>> # Detect using a physical input signal
>>> record = wfdb.rdrecord('sample-data/100', channels=[0])
>>> qrs_locs = processing.gqrs_detect(record.p_signal[:,0], fs=record.fs)
>>> # Detect using a digital input signal
>>> record_2 = wfdb.rdrecord('sample-data/100', channels=[0], physical=False)
>>> qrs_locs_2 = processing.gqrs_detect(d_sig=record_2.d_signal[:,0],
                                        fs=record_2.fs,
                                        adc_gain=record_2.adc_gain[0],
                                        adc_zero=record_2.adc_zero[0])

Annotation Evaluators

class wfdb.processing.Comparitor(ref_sample, test_sample, window_width, signal=None)

The class to implement and hold comparisons between two sets of annotations. See methods compare, print_summary and plot.

ref_sample : ndarray
An array of the reference sample locations.
test_sample : ndarray
An array of the comparison sample locations.
window_width : int
The width of the window.
signal : 1d numpy array, optional
The signal array the annotation samples are labelling. Only used for plotting.
>>> import wfdb
>>> from wfdb import processing
>>> sig, fields = wfdb.rdsamp('sample-data/100', channels=[0])
>>> ann_ref = wfdb.rdann('sample-data/100','atr')
>>> xqrs = processing.XQRS(sig=sig[:,0], fs=fields['fs'])
>>> xqrs.detect()
>>> comparitor = processing.Comparitor(ann_ref.sample[1:],
                                       xqrs.qrs_inds,
                                       int(0.1 * fields['fs']),
                                       sig[:,0])
>>> comparitor.compare()
>>> comparitor.print_summary()
>>> comparitor.plot()
compare()

Main comparison function. Note: Make sure to be able to handle these ref/test scenarios:

N/A

N/A

A: o—-o—o—o x——-x—-x

B: o—-o—–o—o x——–x–x–x

C: o——o—–o—o x-x——–x–x–x

D: o——o—–o—o x-x——–x—–x

plot(sig_style='', title=None, figsize=None, return_fig=False)

Plot the comparison of two sets of annotations, possibly overlaid on their original signal.

sig_style : str, optional
The matplotlib style of the signal
title : str, optional
The title of the plot
figsize: tuple, optional
Tuple pair specifying the width, and height of the figure. It is the’figsize’ argument passed into matplotlib.pyplot’s figure function.
return_fig : bool, optional
Whether the figure is to be returned as an output argument.
fig : matplotlib figure object
The figure information for the plot.
ax : matplotlib axes object
The axes information for the plot.
print_summary()

Print summary metrics of the annotation comparisons.

N/A

N/A

wfdb.processing.compare_annotations(ref_sample, test_sample, window_width, signal=None)

Compare a set of reference annotation locations against a set of test annotation locations. See the Comparitor class docstring for more information.

ref_sample : 1d numpy array
Array of reference sample locations.
test_sample : 1d numpy array
Array of test sample locations to compare.
window_width : int
The maximum absolute difference in sample numbers that is permitted for matching annotations.
signal : 1d numpy array, optional
The original signal of the two annotations. Only used for plotting.
comparitor : Comparitor object
Object containing parameters about the two sets of annotations.
>>> import wfdb
>>> from wfdb import processing
>>> sig, fields = wfdb.rdsamp('sample-data/100', channels=[0])
>>> ann_ref = wfdb.rdann('sample-data/100','atr')
>>> xqrs = processing.XQRS(sig=sig[:,0], fs=fields['fs'])
>>> xqrs.detect()
>>> comparitor = processing.compare_annotations(ann_ref.sample[1:],
                                                xqrs.qrs_inds,
                                                int(0.1 * fields['fs']),
                                                sig[:,0])
>>> comparitor.print_summary()
>>> comparitor.plot()
wfdb.processing.benchmark_mitdb(detector, verbose=False, print_results=False)

Benchmark a QRS detector against mitdb’s records.

detector : function
The detector function.
verbose : bool, optional
The verbose option of the detector function.
print_results : bool, optional
Whether to print the overall performance, and the results for each record.
comparitors : dictionary
Dictionary of Comparitor objects run on the records, keyed on the record names.
sensitivity : float
Aggregate sensitivity.
positive_predictivity : float
Aggregate positive_predictivity.

TODO: - remove non-qrs detections from reference annotations - allow kwargs

>>> import wfdb
>> from wfdb.processing import benchmark_mitdb, xqrs_detect
>>> comparitors, spec, pp = benchmark_mitdb(xqrs_detect)