About this Guide

You should have a good grasp of the C language in order to make the best use of this guide. If ANSI C prototypes, used here to document the WFDB library functions, are unfamiliar to you, see pp. 217–218 in the second edition of The C Programming Language by Kernighan and Ritchie, Prentice Hall, 1988. (This is the famous K&R; all K&R references in this guide include page numbers for the second edition. Newcomers to C should have a copy for ready reference while reading this guide.) It may also be helpful to have a copy of a database directory, such as the MIT-BIH Arrhythmia Database Directory. The WFDB Applications Guide will be useful as a reference for existing WFDB library-based applications (available from PhysioNet, http://physionet.org/).

You should have access to a computer that has the WFDB library and at least one or two database records on-line, or access to the World Wide Web, where database records can be obtained from PhysioNet and other sources. (If you are installing the WFDB library on a new computer for the first time, please read the installation notes supplied with the WFDB library first, or see section Installing the WFDB Software Package, then return here.) You should know how to create a C source file using your favorite editor, and you should know how to compile it and how to run the resulting executable program.

Resist all temptation to plunge into the esoteric details of file formats. (Those who find such details irresistible will find them in Section 5 of the WFDB Applications Guide; note, however, that support for new file formats is added to the WFDB library from time to time, so that the information you find there may be incomplete.) The WFDB library provides an efficient means of reading and writing files in many formats; it is not a trivial task to duplicate it, and time spent doing so is time that could be spent doing something useful, enjoyable, or possibly both. If you really think you need to understand the file formats in order to translate them into whatever the ECGWhizz Model 666 needs, consider instead writing a format translator using the WFDB library to read the files; then you will at least have a program that requires only recompilation with a new version of the WFDB library when file formats change. In extremis, use ‘rdann’ and ‘rdsamp’ — available from PhysioNet in source and ready-to run formats — to translate files into text format.

Chapter 1 of this guide begins with a simple example program that reads a few samples from a database record. The C version of this program is also translated into a variety of other languages supported by the WFDB library itself or by separately available bindings. This example should help you understand the mechanics of compiling and using a program that does something with an ECG database. Chapter 2 introduces the library functions themselves, with a number of brief examples; you may wish to skim through this material on a first reading to get acquainted with what is available, and then refer to it as needed while writing your programs. Data structures for annotations and for signal and annotator attributes are described in chapter 3. Chapter 4 contains a table of annotation types and descriptions of several annotation-mapping macros. Database files and related topics are discussed in chapter 5, which can be skipped on a first reading. Chapter 6 contains additional example programs that illuminate a few of the darker corners of the WFDB library. The glossary defines the ordinary-sounding words such as signal that have specialized meanings in this guide; such words are emphasized in their first appearances in order to warn you that you should look them up in the glossary on a first reading (see section Glossary).

If the WFDB library has not yet been installed on your system, see section Installing the WFDB Software Package. Another appendix (see section WFDB Application Programs) includes brief descriptions of the application programs that are distributed with the WFDB library as part of the WFDB software package.

Another appendix discusses porting the WFDB library to new machines or operating systems, and includes notes on adding support for new file formats, annotation codes, and other enhancements (see section Extensions). The WFDB library has been written with portability in mind. It runs on a wide variety of machines and operating systems, including Unix (BSD 4.x, System V, SunOS, Solaris, HP-UX, OSF/1, Version 7, XENIX, VENIX, ULTRIX, GNU/Linux, FreeBSD, OpenBSD, IRIX, AIX, AUX, Darwin, Mac OS X, SCO, Coherent, and more), MS-DOS, MS-Windows, VMS, and classic Mac OS. This guide was written for Unix users (with notes for MS-Windows and MS-DOS users where differences exist), but others should find only minor differences.

At the end of the guide is a list of sources for databases and other materials that may be useful to readers (see section Sources), and a log of changes made to this library since 1999 (see section Recent Changes).

Many friends have contributed to the development of the WFDB library. Thanks to Paul Albrecht, Ted Baker, Phil Devlin, Scott Greenwald, Thomas Heldt, Isaac Henry, David Israel, Roger Mark, Joe Mietus, Warren Muldrow, Ikaro Silva, Wei Zong, and especially to Paul Schluter, whose elegant 8080 assembly language functions inspired these (long live getann!). Pat Hamilton and Bob Farrell contributed ports, to classic Mac OS and the MS 32-bit Windows environments, respectively. Jose Garcia Moros and Salvador Olmos contributed Matlab/Octave reimplementations of a useful subset of the WFDB library. Jonas Carlson wrote, documented, and contributed a set of Matlab wrappers for the WFDB library, and Michael Craig created and contributed the WFDB Toolbox for Matlab. Isaac Henry contributed SWIG wrappers that provide interfaces for a variety of scripting languages, as well as a set of translations of the C example programs in this guide into the languages supported by the SWIG wrappers. Mike Dakin provided the first implementation of NETFILES (HTTP client support in the WFDB library) based on the W3C’s libwww. Following the W3C’s decision to end development of libwww, Benjamin Moody reimplemented NETFILES using libcurl, and also implemented variable-layout records. Bug reports (and in some cases fixes) have been contributed by Omar Abdala, Winton Baker, David Brooks, Bob Farrell, Virginia Faro-Maza, Ion Gaztañaga, Fred Geheb, Mathias Gruber, Thomas Heldt, Isaac Henry, Justin Leo Chang Loong, Benjamin Moody, Guido Muesch, Joonas Paalasmaa, Tony Ricke, Dave Schaffer, Dan Scott, Allavatam Venugopal, Mauro Villarroel, Andrew Walsh, Piotr Wlodarek, and Yinqi Zhang. Thanks also to the many readers of earlier versions of this guide; if this edition answers your questions, it is because someone else has already asked them, and hounded the author until he produced comprehensible answers.

Before May, 1999, and the release of version 10.0.0 of the library, the WFDB library was known as the DB library, and this guide was the ECG Database Programmer’s Guide. The name of the library was changed because of confusion caused by the proliferation of another library with the same name (a reimplementation of the Berkeley Unix DBM library). The names of this guide, and of the WFDB Applications Guide (formerly the ECG Database Applications Guide), have been changed in view of the increasingly broad range of applications in which the library is being used.

The first edition of this guide was written as a tutorial for MIT students using the ECG databases for a variety of signal-processing and analysis projects. The guide, and the WFDB library itself, have been extensively revised since they first appeared in 1981. Your comments and suggestions are welcome. Please send them to:

PhysioNet  <wfdb@physionet.org>
MIT Room E25-505A
Cambridge, MA 02139
USA

If you use the GNU emacs editor, you can peruse a hypertext version of this guide using info if it has been installed on your system; among its many other features, emacs makes it easy to copy code from the examples into your own programs. Installation instructions are included in the WFDB Software Package; type C-h i within GNU emacs to start up info (see section Sources, for information about obtaining GNU emacs).

You can format and print copies of this guide using TeX if you have it (see ‘makefile’ in the ‘doc’ directory of the library distribution for instructions on doing so). You may obtain preformatted versions in PDF and PostScript formats from http://physionet.org/.