In this repository is possible to find the source code for the event-based gQRS algorithm for R peak detection in ECG signals. both the python demonstrative version and C version implemented on the PULP platform Mr.Wolf can be found here.
corrected typos, added result reading directly on the jupyter notebook
added c code for PULP
added file for automatic data header creation
solved minor bug in the notebook
re-designed jupter notebook for the gQRS python implementation
started to re-implement the gQRS algorithm, need to change data structure for…
finished data re-sampler
started to work on the data parsing
added reference to the paper and ack
|Nov 13 2019|
update README (trying to accomodate markdown interpreter at c4science)
|Nov 12 2019|
|Nov 12 2019|
|Nov 12 2019|
This is the official repository for the publication: Silvio Zanoli, Tomas T. Teijeiro, Fabio Montagna and David Atienza Alonso: "An Event-Based System for Low-Power ECG QRS Detection", developed at the Embedded Systems Laboratory (ESL), EPFL. This publication was presented at the DATE2020 conference
Electrocardiogram(ECG) signals describe the atrial and ventricular contraction in the human heart through the electrical phenomena that happen in the heart muscles. This signals are composed of functional complexes and can be summarized, in first approximation, as follow:
- P-Wave, associated with the atrium contraction
- QRS-complex associated with the contraction of the large ventricular muscles, this is the most prominent event in an ECG signal.
- T-Wave, associated with the repolarization of the ventricles
In this project, we are particularly interested in QRS complex detection in event-based sampled signals. Event-Based signals are a class of signals in which data samples get drawn from the physical system depending on the occurring of certain events instead of using a fixed sampling frequency. The problem of QRS complex detection has been tackled, for uniformly sampled signals, numerous times. At the present day, one of the state-of-the-art algorithms used for QRS complex detection is the gQRS. In this work first, we adapted the gQRS algorithm in order to be compatible with event-based signals, then we ported the developed algorithm on a low-power multicore microcontroller unit (MCU). In this repository it is possible to find both a Python implementation of the event-based gQRS, and an optimized C version for the PULP architecture..
This repository is composed of three main folders:
- data_parsing: This folder contains the python scripts for data pre-processing and results evaluation:
- * ECG_lvlCrossing.py: The re-sampling script: it reads the data in MIT-BIH format and re-sample them
- * makeDataHeader.py: This script reads the re-sampled signal, the annotations file (containing the labels for the signal selected) and produces a header for the C code containing the data and the information relative to the selected file.
- * MITAnnotation.py, eval_mitdb.sh: script used internally for data representation and evaluation.
- python_gQRS: This folder contains the iPython (Jupyter notebook) used for demonstration and performance evaluation of the event-based gQRS.
- * gQRS-lvlCrossingsampling.ipynb: Notebook for event-based gQRS demonstration and evaluation.
- c_gQRS: Folder containing the c source code to be compiled with the PULP SDK.
- Python 3.6.x*
- Python 3.5.3*
\* Note: the Pulp SDK is tested to work within Ubuntu 16.04. The tools used to compile the SDK comprehend python version 3.5.3. This code was designed for Python 3.6.x, and also tested on Python 3.7.1. Our suggestion is to have a Ubuntu 16.04 machine with default python3 -> python3.5.3 and a second python 3.6.x installation used to execute exclusively this code. Alternatively, it is possible to run the C Version on an ubuntu 16.04 virtual machine once all the data and the python calls have been executed on a Linux OS with a python version 3.6.x or higher
- Clone the repository and set the root directory of the project.
- Create a data folder on the root directory, this will be the directory of your RAW data and the output directory.
- Insert your dataset in the MIT-BIH database format (.dat and .hea files) in a subfolder, for example, "dataRaw".
- The database used for developing and testing this algorithm can be found at MIT-BIH Arrhythmia Database. NOTE: The code and the instructions
given here are designed to work with data in the wfdb format.
- Move into the "data_parsing" folder and lunch ECG_lvlCrossing.py
python3 ECG_lvlCrossing.py -i ../data/dataRaw -o ../data/dataOut -b 5 [-l 'MLII'][--hist 0]
This script will extract and resample with an emulated level crossing ADC with number of bits "-b" all the files in the MIT-BIH format found in the directory passed by the "-i" argument and output the results in the folder passed with "-o", in the subfolder "dataOut/lvlCrossingBits_x_Hist_y_". It is also possible to pass the path of a single file as input (-i argument), this will result in the resampling of the single file. The default selected electrode is 'MLII', but it is possible to change the used electrode with the argument "-l 'Electrode Name'". By default, no Hysteresis is used around the threshold levels. It is possible to give a hysteresis value (in percentage) with the argument '--hist'
Run the Jupyter notebook contained in the "python_gQRS" folder. This notebook will produce, in the end, a "results" folder (../data/results) in which it is possible to find the results (sensitivity, positive predictivity, and F1-Score). The results will be also listed inside the same Jupyter notebook.
Important note: This is not a plain C-99 project. This project was developed for the PULP platform "Mr. Wolf". Contrary to the python version, the C code can only apply the event-based gQRS algorithm to one data-file at a time. Notice that this does not affect the results we are trying to obtain: the C-version is used to estimate the energy consumption of the algorithm on the Mr.Wolf platform. The F1-score, that gets computed anyway, is used merely to show that there is no variation between the two versions. The energy consumption of the method has very minor variations as we change the used file.
- Move into the "./data_parsing" folder and launch "makeDataHeader.py"
python3 makeDataHeader.py -f ../data/dataOut/[desired re-sampled folde]/[desired File].csv -d [Directory containing the attribute file for the target file] [ -a "Attribute extension" ]
This will create automatically the header containing the data from the file "selectedFile" to be used by the C code (data.h in ./c_gQRS). This is needed because the PULP platform simulates a hardware device, hence, it is not possible to easily interact with the underlying file system and open a file as we would usually do.
- Move to the "./c_gQRS" folder
- follow the steps at PULP platform SDK and toolchain.
make clean all run
This will start to run the simulation for the selected file multiple times, measuring several parameters of the simulation and returning an overview of the score-results and the performance-results. The performance results will be displayed for every core in the MCU (1 principal core and an 8-core cluster). The most interesting figures we are interested in are the number of cycles and the number of active cycles. These numbers, along with the average sampling frequency, give us the energy figure discussed in "An Event-Based System for Low-Power ECG QRS Detection".
- * Used for the python script execution and the SDK and toolchain build.
- Anaconda - Used as python environment manager for Jupyter.
- * Used for the python demonstrative Jupyter notebook.
- PULP SDK - SDK for the PULP platform.
- * Used for the build and execution of the C-version.
- Silvio Zanoli - ESL Lab, EPFL
- Tomas Teijeiro - ESL Lab, EPFL
- Fabio Montagna - University of Bologna
- David Atienza Alonso - ESL Lab, EPFL
This project is licensed under the GPL v3 License - see the <u>LICENSE.txt</u> file for details.
This work has been funded by:
- The Human Brain Project (HBP) SGA2 (GA No. 785907)
- The DeepHealth Project (GA No. 825111)
- The SNF through the ML-Edge Project (GA No. 182009)
- The ESL Lab