Package: vg-beat-detectors
Fast and Sample-Accurate R-Peak Detectors Based on Visibility GraphsThis Python package provides an implementation of visibility graph (VG)
based approaches for detecting R-peaks in ECG signals. The utilized
visibility graph transformation maps a given signal into a graph
representation by expressing sampling locations as nodes and
establishing edges between mutually visible samples. Subsequently, graph
information is used to determine the R-peak positions.In [1] and [2] benchmarking on several popular databases showed that
the visibility graph based methods allow for sample-accurate R-peak
detection and provide significantly superior performance compared to
popular R-peak detectors.InstallationYou can install the latest version of the ‘vg-beat-detectors’ package
from thePython Package Index
(PyPI)by running:pip install vg-beat-detectorsAdditionally, the source code is available onGitHub.Quick StartThis section illustrates, the basic usage of the ‘FastNVG’ and
‘FastWHVG’ detectors [1], which utilize the natural visibility graph
(NVG) and weighted horizontal visibility graph (WHVG), respectively.For both the ‘FastNVG’ and the ‘FastWHVG’ detectors, this package
provides an identically named class that is initialized with thesampling frequency‘fs’ of the given ECG signal. R-peaks can then be
determined by applying the detectorsfind_peaks(ecg)method on the ECG
signal.This is exemplified in the following by means of the pseudo variablesfsandecg:FastNVGfromvg_beat_detectorsimportFastNVGdetector=FastNVG(sampling_frequency=fs)rpeaks=detector.find_peaks(ecg)FastWHVGfromvg_beat_detectorsimportFastWHVGdetector=FastWHVG(sampling_frequency=fs)rpeaks=detector.find_peaks(ecg)Complete Working ExampleThe next example demonstrates the application of the ‘FastNVG’ detector
using real-world ECG data provided by the ‘scipy’ package. The
utilization of the ‘FastWHVG’ is analogous.# import the FastNVG detectorfromvg_beat_detectorsimportFastNVG# import packages used in this exampleimportnumpyasnpimportmatplotlib.pyplotaspltfromscipy.datasetsimportelectrocardiogram# generate some ECG signalecg=electrocardiogram()# sampling frequency of this excerpt is 360Hzfs=360time=np.arange(ecg.size)/fs# visibility graph R-peak detectordetector=FastNVG(sampling_frequency=fs)R_peaks=detector.find_peaks(ecg)# plot signal and detected peaksplt.plot(time,ecg)plt.plot(time[R_peaks],ecg[R_peaks],'X')plt.xlabel("time in s")plt.ylabel("ECG in mV")plt.xlim(9,10.2)#> (9.0, 10.2)plt.ylim(-1,1.5)#> (-1.0, 1.5)plt.show()Advanced UsageFor advanced and experimental usage, the package provides the
‘VisGraphDetector’ base class, in which a number of parameters can be
set, which will be briefly explained in the next paragraphs. For further
understanding of the listed options and their influence on the
algorithm, the interested user is referred to the papers [1] and
[2].The advanced usage follows the same structure as presented above:fromvg_beat_detectorsimportVisGraphDetectordetector=VisGraphDetector(sampling_frequency=250,graph_type='nvg',edge_weight=None,beta=0.55,accelerated=False,window_overlap=0.5,window_length=2,lowcut=4.0)rpeaks=detector.find_peaks(ecg)Visibility graph typesThe underlying visibility graph transformation can be selected withgraph_type. The option ‘nvg’ results in the natural visibility graph
and ‘hvg’ in the horizontal visibility graph.Weighted edgesThe edges in the visibility graph representation can be constructed with
a weighting factor. Therefore, the optionedge_weightdetermines the
metric for calculating the edge weight between two nodes (or samples).Available weights are ‘distance’, ‘sq_distance’, ‘v_distance’,
‘abs_v_distance’, ‘h_distance’, ‘abs_h_distance’, ‘slope’,
‘abs_slope’, ‘angle’ and ‘abs_angle’ as well as None for no weighting.For further explanation of each available weight, see thedocumentation
of the ‘ts2vg’
package.Accelerated and non-accelerated processingThe acceleration technique proposed in [1] which reduces the input
signal to only local maxima samples can be enabled or disabled by
settingacceleratedtoTrueorFalse, respectively. The
acceleration results in a run-time reduction by one order of magnitude
while the detection accuracy remains comparable to that of the
non-accelerated detector.Sparsity parameter $\beta$As described in [1,2], the choice of the sparsity parameter
$\beta \in [0, 1]$ depends on the used visibility graph transformation and
edge weights. The parameter $\beta$ should be set appropriately to achieve a
high detection performance. Sparsity parameter values for the NVG and
WHVG were determined in numerical experiments in [1,2]. We
highly recommend redeterminingbetaas described in [1,2],
when changes have been made to thegraph_typeandedge_weightoptions.Adjusting segmentsThe input ECG signal is processed segment-wise using segments with a
default length of 2 sec and an overlap of 50%, i.e.,window_length=2andwindow_overlap=0.5. As their name suggests, these parameters allow
for adjustments of the window length and overlap.Setting highpass cutoff frequencyTo change the lower cutoff frequency of the highpass filter that
pre-processes the input ECG signal, the parameterlowcutcan be
modified. The default value is $4 \mathrm{Hz}$.References[1]Emrich, J.,Koka, T.,Wirth, S. andMuma, M. (2023).Accelerated Sample-Accurate R-Peak Detectors Based on
Visibility Graphs.[2]Koka, T. andMuma, M. (2022).Fast and Sample Accurate R-Peak Detection for Noisy ECG
Using Visibility
Graphs.
121-6.