- 
PhysioNet  ·  PhysioBank  ·  PhysioToolkit

The WFDB Toolbox for MATLAB

What is the WFDB Toolbox for MATLAB?

This is a collection of WFDB applications implemented as functions in MATLAB. It is now possible to install through a simple web interface WFDB libraries for reading, writing, manipulating, and plotting records from PhysioBank, all within MATLAB.

By default, the WFDB Toolbox for MATLAB supports reading records directly from PhysioBank over the web (using HTTP). For example, in MATLAB, one can very simply download and plot a signal:

>> r = rdsamp('mitdb/100', 'maxt', ':10');
>> plot(r(:,1), r(:,2));

At the moment, the following functions are implemented:

rdann read annotation files for WFDB records
rdsamp read signal files of WFDB records
setwfdb set WFDB paths to default values
time2sec convert WFDB-format time intervals into seconds
wfdb_config return version and compilation information about the WFDB library
wfdbdesc return specifications for signals in WFDB records
wfdbwhich find the location of files belonging to WFDB records
wrann write annotations for WFDB records into annotation files
wrsamp write signal data into WFDB-compatible records

These include the most essential WFDB functions; as development continues, many more are expected to be implemented.


Notes about implementation

The WFDB Toolbox for MATLAB makes use of the compiled WFDB library itself. This means that separate shared libraries are distributed for each supported platform (operating system and CPU).

The Java Native Interface, or JNI, is used to create bindings to the WFDB library from Java code: system-independent Java code implements the WFDB Toolbox, and it makes use of the native WFDB library through JNI.

SWIG is used to create bindings for the WFDB library automatically: it creates a thin layer of code, using JNI, to interface with WFDB.

To use the WFDB Toolbox, you must have installed MATLAB 7 (R14, 2004) or later, with a working Java Virtual Machine (JVM) that supports Java 1.4 or later. There are currently no plans to support earlier versions of MATLAB or Java. If necessary, it may be possible to upgrade the JVM used by an installation of MATLAB; see this MathWorks technical note on the subject.

The WFDB Toolbox has been developed and tested using Sun's Java (available freely from http://www.java.com). It is compatible with at least some versions of OpenJDK (IcedTea); if you have problems installing it using IcedTea, try using Sun's Java. Future versions of OpenJDK and of the WFDB Toolbox should be fully compatible.


Supported Platforms

The WFDB Toolbox has been tested on all platforms currently supported by MATLAB, except for Solaris 64; it additionally runs on MacOS X PPC (which is supported only by older versions of MATLAB).


Operating systems and architectures

The following table shows which CPU architectures are supported for which operating systems.

AMD64, a.k.a. x86-64 i386, a.k.a. x86 (IA-32) PowerPC
Windows XP, Windows Vista YES YES N/A
GNU/Linux YES YES N/A
Mac OS X NO YES YES

Support for AMD64 under Mac OS X is expected soon. Current versions of MATLAB do not run on PowerPC; older versions were available for PowerPC under Mac OS X only.

Currently, only Mac OS X version 10.5 (Leopard) has been tested; it is expected that earlier versions will work, but they have yet to be tested.

Under GNU/Linux, glibc 2.3.0 or higher, and a Linux 2.6.x kernel must be used. As these are not especially new versions, most modern systems should work fine.


MATLAB versions

Though only a few versions of MATLAB have been tested (including 7.0, 7.1, 7.3, and 7.7), the WFDB Toolbox is expected to work for any version of MATLAB with a JVM version 1.4.0 or higher. If you are having trouble with a version of MATLAB that you think should work, you are strongly encouraged to contact us so that we can investigate the problem.


Downloading

The WFDB Toolbox for Matlab is available for direct installation via a Java Web Start application. This makes it very easy to download and install the package, as long as you have a Java Runtime Environment installed.

The steps that the installer will take are summarized briefly below.

First, you will see a security window asking for permission to allow the installer to run; this is necessary because the WFDB Toolbox must be installed to the file system.
Next, a panel with some introductory information will appear.
The installer will then search for installations of MATLAB. When it is done, you may search the file system for any other installations that it did not find.
Once the MATLAB installations have been selected, the WFDB Toolbox will be installed, and MATLAB will be updated to use them. The installer needs to update MATLAB's classpath.txt and librarypath.txt files, so you may be prompted for a superuser (root, administrator) password (or asked to make these files accessible.) Also, a brief test of the WFDB Toolbox will be run for each version of MATLAB selected.
Finally, a summary of the installation will be displayed. If the WFDB Toolbox could not be installed for some version of MATLAB, or if the brief test was not successful, such information will be displayed here.

In some cases, the installer will be unable to update the MATLAB path to include the directories for the WFDB Toolbox. If this is the case, a dialog box will be shown as the installer is exiting, to inform you about this and assist in updating the path manually (MATLAB's pathtool function can normally be used.) This may happen if there does not appear to be a MATLAB userpath variable set.

Before the installer exits, it will ask whether it should launch MATLAB with a short demonstration script that uses rdsamp and rdann to plot a signal and its annotations.


Other notes about the Java Web Start installer

As the installer runs, it will launch MATLAB several times; on Windows, you may see MATLAB windows pop up briefly, and then disappear. This is normal, and you may safely ignore these windows (do not attempt to close them.)

If one of these runs of MATLAB appears to be taking too long, please note that it is run with a time limit, and will be killed after a couple of minutes, if necessary.

The Java Runtime Environment (JRE) on your computer (not the JVM that MATLAB uses) should be version 1.5.0 or higher to run the WFDB Toolbox installer. If your system has an older version, you can still use the WFDB Toolbox installer, and Java Web Start should automatically download and set up a newer JRE version.

If the Java Web Start installer does not work properly, and you think it should, please contact us so we can address the problem. Please indicate your operating system, version of MATLAB, and a copy of the installer's log (see the "View Log" button in the bottom-leftmost corner of the installer window.)


Other methods of installation

For GNU/Linux and Mac OS X, a shell script is provided to install the WFDB Toolbox for MATLAB without using Java Web Start. The script's -h option prints details on how it can be used. The -p option is used to specify the path of a directory holding the JAR files needed for installation (see below for notes on compilation.) The -p option can instead take a URL, though, which is typically easier. E.g.,

$ ./install.sh -p http://physionet.org/physiotools/beta/wfdb-swig-matlab
will download (as a set of JAR files) and install the latest version of the WFDB Toolbox. There is also a -g option which allows "global," i.e. system-wide installation, for all users.

Note that install.sh, unlike the Java Web Start installer, can only install for one version of MATLAB at a time.

If all else fails, the necessary JAR files may be downloaded and installed manually. Please see the file README.manual-inst for instructions on how to do this.


Compiling from source code

Of course, the latest source code may be downloaded and compiled. Please see the README file within the tarball for instructions on compilation.

Please note that the WFDB Toolbox for MATLAB has a number of dependencies that it includes as native shared libraries. These are pre-compiled and distributed both with the Java Web Start installer, and in downloadable JAR files (see above.) The source-code tarball does not include source for these dependencies; they must be downloaded and compiled separately, for the target operating system and architecture.


Notes on dependencies

The following external dependencies are used by the WFDB Toolbox for MATLAB. The version numbers listed are those of the shared libraries distributed with the WFDB Toolbox; using a newer minor version of any of these should be safe, but is not necessarily guaranteed to work.

cURL 7.19.3 http://curl.haxx.se
GnuTLS 2.6.4 http://www.gnu.org/software/gnutls
GnuPG 1.4.4 http://www.gnupg.org
Libgpg-error 1.7 http://www.gnupg.org/download/#libgpg-error
Libidn 1.12 http://www.gnu.org/software/libidn
WFDB 10.4.18 http://www.physionet.org/physiotools/wfdb.shtml
WFDB SWIG Wrappers 10.4.1 http://www.physionet.org/physiotools/wfdb-swig.shtml

Note that GnuTLS, GnuPG, and Libgpg-error can be omitted if SSL support in cURL is turned off.

Compilation on GNU/Linux and Mac OS X is fairly straightfoward. On Windows, MinGW is required. It should be possible to use Cygwin's gcc with the -mno-cygwin option to compile native Windows binaries, but this has not been tested. Linking with Cygwin's POSIX emulation DLL (cygwin1.dll) is not recommended, as it does not interact well with JNI.


Send feedback about this page to PhysioNet

Your comments and suggestions are welcome. We encourage you to use our feedback form to comment on this page. If you would like to receive a reply, please send your comments by email to webmaster@physionet.org, or post them to:

PhysioNet
MIT Room E25-505A
77 Massachusetts Avenue
Cambridge, MA 02139 USA

Updated Tuesday, 19-May-2009 21:27:37 EDT National Institute of Biomedical Imaging and Bioengineering National Institutes of Health National Institute of General Medical Sciences