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:
: T. Teijeiro and P. Félix: On the adoption of abductive reasoning for time series interpretation, 2016, arXiv:1609.05632.
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 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 , and to allow the interpretation of any ECG record in the MIT-BIH format.
Recently, we have also included an algorithm for automatic heartbeat classification on ECG signals, described in the paper:
: T. Teijeiro, P. Félix, J.Presedo and D. Castro: Heartbeat classification using abstract features from the abductive interpretation of the ECG
This project is implemented in pure python, 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:
To support visualization of the interpretation results and the interpretations tree and run the usage 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 Python distribution. Alternatively, you can install them using pip with the following command:
~$ pip install -r requeriments.txt
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.
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.
All signal strips in  are included as interactive examples to make it easier to understand how the interpretation algorithms work. For this, use the
run_example.sh script, selecting the figure for which you want to reproduce the interpretation process:
Once the interpretation is finished, the resulting observations are printed to the terminal, and two interactive are shown. One plots the ECG signal with all the observations organized in abstraction levels (deflections, waves, and rhythms), and the other shows the interpretations tree explored to find the result. Each node in the tree can be selected to show the observations at a given time point during the interpretation, allowing to reproduce the abduce, deduce, subsume and predict reasoning steps .
Interpreting external ECG records
Any ECG record in MIT-BIH format can be interpreted with the Construe algorithm. For this, we provide two convenient python modules that may be used as command-line tools. The first one (
fragment_processing.py) is intended to visually show the result of the interpretation of a (small) ECG fragment, allowing to inspect and reproduce the interpretation process by navigating through the interpretations tree. The second one (
record_processing.py) is intended to perform background interpretations of full records, resulting in a set of annotations in the MIT format. Both tools follow the WFDB Aplications command-line interface, and usage details are available with the
Using Construe in another problems and domains
We will be glad if you want to use Construe to solve problems different from ECG interpretation, and we will help you to do so. The first step is to understand what is under the hood, and the best reference is . After this, you will have to define the Abstraction Model for your problem, based on the Observable and Abstraction Pattern formalisms. As an example, a high-level description of the ECG abstraction model is available in , and its implementation is in the
knowledge subdirectory. A tutorial is also available in the project wiki.
Once the domain-specific knowledge base has been defined, the
fragment_processing.py module should serve as a basis for the execution of the full hypothesize-and-test cycle with different time series and the new abstraction model.
The source code is structured in the following main modules:
acquisition: Modules for the acquisition of the raw time series data. Currently it is highly oriented to ECG data in the MIT-BIH format.
inference: Definition of the interpretation algorithms, including the construe algorithm and the reasoning modes (abduce, deduce, subsume, predict and advance) .
knowledge: Definition of the ECG abstraction model, including observables and abstraction patterns.
model: General data model of the framework, including the base class for all observables and classes to implement abstraction grammars as finite automata.
utils: Miscellaneous utility modules, including signal processing and plotting routines.
- The ECG knowledge base is prepared to interpret records with any sampling frequency, but if frequency differs from 250 Hz the value has to be manually adjusted in
construe/utils/units_helper.py, line 13.
- Abductive interpretation of time-series is NP-Hard . This implementation includes several optimizations to make computations feasible, but still the running times are probably longer than you expect. Try the
-v flag to get feedback and make the wait less painful ;-).
This project is licensed under the terms of the GPL v3 license.