Waveform Database Software Package (WFDB) for MATLAB and Octave

Abstract

Physiological waveforms - such as electrocardiograms (ECG), electroencephalograms (EEG), electromyograms (EMG) - are generated during the course of routine care. These signals contain information that can be used to understand underlying conditions of health. Effective processing and analysis of physiological data requires specialized software. The WaveForm DataBase (WFDB) Toolbox for MATLAB and Octave is a collection of over 30 functions and utilities that integrate PhysioNet's open-source applications and databases with the high-precision numerical computational and graphics environment of MATLAB and Octave.

Background

Physiological waveforms - such as electrocardiograms (ECG), electroencephalograms (EEG), electromyograms (EMG) - are generated during the course of routine care. These signals contain information that can be used to understand underlying conditions of health. For example, ECGs aid diagnosis of abnormal heart conditions, EEGs aid detection of disorders such as epilepsy, and EMGs aid diagnosis of neuromuscular diseases. Despite the potential utility of waveforms, their complexity and granularity present challenges for retrospective analysis. Effective storage, processing and analysis of physiological signals requires specialized software.

The original Waveform Database (WFDB) Software Package, written in C, provides a large collection of software for processing and analyzing physiological waveforms [1]. The WFDB Toolbox for MATLAB and Octave is a collection of over 30 functions and utilities that integrate PhysioNet's open-source applications and databases with the high-precision numerical computational and graphics environment of MATLAB and Octave [2,3]. Similar themed software is also available in Python [4].

Software Description

The WDFB Toolbox for MATLAB and Octave provides functions useful for loading physiological signals. The function RDSAMP, for example, allows users to load PhysioNet waveform data. If the database signals are not cached locally, they are automatically fetched from PhysioNet’s servers using HTTP and stored locally for future access. The RDANN function is used to load annotations (e.g. arrhythmia events, evoked potential epoch markers, epileptic seizure onset) that have been generated by medical experts or by medical algorithms.

The toolbox also has functions for processing signals. Some of these functions consist of MATLAB/Octave wrappers for open-source C-code functions published in the literature and contributed by user’s to PhysioNet. Among the currently implemented wrappers are ECGPUWAVE and EDR [5,6]. The Toolbox also contains a wrapper, BXB, to a function for testing and reporting performance results of cardiac rhythm and ST segment measurement algorithms according to ANSI/AAMI EC38:1998.

Technical Implementation

The top level of the toolbox consists of HTML documentation files and *.m files. The MATLAB/Octave layer is responsible for interfacing between the user and the toolbox. This MATLAB/Octave layer is linked through a Java API (provided either through MATLAB or Octave) to a set of Java classes. These Java classes are responsible for path configuration, library loading, I/O parsing, multi-thread processing, and basic database queries. The Java classes are linked to WFDB native binaries through standard input, output, and error pipes that are created when the JVM performs a system call.

Unit tests

A unit testing framework has been developed to promote stability in both MATLAB and Octave environments. These tests helps to ensure that documented examples work as expected in all the supported environments, across Windows, MacOS, and Unix systems. In some cases, tests for known, unfixed issues are included. These issues are documented through the repository tracking system.

Installation and Requirements

The WFDB Toolbox for MATLAB includes and uses its own copies of the compiled WFDB library and many of the WFDB applications. This means that separate shared libraries and executable applications are components of the toolbox for each supported platform (operating system and CPU). Installing the WFDB Toolbox for MATLAB does not interfere with any separate installation of the WFDB Software Package [1].

To install or update a previous installation of this Toolbox:

1. Open MATLAB or Octave.
2. Go into the directory where you wish to install the Toolbox:

   cd directoryname
   

3. Type (or copy and paste) the following commands into the MATLAB or Octave window:

   [old_path]=which('rdsamp'); if(~isempty(old_path)) rmpath(old_path(1:end-8)); end
   wfdb_url='https://physionet.org/physiotools/matlab/wfdb-app-matlab/wfdb-app-toolbox-0-10-0.zip';
   [filestr,status] = urlwrite(wfdb_url,'wfdb-app-toolbox-0-10-0.zip');
   unzip('wfdb-app-toolbox-0-10-0.zip');
   cd mcode
   addpath(pwd)
   savepath
   

Requirements

• 64-bit GNU/Linux, Mac OS X 10.9, or MS-Windows. Other platforms may also work, but these will require compiling the Toolbox from source.
• MATLAB R2014a or later, with a working Java Virtual Machine (JVM) that supports Java 1.7 or later; or GNU Octave 3.8.1 or later with the Java package.

Usage Notes

The source code for the WFDB Software is publicly available on GitHub [3]. If you are a user of the software and encounter issues, then we suggest searching to see if the issue is already tracked on the GitHub repository. If not, then please raise a new issue, clearly describing the problem that you have encountered and what steps you have taken to try to address it.  We have limited resources to support the software, and so we encourage community contributions via pull requests. 

We also highly recommend reviewing documentation on the original C language implementation of the software [1]. This documentation provides detailed background on various aspects of the WFDB library, including file structures, terminology, and general user guidance.

Release Notes

For the latest stable version of the software, we recommend referring to GitHub [3].

Conflicts of Interest

The authors have no conflicts of interest to declare.

References

1. Moody, G., Pollard, T., & Moody, B. (2021). WFDB Software Package (version 10.6.2). PhysioNet. https://doi.org/10.13026/zzpx-h016
2. Silva I, Moody G. An Open-source Toolbox for Analysing and Processing PhysioNet Databases in MATLAB and Octave. Journal of Open Research Software. 2014;2(1):e27. DOI: http://doi.org/10.5334/jors.bi
3. WFDB MATLAB on GitHub. https://github.com/ikarosilva/wfdb-app-toolbox [Accessed: 1 March 2021]
4. Xie, C., McCullum, L., Johnson, A., Pollard, T., Gow, B., & Moody, B. (2021). Waveform Database Software Package (WFDB) for Python (version 3.3.0). PhysioNet. https://doi.org/10.13026/g35g-c061.
5. Laguna P. et al (2018). ECGPUWAVE: QRS detector and waveform limit locator. PhysioNet. https://physionet.org/content/ecgpuwave/.
6. Lipsitz L and Moody G (2000). ECG-Derived Respiration. PhysioNet. https://physionet.org/content/edr/