ECG Database Applications Guide
Table of Contents
wave - waveform analyzer, viewer, and editor for the X Window System
wave -r record[+record ...] [ options ... ]
wave can be used
to view the specified DB record or records on any display controlled by
an X11 server. It includes facilities for interactive annotation editing.
The keyboard and mouse are used to control the display interactively.
First-time users should read the WAVE User's Guide. (One way to do this
is by pointing your Web browser to file:///usr/local/help/html/wug/wug.htm,
or to http://ecg.mit.edu for the latest version.) If the Guide is unavailable,
print a copy of the on-line manual; run wave without any command-line arguments
to get instructions for doing so. Note that this operation does not require
an X display.
If you specify more than one record, a separate wave process
is started for each record. Note that all records to be opened must be
listed in a single command-line argument following -r, with + characters
(not spaces) between the record names. See `Running two or more WAVE processes'
Use the left mouse button to make selections, and the right mouse
button to open menus (indicated by triangular glyphs at the right end
of some buttons). See the Guide or the on-line manual for notes on annotation
- -a annotator
- Open the specified annotation file for
the previously specified record or records.
- -dpi xx[xyy]
- Calibrate wave
for use with a display having a resolution of xx (by yy) dots per inch.
- -f time
- Open the record(s) beginning at the specified time.
- Use shades
of grey only, even on a color monitor.
- Read the signal files in high-resolution
mode (default: standard mode). These modes are identical for ordinary records.
For multifrequency records, the standard decimation of oversampled signals
to the frame rate is suppressed in high-resolution mode (rather, all other
signals are resampled at the highest sampling frequency).
- Use monochrome
(usually black and white) only, even on a color or greyscale monitor.
The line styles selected by the -m option may be easier to distinguish
on some greyscale monitors than the default shades of grey.
- Use overlay
graphics for maximum speed and display quality if possible. This is the
usual default if the X server supports a PseudoColor or GrayScale visual.
This option exists only to force use of overlay graphics if a different
mode has been chosen as the default.
- -s signal [signal ...]
- Initialize the
signal list. By default, the signal list includes all available signals,
in numerical order.
- Use the standard (shared) color palette, even if
it is possible to modify the palette. Using this option conserves color
resources if you have other applications that use non-standard colors,
at the expense of some speed in redrawing the display. The -S option may
be used in combination with the -g option if desired.
- Set display option
x. See `Display Options' below for details.
Note that wave queries the X
server to determine the display capabilities and resolution; it is not
necessary to use the -g, -m, or -S options unless you wish to restrict wave's
use of the available capabilities. Use the -dpi option to override the
server's default resolution if it is incorrect and cannot be changed otherwise
(see comments below under `Resources').
The system on which wave runs (the
``host'' system) need not be the same as the system to which your keyboard,
mouse and display are connected (the ``local'' system), provided only that
the host and local systems are on the same network. If you wish to run
wave remotely, it is usually necessary to grant permission for the host
system to open windows on the local system's display (generally, this is
accomplished using xhost on the local system; see the documentation for
your X server for details). Use rlogin, telnet, or a similar method to
log into the host system from the local system, and set the DISPLAY environment
variable on the host system appropriately (if the local system runs UNIX,
the value of DISPLAY should be local-hostname:0.0 in most cases; again,
consult your X server documentation).
wave uses many environment
variables; they are listed in this section roughly in order of importance.
Many of them need not be set at all, since wave uses reasonable default
values in most cases. Those that are set must be set on the host system.
- The name of the X server and display you are using (see above).
If not set, wave will not be able to open windows on your display unless
your display is attached to the host system directly (not via network
- The database path (see setdb(1)
). If not set, wave can
find database files only in the current directory. If you edit annotation
files and wish to reopen them later, be sure that the current directory
(in which wave writes any edited annotation files) is the first directory
in your database path.
- The DB calibration file (see setdb(1)
). If not set, wave may not scale signals other than ECGs correctly.
- The name of the analysis menu file (see below); if not set,
wave uses wavemenu if it exists in the current directory, or $MENUDIR/wavemenu.def
- The command interpreter used within the Analysis Commands
window; if not set, wave uses /bin/sh (the Bourne shell). Other shell-related
variables, such as PATH, are also significant when wave is running commands
within the Analysis Commands window.
- The name of the text editor
to be used for modifying the analysis menu file and the log file. If not
set, wave uses textedit.
- The name of a PostScript printer to be
used for paper output; if not set, wave uses the default printer.
- The command used to print PostScript data from the standard input; if
not set, wave uses `lpr -P$PRINTER'.
- The command used to print text
from the standard input; if not set, wave uses `lpr -P$PRINTER'.
name of a file that contains custom annotation definitions (see `Resources',
below, for details). If not set, wave uses standard annotation definitions
The environment variables below are not needed unless the wave binary
distribution, or XView, has been installed in non-standard directories:
- The path for XView spot help; if not set, wave initializes it
to /usr/lib/help. wave's own spot help is in $HELPDIR/wave, which is appended
to the end of HELPPATH by wave.
- The directory in which wave's help
directory is located; if not set, wave uses /usr/local/help.
name of the directory that contains the default analysis menu file; if
not set, wave uses /usr/local/lib.
- The name of the directory in
which system-wide default X11 resource files are kept; if not set, wave
uses /usr/lib/X11/app-defaults. XUSERFILESEARCHPATH, XAPPLRESDIR, and XENVIRONMENT
are also used, together with HOME and USER, to locate resource files (see
You can control many aspects of wave's appearance and behavior
by setting its resources. If you are not familiar with this concept, refer
to an introductory book on using the X Window System, such as Quercia
and O'Reilly's `X Window System User's Guide'. Since wave is built using the
XView toolkit, all of the resources listed in xview(7)
can be used with
wave. In addition, the following wave-specific resources may also be set:
- This resource specifies if wave is allowed to render
dotted lines. wave normally draws annotation marker bars as dotted lines,
and may use dotted lines for other display elements on black-and-white displays
for clarity. Some X servers do not properly render dotted lines, however;
if you observe irregular or missing annotation marker bars, change the
value of this resource from True to False.
- This resource specifies
the name of a file that contains a table of annotation definitions. The
environment variable ANNTAB can also be used to specify this filename;
the resource overrides the environment variable if both are set. The
file contains one-line entries of the form
15 % Funny looking beat
in which the first field specifies the (numeric) annotation code in the
range between 1 and ACMAX inclusive (see /usr/include/ecg/ecgcodes.h for
a list of predefined codes and for the definition of ACMAX); the second
field (`%' in the example) is a mnemonic (used in annotation display and
entry), and the remainder of the entry is a description of the intended
use of the annotation code (which appears next to the mnemonic in the
`Type' field and menu of `Annotation Template' windows). Lines in the annotation
table that begin with `#' are treated as comments and ignored. It is not
necessary to specify an annotation table when editing an existing annotation
file unless previously undefined annotation types are to be added to it
during the editing process, although it is generally harmless to do so.
- This resource specifies the display resolution in dots per inch
in the form MMxNN, where MM is the horizontal resolution and NN is the
vertical resolution. Normally, the resolution is known to the X server,
and it is unnecessary to specify this resource. If your X server is misinformed,
wave's calibrated display scales will be incorrect; the best solution
is to specify the resolution using a server option such as the -dpi option
supported by MIT's X11 servers, since this will solve problems common to
any other applications that require calibrated scales as well. Not all
X11 servers support such an option, so this resource is available as a
work-around. The command-line option -dpi overrides the resource if both
are specified. (If you don't know the resolution, use xdpyinfo(1)
what your X server thinks it is. Then run wave, enable the grid display,
and measure the grid squares with a ruler. If they are larger than 5 mm,
the number of dots per inch returned by xdpyinfo is too large; adjust
the Wave.Dpi resource proportionally, and repeat the process until the
grid squares measure 5 mm in each direction.)
- This resource
specifies the graphics mode used by wave; it can be overridden using
the -g, -m, -O, or -S options. The legal values are 1 (monochrome mode), 2
(overlay greyscale mode), 4 (shared color mode), 6 (shared grey mode),
and 8 (overlay color mode).
- These resources
specify the colors to be used on greyscale or color displays. The `Color.*'
resources are used only if the display is color-capable and neither greyscale
nor monochrome mode has been specified. The defaults are:
- In monochrome mode, the background is normally white, and all other display
elements are normally black. The reverse can be obtained by setting this
resource to black. (There is at least one server for which this fails.)
- These resources specify the
colors to be used in the Scope window on greyscale or color displays. The
Foreground color is used for the waveform and the time display; by default,
it matches the color used for signals in the signal window (see the previous
item). Some X servers do not allow the background color of the Scope window
to be set, because of the color map animation and stippled erasing techniques
- This resource can be used to invert the
foreground and background of the Scope window when WAVE is running in
monochrome mode. This does not work for all X servers.
- These resources specify the preferred dimensions (in millimeters) for
the signal window. The defaults are 120 and 250 respectively.
- This resource specifies the font used to display annotations and time
marks in the signal window. The default is fixed.
- This resource
specifies the name of the text editor invoked by wave to permit you to
edit wave's log and analysis menu files. The default is textedit (the OpenLook
visual editor). You may override this resource by using the environment
variable EDITOR, which is also used by many other UNIX applications that
Initial values for the settings controlled
from wave's View window can be specified using either X resources or command-line
options. Once suitable settings have been selected, use the `Save as new
defaults' button in wave's View window to record them in your .Xdefaults
file. In this section, the X resource name is specified first, and the
command-line option follows.
By default, all of the display options in the
first group are off (False); set any of these X resources to True to enable
these options, or use the command-line options to do so.
- Display annotation subtyp fields.
- Wave.View.Chan (-Vc)
- Display annotation
- Wave.View.Num (-Vn)
- Display annotation num fields.
- Display annotation aux fields.
- Wave.View.Markers (-Vm)
- Display annotation
- Wave.View.SignalNames (-VN)
- Display signal names along the left
edge of the signal window.
- Wave.View.Baselines (-Vb)
- Display baselines for
any DC-coupled signals, and label the zero levels and the units along the
right edge of the signal window.
- Wave.View.Level (-Vl)
- While the pointer is
in the signal window and any mouse button is depressed, track the intersections
of the marker bar with the signals and draw horizontal marker bars across
the signal window at the levels of these intersections.
The remaining resources
and command-line display options correspond to the menu buttons in wave's
View window. The value of each resource, or the numeric argument that
immediately follows the command-line option, should match the position
of the desired menu choice, where the top item on each menu is in position
0, the one below it is in position 1, etc. For example, to set the initial
amplitude scale to 5 mm/mV (the item at position 2 in the `Amplitude scale'
menu), add -Vv 2 to the command line, or Wave.View.AmplitudeScale:2 to the
X11 resource database.
- Wave.View.TimeScale (-Vt)
- Set the time scale (0: 50
mm/min; 1: 125 mm/min; 2: 250 mm/min; 3: 500 mm/min; 4: 12.5 mm/sec; 5:
25 mm/sec (default); 6: 50 mm/sec; 7: 125 mm/sec; 8: 250 mm/sec).
- Set the amplitude scale (0: 1 mm/mV; 1: 2.5 mm/mV; 2: 5 mm/mV; 3:
10 mm/mV (default); 4: 20 mm/mV; 5: 40 mm/mV; 6: 100 mm/mV).
- Set the choice on the `Draw' menu (0: all signals (default); 1: listed
- Wave.View.AnnotationMode (-VA)
- Set the choice on the `Show annotations'
menu (0: centered (default); 1: attached to signals; 2: as a signal).
- Set the choice on the `Time display' menu (0: elapsed (default); 1:
absolute; 2: in sample intervals).
- Wave.View.GridMode (-VG)
- Set the choice
on the `Grid' menu (0: none; 1: 0.2 s; 2: 0.5 mV; 3: 0.2s x 0.5 mV (default)).
In addition to the usual ways of setting X resources, it is possible
to set any of those listed above, as well as any of the generic XView
resources, by using the -xrm or -default options on the command line when
starting wave. For example, you can set the background color of the signal
window using a command such as
wave -r 100s -xrm Wave.SignalWindow.Color.Background:lightblue
By specifying two or more record names,
separated by `+' characters, in the command-line argument that follows `-r'
(see above), you may open separate WAVE signal windows (processes) for
each record. These processes are almost completely independent: from any
signal window, you may navigate within the record, change display settings,
edit annotations, run external analysis programs, quit the process, etc.,
without affecting any other signal windows.
For example, you may open two
signal windows for the same record by:
wave -r 100+100 -a atr
You can now
move about the record freely in either window. This facility makes it
easy to compare different segments of the record. Note that whenever two
or more windows are displaying the same set of annotations, as in this
case, only one should be editing the annotations at any given time.
window associated with the last record named on the command line has a
special status: it is designated the master signal window, and an extra
button (labelled `Sync') appears at the top of this window. Clicking on
this button causes all of the other signal windows to be redrawn so that
the times shown in their lower left corners match that in the master signal
window. (Note, however, that if you have quit a signal window from the
middle of the list, any signal windows from earlier in the list will no
longer respond to sync requests.)
By default, all command-line arguments
apply to all signal windows. You may specify an argument that is to apply
to only one signal window, however, by prefixing the argument with `+n/',
where n is the signal window number. (The first signal window, corresponding
to the first record named on the command line, is signal window number
0; the next is number 1, etc.)
This facility has many applications. For
example, you may wish to open two copies of the same record, with two
wave -r 100+100 -a +0/atr +1/qrs
In this case, record
100 is opened in two windows, with annotator `atr' in window 0 and annotator
`qrs' in window 1. (The `-a' option applies to both windows since it does not
have a `+n/' prefix.)
As another example, you may wish to discuss a record
with colleagues at other locations:
wave -r 200+200+200 -a qrs +0/-display
Here, record 200
is opened in three windows. Window 0 is opened on display 0 of atlantic.bigu.edu,
window 1 on display 0 of pacific.widget.com, and window 3 (the master window)
on the local display. (For this to work, your colleagues must first allow
your computer to open windows on their displays, typically using xhost.
for information about the -display option. Notice that the
`+n/' prefix must be attached to both the `-display' option and to its argument
in order to apply both of these arguments to the same signal window.) Your
colleagues can freely move about the record, but you can direct the discussion
at any time by using the Sync button in your signal window. In a case
such as this one, anyone can enable editing; you should do so only after
making sure that no one else has. Once you have saved your work (by selecting
`Save' from the File menu), your changes become visible to your colleagues
if they reload the annotations (by clicking on `Reload' from the Load window).
As a final example, the MIMIC Database includes both high-resolution waveform
records and medium-resolution (roughly 1 sample per second) computed measurement
records. You may view both of these at the same time using a command such
wave -r 237+237n -a all
Typically, you will wish to view the high-resolution
and low-resolution data at different time scales. Although wave attempts
to choose reasonable defaults, you can adjust the scales independently
if you wish:
wave -r 237+237n -a all +1/-Vt +1/2
If you use wavescript or
wave-remote to control the master signal window (this happens by default
unless you use the -pid option of these programs to control a different
signal window), the other signal windows are kept synchronized with the
Note that you cannot increase the number of signal windows
in a group once you have started a wave process group, although you can
run more than one process group at a time if you wish.
a simple menu file to allow you to set up analysis options. Each line
in the file corresponds to a button in the Analyze window (except for
empty lines and lines that begin with `#', which are ignored). Within each
line, the syntax is label<tab>action, where <tab> is one or more tab characters.
The label field is used to identify a command button in the Analyze window,
and the action field is any command acceptable to your shell. button-label
and action may include spaces if needed; if necessary, a `\' may be used
at the end of a line to indicate that it is continued on the next line.
Before the command is executed, wave replaces certain tokens with appropriate
strings; these include:
- The name of the current record.
- The name of the current input annotator.
- The currently selected
`start analysis' time.
- The currently selected `end analysis' time.
- The time interval between $END and $START.
- The time corresponding
to the left edge of the signal window.
- The time corresponding to
the right edge of the signal window.
- The time interval between $RIGHT
- The currently selected signal number (as shown in the
- The current signal list (as shown in the Analyze
- The name of the current log file (as shown in the Log window).
- The DB path (from the Load window).
- The name of the DB calibration
file (from the Load window).
- The time scale, in mm/sec.
- The amplitude scale, in mm/mV.
- The annotation display mode (0:
annotations displayed in center, no marker bars; 1: annotations displayed
in center, long marker bars; 2: annotations attached to signals, no bars;
3: annotations attached to signals, short bars; 4: annotations displayed
as a signal, no bars; 5: annotations displayed as a signal, long bars)
- The command for printing PostScript data from the standard input,
as specified in the Print Setup window.
- The command for printing
text from the standard input, as specified in the Print Setup window.
- The URL specified by the most recently selected link.
Other tokens that
begin with `$' are passed to the shell unchanged.
The default menu
file includes the following lines (among others):
| Mark QRS complexes||sqrs
-r $RECORD -f $START -t $END -s $SIGNAL|
| Calibrate||calibrate -r $RECORD -f $START
-t $END -s $SIGNALS|
| Extract segment||snip -i $RECORD -f $START -t $END -n n_$RECORD
| -a $ANNOTATOR|
| List annotations||rdann -r $RECORD -a $ANNOTATOR -f $START -t
| List samples||rdsamp -r $RECORD -f $START -t $END -s $SIGNALS|
| Print chart||echo
$RECORD $START-$END | \ |
| pschart -a $ANNOTATOR -g -l -R -s $SIGNALS - | $PSPRINT|
Print full disclosure||echo $RECORD $START-$END | \ |
| psfd -a $ANNOTATOR -g -l
-R -s $SIGNALS - | $PSPRINT|
Whenever the pointer is in the
signal window, the normal arrow pointer is replaced by a crosshair pointer.
At these times, the numeric keypad and several of the function keys may
be used for many annotation editing and display operations, and the normal
alphanumeric and punctuation keys can be used to select single-character
annotation mnemonics (displayed in the Annotation Template window). `Num
Lock' must be off if you wish to use the keypad for editing operations.
Some of the function and numeric keypad commands work on Sun keyboards
only; in these cases, alternate keyboard commands for use with PC and
other keyboards are shown in parentheses. Most of these alternate commands
also work on Sun keyboards.
- <Help> (<F1>)
- Open XView spot help for the item
under the pointer. (Unlike most of the other keyboard commands, this command
is available at any time, not only when the pointer is in the signal window.)
- <left arrow>
- Select the annotation to the left of the pointer. (Click left
to do this using the mouse. These actions also work when the pointer is
in the scope window.)
- <right arrow>
- Select the annotation to the right of
the pointer. (Click right to do this using the mouse. These actions also
work when the pointer is in the scope window.)
- <up arrow> Move the selected
annotation up one signal (i.e.,
- decrement its chan field). This command
works in multi-edit mode only (enter multi-edit mode by choosing `attached
to signals' from the `Show annotations' menu in wave's View window).
- <down arrow>
- Move the selected annotation down one signal (i.e., increment its chan field).
This command works in multi-edit mode only.
- keypad <5> (<F2>)
- Insert an annotation
at the current position of the pointer. (Click the middle button to do
this using the mouse. Annotation editing must be enabled for this action
to be successful.)
- keypad <=> (<F3>)
- Move the pointer toward the left.
- Move the pointer toward the right.
- <Copy> (<F6>)
- Copy the selected annotation
to the Annotation Template.
- <Find> (<F9>)
- Search forward.
- <ctrl><Find> (<ctrl><F9>)
- Search backward.
- <End> (<shift><F9>)
- Advance to the end of the record.
- <Home> (<ctrl><shift><F9>)
- Move to the beginning of the record.
- <PgDn> (<F10>)
- Advance half a screen.
- Advance a full screen.
- <PgUp> (<shift><F10>)
- Move back half a screen.
- <ctrl><PgUp> (<ctrl><shift><F10>)
- Move back a full screen.
- <Enter> (<Return>)
- (Only if
a link annotation has been selected.) Show the external data specified
by the link using a Web browser; start the Web browser first if necessary.
Under SunOS, once you have opened the Analyze window or have selected
Print from the File menu, do not attempt to suspend wave (for example,
by typing control-Z in the controlling terminal window). Under these circumstances,
wave may exit immediately (without quit confirmation) and any unsaved
edits may be lost. This problem is the result of a bug in the XView termsw
package used for the Analysis Commands window. To avoid this bug, always
run wave in the background under SunOS. The Solaris 2.x and Linux versions
of the XView library do not have this bug.
On some 24-bit displays, an X
server bug causes wave to start with an empty signal window. Using any
of the navigation controls, or resizing the window, should make the signals
visible. On some of these displays, text in the signal window may be invisible
using overlay graphics mode; if this happens, use the -S option.
than one piped record (see the ECG Database Programmer's Guide) can be
viewed in a single invocation of wave. If the signal file is a pipe, it
is possible only to search forward through it (although wave caches several
of the most recently displayed windows, which can be reviewed in any case).
Using the `>' button to move by half a frame does not work properly with
piped input, nor does changing the display scales, since these actions
require rereading the signals.
(in Sun's DeskSet Environment Reference Guide,
or on-line; on some systems, this man page is known as xview(1)
Versions of wave for use on Sun SPARCstations and clones
(under SunOS or Solaris), and on Intel 386-compatible PCs (under Linux)
are included on the third edition of the MIT-BIH Arrhythmia Database CD-ROM,
and on the Software for Physiologic Databases with Samples CD-ROM. Demonstration
versions of wave (fully functional except that saving the results of annotation
editing operations is not possible) may be obtained from http://ecg.mit.edu
(or by anonymous FTP from ecg.mit.edu) and on the Samples of Physiologic
wave is not part of the DB Software Package, but is intended
to work with this package on systems that support X11 and XView. If you
would like to use wave on a system other than those listed above, you
will need to port XView to your system first (or purchase a commercial
port if one is available). Sources for XView are supplied on our CD-ROMs
that include wave, and are also available from sunsite.unc.edu, tsx-11.mit.edu,
and their mirrors. We cannot offer assistance in porting XView; if you
wish to try this, you are on your own. If you successfully port the cmdtool
terminal emulator application included in the XView sources, we will assist
you in porting wave (this is much simpler than the XView port).
edition of the MIT-BIH Arrhythmia Database CD-ROM contained an earlier version
of wave (for Sparc SunOS only) that lacked many of the features described
here. Refer to the documentation included on that CD-ROM for details.
Table of Contents