\documentclass[twoside]{book}
\nofiles
\usepackage{rawfonts}
\IfFileExists{times.sty}{\usepackage{times}}{\@missingfileerror{times}{sty}}
\usepackage{fancyhdr}
\oddsidemargin 0.1in
\evensidemargin -0.1in
\topmargin -0.5in
\textheight 650pt
\footskip 48pt
\def\textwidth{6.375 in}
\pagenumbering{roman}
\def\headrulewidth{0pt}
\lhead{\rm{}Contents}
\chead{\rm{}WFDB Applications Guide}
\rhead{\rm{}Contents}
\lfoot[\rm\thepage]{\rm{}WFDB VERSION}
\cfoot{\rm{}LONGDATE}
\rfoot[\rm{}WFDB VERSION]{\rm\thepage}
\title{WFDB Applications Guide}
\author{Tenth Edition\\
(revised and with corrections for WFDB VERSION)\\
LONGDATE\\
\\
\\
\\
George B. Moody\\
Harvard-MIT Division of Health Sciences and Technology}
\date{}
\begin{document}
\maketitle
\pagestyle{empty}
\vspace*{\fill}
\noindent
Copyright \copyright 1980 -- 2014 George B. Moody
\vspace{1 in}
\noindent
The most recent versions of the software described in this guide may be
freely downloaded from PhysioNet\\
({\tt http://www.physionet.org/}).
For further information, write to:
\begin{quote}
George B. Moody\\
Massachusetts Institute of Technology\\
77 Massachusetts Avenue, Room E25-505A\\
Cambridge, MA 02139\\
USA\\
\end{quote}
\noindent
An HTML version of this guide is available at
{\tt http://www.\-physio\-net.\-org/\-physio\-tools/\-wag/}.
\vspace{0.2 in}
\noindent
Permission is granted to make and distribute verbatim copies of this
guide provided that the copyright notice and this permission notice are
preserved on all copies.
\vspace{0.2 in}
\noindent
Permission is granted to copy and distribute modified versions of this
guide under the conditions for verbatim copying, provided also that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
\vspace{0.2 in}
\noindent
Permission is granted to copy and distribute translations of this guide
into another language, under the above conditions for modified versions.
\newpage
\pagestyle{fancyplain}
\tableofcontents
\newpage
\lhead{\rm{}Introduction}
\chead{\rm{}WFDB Applications Guide}
\rhead{\rm{}Introduction}
\chapter*{Introduction}
Most of this guide consists of UNIX \textbf{man} pages that describe the
applications included in the WFDB (Waveform Database) Software
Package (and related software from PhysioToolkit). This introduction
contains important information about how to interpret the material in
the main sections of the guide, and about common conventions for using
all of the WFDB applications that are not described in the main sections.
The FAQ that follows this introduction contains additional information
that will be particularly helpful if you are using MS-Windows (but it
may be of interest even if you are not).
\section*{Using this Guide}
The organization follows the traditional arrangement of the UNIX Reference
Manual: section 1 contains programs, section 3 contains libraries, and
section 5 contains file formats. In the UNIX Reference Manual, sections
2 and 4 are reserved for system calls and device interfaces respectively;
these sections do not exist in this guide. Following convention, a
citation such as \textbf{rdann}(1) refers to the page titled \textbf{rdann}
in section 1 of this guide.
A \textbf{man} "page" may span more than one physical page, although most do
not. Each \textbf{man} page in section 1 of this guide documents one or more
applications, as indicated in the \textbf{NAME} section at the top. The
\textbf{SYNOPSIS} appears next; it illustrates the form of the command line
needed to run the application. In the synopsis, \textbf{boldface} indicates
text to be typed as is, and \textit{italics} indicate replaceable arguments;
brackets ([], which are \textit{not} to be typed) surround arguments that may
be omitted, and ellipses (...) follow arguments that can be repeated. The
\textbf{DESCRIPTION} sections are intentionally terse; this is a reference
manual and not a tutorial introduction to the software described within. In
those cases for which relevant tutorial material exists elsewhere, references
appear in the \textbf{SEE ALSO} sections of each \textbf{man} page. A unique
feature of this guide is the \textbf{SOURCE} section at the end of each page,
which provides a URL where you may find the current version of the source(s)
for each application.
On each page, the footer indicates the date when that page was last revised,
and (in most cases) the version of the WFDB Software Package that was current
at that time. An old date and version number do not mean that the page is
out-of-date; rather they mean that the material described on that page
remains current.
Under GNU/Linux, Mac OS X, or Unix, if the WFDB Software Package has
been installed on your system, you can also access the information
contained in the main sections of this guide using \textbf{man} and
related programs. For example, to see the manual page for
\textbf{rdsamp}, run the command
\begin{quote}
\textbf{man rdsamp}
\end{quote}
(This also works under MS-Windows if you have installed the
Cygwin package, which includes the \textbf{man} utility for formatting
and reading manual pages.) In some cases you may need to add
\textbf{/usr/local/man} to your \textbf{MANPATH} environment variable, in
order to make these pages accessible to \textbf{man}.
An HTML version of this guide is also available (at
\textbf{http://www.physionet.org/physiotools/wag/} ).
\section*{Using WFDB Applications}
If you have not used any of these programs before, you may need to set up
your environment properly so that WFDB applications can find their
input files. See \textbf{setwfdb}(1) in this guide for information about
doing this; a more detailed discussion may be found in the first chapter
of the \textit{WFDB Programmer's Guide}, in the section about the database
path. Most users will not need to do this, however.
Certain types of command-line arguments are used by many of the applications
described in this guide. These include:
\begin{description}
\item{\textit{record}}
Where this appears, substitute the name of a WFDB record. \textbf{A record
name is \textit{not} a file name!} The first part of the name of a .hea
file is the name of the record to which the .hea file belongs; so the
record name corresponding to `100.hea' is `100'. For example, MIT-BIH
Arrhythmia Database record names are 3-digit numbers, AHA Database
record names are 4-digit numbers, and European ST-T Database record
names begin with lowercase `e', followed by a 4-digit number. Record
names may contain letters, digits, and underscores. Case is significant in
record names that contain letters, even in environments such as
MS-Windows for which case translation is normally performed by the
operating system on file names; thus `e0104' is the name of a record
found in the European ST-T Database, whereas `E0104' is not. Once
again: a record name is \textbf{not} a file name; record names never
include an extension (.hea, .dat, etc.).
Wherever a record name can be supplied to a WFDB application, you may include
path information if necessary. For example, if the WFDB path includes the
current directory, and if the current directory includes a subdirectory named
`my\_records', and that directory contains a record named `record\_23', you can
supply `my\_records/record\_23' as a \textit{record} argument. See the
\textit{WFDB Programmer's Guide} for further details on record names.
Each PhysioBank database directory includes a text file named \textbf{RECORDS},
which lists the record names for all records in that directory.
\item{\textit{annotator}}
Where this appears, substitute an annotator name. \textbf{Annotator names are
\textit{not} file names!} The suffix (extension) of the name of an
annotation file is the annotator name for that file; so, for example, the
annotator name for `e0104.atr' is `atr'. The special annotator name `atr' is
used to name the set of \textit{reference annotations} supplied by the database
developers. Other annotation sets have annotator names that may contain
letters, digits, and underscores, as for record names.
Each PhysioBank database directory includes a text file named
\textbf{ANNOTATORS}, which lists the annotator names for all annotation files
in that directory.
\item{\textit{time}}
Where this appears, substitute a string in \textit{standard time format}.
\textit{Time} arguments generally specify elapsed times from the beginning
of the record (for exceptions to this rule, see the section on the
\textbf{strtim} function in the \textit{WFDB Programmer's Guide}). Examples
of standard time format:
\begin{center}
\begin{tabular}{lr}
2:14.875 & 2 minutes + 14.875 seconds \\
143 & 143 seconds (2 minutes + 23 seconds) \\
4:02:01 & 4 hours + 2 minutes + 1 second \\
4:2:1 & same as above \\
s12345 & 12345 sample intervals \\
e & time of the end of the record \\
\end{tabular}
\end{center}
\item{\textit{signal}}
Where this appears, substitute a signal number or (in most cases) a signal name.
Signal numbers are integers; the first signal in each record is signal 0.
In printed documentation for the databases, signals always appear with signal 0
at the top, signal 1 beneath, etc. Signal names are the strings printed by
\textbf{signame}(1).
\item{\textit{signal-list}}
Where this (or `\textit{signal ...}') appears, you may specify more than one
signal in any desired order; separate the signal numbers or names using spaces.
Unless otherwise noted, a signal may appear more than once, or not at all, in a
signal list. In most cases, the end of the signal list is unambiguous (since
signal numbers are never negative, and signal names rarely if ever begin with
'-', an option argument beginning with '-' is a reliable indicator). In unusual
cases, you may need to arrange options so that the signal list is at the end of
the command, or so that it is followed by an argument that cannot be
interpreted as a signal number.
\end{description}
\chapter*{Frequently Asked Questions\\(and Frequently Exclaimed Exclamations)}
\lhead{\rm{}FAQ}
\rhead{\rm{}FAQ}
\noindent
{\large
\textbf{I double-clicked on the program icon, and nothing happens!}\\
\textbf{I typed the program name in the 'Run...' dialog, and nothing happens!}}
\noindent
Don't do this!
With few exceptions, PhysioToolkit applications run in \textbf{text mode}
(i.e., they do not include a graphical user interface). These programs are
intended to be run within a terminal emulator using a command-line interface.
In most cases, if you attempt to run them by clicking on their icons or names,
or by entering the program name in the MS-Windows \textbf{Run...} dialog box,
these programs will open a DOS box, print a usage summary, and exit, usually
much too fast for you to read anything.
By far the best way to use these programs under MS-Windows is to install a
Unix-compatible terminal emulator and shell in which to run them. The best of
these is also free; if you have not already done so, download and install the
Cygwin software package from \textbf{http://www.cygwin.com/}. This package
includes \textbf{bash}, the GNU Bourne Again Shell and a terminal emulator in
which to run it. After a standard installation of Cygwin, you can launch a
terminal emulator and \textbf{bash} by clicking on the Cygwin icon that will
have been installed on your desktop.
If you do not wish to use Cygwin, it is possible to run these applications
within a DOS box, but there are many limitations of \textbf{command.com} that
may prove frustrating. In particular, \textbf{command.com} supports a
relatively small space for environment variables that is not secure against
buffer overruns, and has idiosyncratic filename globbing behavior.
\vspace{5mm}
\noindent
{\large \textbf{What does the message "init: can't open header for ..." mean?}}
\noindent
This message can be produced by any application linked to the WFDB
library, including \textbf{rdsamp}(1) and \textbf{rdann}(1). In order to
read data files, these applications need to find a header (\textbf{.hea})
file for the input record you specify. The message indicates that the header
file was not found in any of the expected places, or that it was
unreadable. There are three common reasons why this can happen:
\begin{itemize}
\item
The \textit{record} name supplied to the application is not correct. Record
names are \textbf{not} file names (if this doesn't sound familiar yet, go back
and read the introduction again). If you wish to read, for example, a signal
file named \textbf{slp60.dat} using \textbf{rdsamp}, you must specify the name
of the record to which this file belongs (\textbf{slp60}) after the \textbf{-r}
option, and not the name of the file itself. Whatever follows "init: can't
open header for ..." is what the application thinks is the name of the record
you wish to read. Also, be aware that case matters in record names, even under
operating systems that ignore case in file names. Thus "\textbf{SLP60}" is not
a valid record name; "\textbf{slp60}" is.
\item
The header file is missing. If you download signal (\textbf{.dat}) or
annotation (\textbf{.atr}, \textbf{.qrs}, etc.) files, be sure to download
the corresponding \textbf{.hea} files from the same locations.
\item
The list of locations to be searched does not include the location of
the header file. WFDB applications find their input files by searching
a list of locations specified by the WFDB path (the environment variable
\textbf{WFDB}, or a default list of locations if WFDB has not been set). The
WFDB path normally includes the current directory, but this may not be
true if the WFDB path has been modified; the current directory must
appear explicitly (either as a "." or as an empty component in the path)
in order to be included in the list of locations to be searched. For
further information, see "The Database Path and Other Environment Variables"
in the \textit{WFDB Programmer's Guide}.
\end{itemize}
\vspace{5mm}
\noindent
{\large \textbf{How can I save the output of ... in a file?} \\
\textbf{How can one program read another's output?}}
\noindent
If you are running programs from a command prompt (by typing commands into a
terminal emulator window or an MS-DOS box), these things can be done easily.
If you have ever used GNU/Linux, Unix, or MS-DOS, you may have captured the
output of a program by \textit{redirecting} it to a file, like this:
\begin{quote}
\textbf{foo $>$bar}
\end{quote}
The $>$ operator redirects \textbf{foo}'s standard output (which would normally
appear on-screen) into a file named \textbf{bar}. If \textbf{bar} exists
already, its contents are replaced. If you wish to append \textbf{foo}'s output
to whatever is already contained in \textbf{bar}, use a command such as this
instead:
\begin{quote}
\textbf{foo $>>$bar}
\end{quote}
There is an analogous operator that arranges for a program's standard input
(which would normally be read from whatever you type on the keyboard) to be
read from a file instead:
\begin{quote}
\textbf{baz $<$bar}
\end{quote}
Here, the $<$ operator arranges for \textbf{baz} to read its input from a file
named \textbf{bar}. If \textbf{bar} was created by \textbf{foo}, then this
command allows \textbf{baz} to read \textbf{foo}'s output.
You can combine input and output redirection in a single command using the pipe
($|$) operator:
\begin{quote}
\textbf{foo $|$ baz}
\end{quote}
This command runs \textbf{foo} and sends its standard output directly to
\textbf{baz}, without requiring an intermediate file. True multitasking
operating systems such as Unix and GNU/Linux allow both programs to run
(apparently) simultaneously; under MS-DOS or MS-Windows, the first program runs
to completion before the second one begins execution.
You can use these techniques whenever you run programs from a command prompt,
whether those programs are among those available here or obtained from some
other source. You can use the same techniques with programs you write yourself;
the only requirement is that your programs must read from the standard input
and write to the standard output (i.e., they must not attempt to bypass the
standard input/output mechanism by reading directly from the keyboard or
writing directly to the screen).
These operators ($>$, $>>$, $<$, and $|$) are supported by all shells (command
interpreters) under Unix, GNU/Linux, and MS-DOS (including those that run
within MS-DOS boxes or other types of terminal emulators under MS-Windows). For
further information, please refer to the documentation for your shell or
command interpreter.
\vspace{5mm}
\noindent
{\large
\textbf{Where else can I find answers to my questions about this software?}}
\noindent
If you haven't read the introduction to this guide yet, do so now. It answers
many frequently asked questions by describing the common behavior of many of
the WFDB applications. It also describes the typographic and organizational
conventions used in the remainder of this guide.
Many more questions are asked and answered in the PhysioNet FAQ
(http://www.physionet.org/faq.shtml).
\end{document}