Construe
An abductive framework for the interpretation of time series, with special application to ECG data.
Install / Use
/learn @citiususc/ConstrueREADME
Construe
Construe is a knowledge-based abductive framework for time series interpretation. It provides a knowledge representation model and a set of algorithms for the interpretation of temporal information, implementing a hypothesize-and-test cycle guided by an attentional mechanism. The framework is fully described in the following paper:
[1]: T. Teijeiro and P. Félix: On the adoption of abductive reasoning for time series interpretation, Artificial Intelligence, 2018, vol. 262, p. 163-188. DOI:10.1016/j.artint.2018.06.005.
In this repository you will find the complete implementation of the data model and the algorithms, as well as a knowledge base for the interpretation of multi-lead electrocardiogram (ECG) signals, from the basic waveforms (P, QRS, T) to complex rhythm patterns (Atrial fibrillation, Bigeminy, Trigeminy, Ventricular flutter/fibrillation, etc.). In addition, we provide some utility scripts to reproduce the interpretation of all the ECG strips shown in paper [1], and to allow the interpretation of any ECG record in the MIT-BIH format with a command-line interface very similar to that of the WFDB applications.
Additionally, the repository includes an algorithm for automatic heartbeat classification on ECG signals, described in the paper:
[2]: T. Teijeiro, P. Félix, J.Presedo and D. Castro: Heartbeat classification using abstract features from the abductive interpretation of the ECG, IEEE journal of biomedical and health informatics, 2018, vol. 22, no 2, p. 409-420. DOI: 10.1109/JBHI.2016.2631247 .
The Construe algorithm is also the basis for the arrhythmia classification method described in the following papers:
[3]: T. Teijeiro, C.A. García, D. Castro and P. Félix: Arrhythmia Classification from the Abductive Interpretation of Short Single-Lead ECG Records, Computing in Cardiology, 2017, vol. 44, p. 1-4. DOI: 10.22489/CinC.2017.166-054.
[4]: T. Teijeiro, C.A. García, D. Castro and P. Félix: Abductive reasoning as the basis to reproduce expert criteria in ECG Atrial Fibrillation identification. Physiological Measurement, 39(8), 084006. DOI: 10.1088/1361-6579/aad7e4
This method won the First Prize in the Physionet/Computing in Cardiology Challenge 2017, providing the best results in Atrial Fibrillation detection among the 75 participating teams.
Installation
This project is implemented in pure python 3, so no installation is required. However, the core algorithms have strong dependencies with the following python packages:
In addition, the knowledge base for ECG interpretation depends on the following packages:
As optional dependencies to support the interactive visualization of the interpretation results and the interpretations tree and to run the demo examples, the following packages are also needed:
Finally, to read ECG signal records it is necessary to have access to a proper installation of the WFDB software package.
To make easier the installation of Python dependencies, we recommend the Anaconda or Miniconda Python distributions. Alternatively, you can install them using pip with the following command:
~$ pip install -r requirements.txt
NOTE: It is possible that Construe doesn't work with the latest versions of some of the dependencies. For this reason, we have included in the repository an Anaconda Environment file named construe_environment.yml with tested versions for all the dependencies.
Once all the dependencies are satisfied, it is enough to download the project sources and execute the proper python or bash scripts, as explained below. Please note that all our tests are performed on Linux environments, so unexpected issues may arise on Windows or OS-X environments. Please let us know if this is the case.
Getting started
Construe as a tool for ECG analysis
Along with the general data model for knowledge description and the interpretation algorithms, a comprehensive knowledge base for ECG signal interpretation is provided with the framework, so the software can be directly used as a tool for ECG analysis in multiple abstraction levels.
Interpreting external ECG records. The construe-ecg tool:
Any ECG record in MIT-BIH format can be interpreted with the Construe algorithm. This is done via the construe_ecg.py script, which is intended to be used as a production command-line tool that performs background interpretations of full ECG records (or sections). The result is a set of annotations in the MIT format. This tool tries to follow the WFDB Applications command-line interface. The usage of the construe-ecg application is as follows:
usage: construe_ecg.py [-h] -r record [-a ann] [-o oann]
[--level {conduction,rhythm}] [--exclude-pwaves]
[--exclude-twaves] [-f init] [-t stop] [-l length]
[--overl OVERL] [--tfactor TFACTOR] [-d min_delay]
[-D max_delay] [--time-limit TIME_LIMIT] [-k K] [-v]
[--no-merge]
Interprets a MIT-BIH ECG record in multiple abstraction levels, generating as
a result a set of annotations encoding the observation hypotheses.
optional arguments:
-h, --help show this help message and exit
-r record Name of the record to be processed
-a ann Annotator containing the initial evidence. If not
provided, the gqrs application is used.
-o oann Save annotations as annotator oann (default: iqrs)
--level {conduction,rhythm}
Highest abstraction level used in the interpretation.
Using the "conduction" level produces just a wave
delineation for each QRS annotation in the initial
evidence, while the "rhythm" level also includes a
rhythm interpretation of the full signal, but at the
expense of a higher computational cost in several
orders of magnitude.
--exclude-pwaves Avoids searching for P-waves. Default:False
--exclude-twaves Avoids searching for T-waves. It also implies
--exclude-pwaves Default:False
-f init Begin the interpretation at the "init" time, in
samples
-t stop Stop the interpretation at the "stop" time, in samples
-l length Length in samples of each independently interpreted
fragment. It has to be multiple of 256. Default:23040
if the abstraction level is "rhythm", and 640000 if
the abstraction level is "conduction".
--overl OVERL Length in samples of the overlapping between
consecutive fragments, to prevent loss of information.
If the selected abstraction level is "conduction",
this parameter is ignored. Default: 1080.
--tfactor TFACTOR Time factor to control the speed of the input signal.
For example, if tfactor = 2.0 two seconds of new
signal are added to the signal buffer each real
second. A value of 1.0 simulates real-time online
interpretation. If the selected abstraction level is
"conduction", this parameter is ignored. Default: 1e20
-d min_delay Minimum delay in samples between the acquisition time
and the last interpretation time. If the selected
abstraction level is "conduction", this parameter is
ignored. Default: 2560
-D max_delay Maximum delay in seconds that the interpretation can
be without moving forward. If this threshold is
exceeded, the searching process is pruned. If the
selected abstraction level is "conduction", this
parameter is ignored. Default: 20.0
--time-limit TIME_LIMIT
Interpretation time limit *for each fragment*.If the
interpretation time exceeds this number of seconds,
the interpretation finishes immediately, moving to the
next fragment. If the selected abstraction level is
"conduction", this parameter is ignored. Default:
Infinity
-k K Exploration factor. It is the number of
