Event_based_gQRS/ef25f566de33master
README.md
Event-based gQRS
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 submitted and accepted for the DATE2020 conference, Tuesday, March 10, 2020
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 the Nyquist sampling theorem is not respected and 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 is possible to find the source code for the event-based gQRS.
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 attribute 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 (Jupiter 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.
The python demonstrative version, C version implemented on the PULP platform, Mr.Wolf, and the tools necessary to extract and re-sample the data can be found here.
Getting Started
Requirements
Python version:
- Jupyter-notebook
- Python 3.6.x*
- Numpy
- Pandas
- Matplotlib
- wfdb
- tqdm
C version:
- Python 3.5.3*
- GCC
\* 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. The python version this code was designed with (the Python part) is python 3.6.x and 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 (tested on 3.7.1)
Installing and Running
- Clone the repository and set the root directory of the project.
- Create a data folder on the root directory of this project, 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'
Python version:
- 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 (specificity, positive predictivity, and F1-Score). The results will be also listed inside the same Jupyter notebook.
C version:
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 the time. Notice that this does not affect the results we are trying to obtain: the C-version is used to measure (indirectly) the energy consumption of the algorithm on the Mr.Wolf platform. The F1-score, that get computed anyway, is used merely to show 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 the lack of I/O routines for file reading.
- Move to the "./c_gQRS" folder
- follow the steps at PULP platform SDK and toolchain.
- Execute:
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".
Built With
- * 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 Jupiter notebook
- PULP SDK - SDK for the PULP platform
- * Used for the build and execution of the C-version
Authors
- Silvio Zanoli - ESL Lab, EPFL
- Tomas Teijeiro - ESL Lab, EPFL
- Fabio Montagna - University of Bologna
- David Atienza Alonso - ESL Lab, EPFL
License
This project is licensed under the GPL v3 License - see the <u>LICENSE.txt</u> file for details
Acknowledgments
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