WAVE: Waveform Analyzer, Viewer, and Editor

Copyright (C) 1990-2000 George B. Moody

WAVE is an extensible interactive graphical environment for manipulating sets
of digitized signals with optional annotations.  WAVE is built using the WFDB
library developed for physiologic signal processing, so it can be applied to
any of a wide variety of data formats supported by the WFDB library.  WAVE can
run on Linux PCs, Sun workstations, and other systems that support the X
Window System and the public-domain XView toolkit; in addition, it can be
accessed remotely using networked PCs, Macintoshes, or other systems for which
X11 servers are available.

Among WAVE's capabilities are:
 - fast display of waveforms and annotations at various calibrated scales
 - fast access to any portion of a recording, with caching and `read-ahead'
   heuristics to improve efficiency and reduce network traffic
 - forward and backward searches for annotation patterns
 - graphical annotation editing using standard or user-defined annotations
 - variable-speed superimposition display (simulation of triggered oscilloscope
   display with persistence;  can be run forward or backward)
 - high-resolution printing of user-selected signal segments
 - extremely flexible control of external signal-processing and analysis
   programs (menus may be reconfigured by the user while WAVE is running)
 - on-line `spot' help for all controls, with additional topic-oriented on-line
   help

Move the mouse pointer over any control and press the HELP key (or F1 if there
is no HELP key) for information about that control.  (If your window manager
does not cooperate, this may not work;  in that case, select `Buttons' from the
`Help Topics' panel for information about controls.)

This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with
this program; if not, write to the Free Software Foundation, Inc., 59 Temple
Place - Suite 330, Boston, MA 02111-1307, USA.

Your comments and suggestions are welcome!  Please send them by e-mail to
george@mit.edu, or by postal mail to:
    George B. Moody
    MIT Room E25-505A
    Cambridge, MA 02139 USA
For updates to this software, please visit http://www.physionet.org/.

Contents
========
 . Before You Begin
 . Starting WAVE
   . Options
   . Examples
 . Using WAVE
   . WAVE controls
   . Annotation and Marker Editing
   . Analyzing Data with WAVE
   . WAVE Logs
   . Printing
 . Setting WAVE Resources
 . Frequently Asked Questions

Before You Begin
================

WAVE is a very powerful and flexible tool with a user interface that is easy
to learn once you are familiar with the style of interaction common to other X
applications.  To a significant extent, the "look and feel" of WAVE is
determined by your choice of window manager and preferences.  If you have not
used the X Window System before, you should study the documentation that
describes your system's X server and window manager.  You should also find out
how to simulate the possible actions of a three-button mouse if you do not
have one (servers often provide keyboard/mouse combinations for this purpose).
The remainder of this guide assumes that you know:
 - how to log onto a system on which WAVE has already been installed;
 - how to start an X application; and
 - how to use the mouse.

If you are planning to run WAVE remotely (i.e., if the display and keyboard
in front of you do not belong to the system on which WAVE runs, but instead
belong to another system on the same network), you may need to perform a
few preparatory steps.  See `How can I use WAVE from an X terminal/PC/Mac/etc?' (below)
for details.

Before running WAVE for the first time with a given X server, you may wish to
calibrate your display so that WAVE can draw signals at the proper scales.
See `How can I get correct display scales?' (below) for details.

In common with other WFDB applications, WAVE locates signal, annotation, and
header files by searching for them in a user-definable sequence of locations
(the WFDB path).  Be sure to set the WFDB path appropriately for your system
(C-shell users can usually do so by typing `source /usr/local/bin/cshsetwfdb';
Bourne shell, Korn shell, and `bash' users should type `. setwfdb' instead.)
See the WFDB Programmer's Guide or the WFDB Applications Guide, or type
`man setwfdb' for details.

Starting WAVE
=============

From within a terminal window for the system on which WAVE resides, type:
	wave -r RECORD OPTIONS
where RECORD is the WFDB record name and OPTIONS can include any of the
optional arguments listed below, or none of them.  Separate arguments
with spaces, and execute the command by pressing RETURN (or ENTER, etc.).

Options:
--------
 -a ANNOTATOR		Open the specified annotation file for the previously
			specified RECORD.
 -dpi XX[xYY]		Calibrate WAVE for a display with a resolution of
			XX (by YY) dots per inch.
 -f TIME		Open the previously specified RECORD at TIME.
 -g			Use shades of grey only (even on a color monitor).
 -m			Use black and white only (even on color or grayscale
			monitors).
 -O			Use overlay graphics (for the fastest and best-quality
			graphics on displays that support this mode)
 -s SIGNAL [SIGNAL ...] Initialize the signal list to the specified SIGNAL(s).
 -S			Use the standard (shared) color palette (even if it
			is possible to modify the palette).
 -D LOGFILE		Start WAVE in `demo' mode (see below).
 -V...			Specify initial values for the settings controlled
			from the `View' panel (see `Resources' for details).
Examples:
---------
 wave -r 200 -a atruth		Open record 200, and show annotations from
				the reference annotation file (atruth.200)

 wave -r 100 -g -dpi 65x70	Open record 100, and use shades of grey only
				on a display that has a resolution of 65 dpi
				horizontally by 70 dpi vertically

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.  The -O option exists only
to force use of overlay mode if another mode has been set as the default (see
`Setting WAVE Resources' below);  usually, overlay mode is the default.  Use
-dpi only if the X server does not have, and cannot be supplied, the correct
information about the display resolution.

In `demo' mode, WAVE displays the strips specified in LOGFILE, pausing for 5
seconds after each display.  All of WAVE's controls operate in normal fashion
while `demo' mode is active.  To exit `demo' mode without exiting from WAVE,
call up the `Log...' window from the `File' menu and press the `Pause' button.
You can return to `demo' mode by pressing the `Review log' button.  (See `WAVE
Logs', below, for information on creating a LOGFILE.)

See `Frequently asked questions', below, if you have difficulty getting
started.

Using WAVE
==========

After typing a command to start WAVE, as described above, the main window
of WAVE should appear on your display.  (Some window managers may require
you to specify the placement or sizing of a new window before it appears.
In this case, you may see an outline of the window, or the cursor shape may
change, and you must use the mouse to open the window.  This behaviour is
beyond the control of WAVE.)

Move the mouse so that the pointer lies within the WAVE main window.  (Again,
depending on your window manager, you may have to set the input focus
explicitly before proceeding.  Typically, you may have to click the left
mouse button with the pointer within the window in order to do so.)  Once
the WAVE main window has the input focus, the buttons in the main control
panel (at the top of the window) can be used to control WAVE.

Some of WAVE's panels contain regions marked by underlines for entry of text.
By positioning the pointer near any of the underlined entries and clicking the
left mouse button, you can set a text cursor that appears above the underline.
You may delete characters to the left of the text cursor using the DELETE key,
or you may type into the entry.  If you press RETURN, your changes take effect
immediately;  you may change two or more entries without pressing RETURN, and
the effects of the changes will be deferred until you press RETURN or select
one of the buttons on the panel.  To select a panel button, position the
pointer on the button and click the left mouse button.  If the button label
includes a menu indicator (a downward- or rightward-pointing triangle), you
may pop up the menu by pressing the right mouse button;  drag the pointer to
the desired choice on the menu and release the right mouse button, or move the
pointer off of the menu before releasing the right mouse button if you do not
wish to choose any of the menu items.

WAVE Controls
-------------

The buttons of the main control panel are:

 File		Press the right mouse button to bring up the File menu, which
		includes:
	Load...		Select this item to bring up the Load window;  change
			the `Record' or `Annotator' fields in the Load window
			in order to load a different record or annotation file.
			The initial values of these fields are obtained from
			the -r and -a options on the command line.  If the
			`Annotator' field is empty, no annotations are loaded.
	Save		Select this item to force your edits to be written to
			disk files.  (This is done automatically after every
			20 edits, any time the record or annotator is changed,
			and upon exiting WAVE.)
	Print		Select this item to print the contents of the ECG
			window in chart recorder format (after saving any
			edits).  This is accomplished by spawning a `pschart'
			process, so you need not wait for the output before
			continuing.  Output from multiple print requests
			appears in the order in which the requests were made.
 	Analyze...	Select this item to bring up the Analyze panel and the
			Analysis commands window; use the buttons in the panel
			to analyze the record, or type a command directly into
			the Analysis commands window.  The names of most of the
			buttons and their assigned actions are read from a menu
			file (by default, /usr/local/lib/wavemenu.def; 	this
			may be overridden by setting the environment variable
			WAVEMENU to the name of a different file).  The buttons
			are usually configured to perform various analysis
			functions on the current record; read the default menu
			file for details.
	Log...		Select this item to bring up the Log window.  Change
			the `Log file name' field to load a log file;  enter
			text to be recorded in the log file in the
			`Description' field.  Record an entry by pressing the
			`Save' button, or dismiss the window without logging
			the entry by pressing `Cancel'.  Review the entries
			by pressing `Review log';  each entry will be displayed
			for 5 seconds unless you press `Pause' (disabled except
			while reviewing the log).  Each entry contains the
			record name, the times shown at the lower left and
			right corners of the ECG window, and the contents of
			the `Description' field.  Log files may be used as
			command scripts for `pschart'.  You may write to as
			many log files in a single session as you choose, and
			you may accumulate entries from multiple sessions in a
			single log file.

 View...	Press the left mouse button to bring up the View window, which
		includes:
	Show:		Select one or more of these items in order to enable
			or disable optional elements of the ECG display.
	Time scale:	Press the right mouse button to view the list of
			available time scales;  drag the pointer to the
			desired scale and release the right mouse button.
	Amplitude scale:
			Press the right mouse button to view the list of
			available amplitude scales;  drag the pointer to the
			desired scale and release the right mouse button.
	Draw:		Press the right mouse button to select either `all
			signals' or `listed signals only'.  If you choose
			`listed signals only', signals are displayed in the
			order specified in the signal list on the `Analyze'
			panel, and any signals not included in the list are
			not displayed.
	Grid:		Press the right mouse button to view the list of
			available grid types;  drag the pointer to the
			desired type and release the right mouse button.
	Undo changes	Select this item to restore the View window indicators
			to match the current state of the ECG window.
	Redraw		Select this item to apply any changes you have made
			and to dismiss the View window.

 Edit		Press the right mouse button to bring up the Edit menu, which
		includes:
	Allow editing	Select this item if you wish to make changes in the
			annotation file.
	View only	Select this item if you do not wish to edit the
			annotation file any longer.  By default, editing is
			disabled when WAVE is started up.

 Properties	Press the right mouse button to bring up the Properties menu,
		which includes:
	Signals...	Select this item to view information about the ECG
			signals in the current record.
	Annotations...	Select this item to view a summary of the contents of
			the current annotation file.
	About WAVE...	Select this item to view information about the version
			number and installation date of this version of WAVE.

 < Search	Search backwards, beginning with the annotation that
		immediately precedes the earliest annotation currently
		displayed, for an annotation that matches the entry in the
		"Search for" field of the Find window (see below).  The display
		is redrawn, roughly centered on the matching annotation.

 <<		Skip backwards by an amount equal to the duration of the
		signals currently displayed (i.e., a full screen).

 <		Skip backwards by one-half screen.

 Find...	Press the left mouse button to bring up the Find window, which
		includes:
	Start time:	The value of this item is the time shown in the lower
			left corner of the ECG window.  Change it in order to
			view another part of the record.  (Time can be entered
			in h:m:s format, with hours or hours and minutes
			omitted, or in sNNNNN format, in which NNNNN is a
			number of sample intervals from the beginning of the
			record.  Time is always rounded down to an even
			multiple of one second, and is displayed in m:s or
			h:m:s format irrespective of the input format once the
			display is refreshed.)
	End time:	Similarly, this item's value is the time shown in the
			lower right corner of the ECG window.  Change it in
			order to view another part of the record.  If you
			change both the Start time and the End time fields
			without pressing RETURN in between, only the last
			change is effective.  To change the duration of the
			ECG window, select the View window (see above) and
			change the time scale.
	Search for:	This entry is initially empty.  Enter a string to
			specify a search target for the "< Search" and
			"Search >" buttons.  The string should match an
			annotation or marker mnemonic, signal quality code,
			rhythm, comment, or other text string, or one of:
			  *v	to match any ventricular ectopic beat
			  *s	to match any supraventricular ectopic beat
			  *n	to match any other beat type
			  *	to match any annotation or marker
			  .	to match a deletion made during this edit

 >		Skip forwards by one-half screen.

 >>		Skip forwards by a full screen.

 Search >	Search forwards, beginning with the annotation that
		immediately follows the last annotation currently displayed,
		for an annotation that matches the entry in the "Search for"
		field of the Find window (see above).  The display is redrawn,
		roughly centered on the matching annotation.

 Help		This button pops up a panel containing buttons that name
		several topics for which extensive on-line help is available.
		Choosing a topic allows you to browse through the associated
		help file in a scrollable text window.

 Quit		WAVE exits when you press this button, after saving your edits
		if any.  If your input file would be overwritten as a result of
		saving your edits, it is first renamed by appending a `~' to
		the annotator name.  If you have entered annotations but have
		not specified an annotator, the name by which you invoked this
		program (normally, `wave') is used for the annotator name.

Annotation and Marker Editing
-----------------------------

Annotations may be edited if you have enabled editing from the Edit menu. If
you have specified an existing annotator on the command line or in the Load
window (accessible from the File menu), you can modify the annotations assigned
to that annotator.  You may also specify a new annotator name and create the
annotation set from scratch.  If you do not specify an annotator name, WAVE
creates an output annotation file for you if you insert any annotations;  the
annotator name in this case is the name by which you invoked WAVE (normally
`wave').

If you have chosen to have annotations displayed by WAVE attached to signals
(using the `Show annotations' menu button on WAVE's View panel), be sure to
read the comments on `Multi-edit mode' at the end of this help topic, since
editing operations in that mode are slightly different.

Move the mouse so that the pointer enters the signal window (the portion of the
main window in which the signals are drawn), and click the left mouse button.
(While within the signal window, the shape of the pointer changes to a pair of
crosshairs, which intersect at the "hot spot".)  The Annotation Template window
appears; it shows the attributes given to any annotations that are inserted.
The `Type' item shows the annotation mnemonic; if this field is `.', existing
annotations will be deleted rather than changed.  You may change the type
either by pulling down the type menu using the right mouse button, or by typing
the mnemonic while the pointer is in the signal window.  Other fields may be
set as desired.  You may remove the Annotation Template window from the screen
by pressing the "Dismiss" button, but you may prefer to leave it on-screen as
a reminder of its current contents.

To INSERT an annotation, type its mnemonic while the pointer is in the signal
display area (or select the desired type and other attributes in the Annotation
Template window).  Move the pointer's hot spot to the spot where you wish to
insert the annotation, and click the middle mouse button.  If you wish, you may
"drag" the fiducial line (which appears when you press the middle button) to
the exact location desired, then release the button to insert the annotation.

To SELECT an existing annotation (in preparation for moving, changing, or
deleting it), click the left or right mouse buttons to move the pointer one
annotation at a time left or right.  The annotation under the pointer is
"selected" by this operation and may be moved, changed, or deleted while it is
marked with a rectangle.  WAVE recenters the display on the selected annotation
if the pointer would otherwise move past the left or right edge of the signal
window.

To COPY an existing annotation, select it, then press <Copy> (or <F6> if your
keyboard does not have a <Copy> key).  This action copies the selected
annotation into the Annotation Template.  Now insert the copy at the desired
location.

To MOVE an existing annotation, select it using the left or right mouse button,
drag its marker bars to the desired location, then release the button.
Until the button is released, the rectangle stays in its original position;
if you decide not to move the annotation, simply move the pointer back into
the rectangle before releasing the button.  To move an annotation by an amount
less than the width of the rectangle, simply drag the pointer above or below
the rectangle to the desired position.

To CHANGE an existing annotation, set the desired attributes in the Annotation
Template window as described above.  Select the annotation to be changed using
the left or right mouse buttons.  While the pointer is within the rectangle,
click the middle mouse button.  The previous annotation at the same time is
overwritten by the new one.  Thus this operation is just like inserting a new
annotation, except that you select an existing annotation first.

To DELETE an annotation, type "." while the pointer is in the signal window, or
select the ". (deleted annotation)" item from the Type menu within the
Annotation Template window.  Select the annotation to be deleted using the left
or right mouse buttons as above, then click the middle button to delete the
annotation.  The previous annotation is removed, and a "." appears in its place
(thus this operation is exactly like changing an annotation).  The "." marks
remain until the annotation file is closed; until that time, they can be
selected in the same way as ordinary annotations, but they are not written to
the output annotation file.

If you perform the deletion operation on an annotation that is marked as
deleted, the annotation is "undeleted" (i.e., restored to its original state).

To perform the same operation repeatedly it is not necessary to retype the
annotation mnemonic (or ".") each time.  Type the mnemonic only when you wish
to change the type of editing operation.

The operations above, with the exception of moving an annotation, may also be
performed using the keyboard.  The `Num Lock' indicator must be off (press the
`Num Lock' key to turn off the indicator if necessary), and the pointer must
be in the signal window (as indicated by a crosshair pointer replacing the
normal arrow pointer).  In this context, keys <4>, <5>, and <6> (left-arrow,
unmarked, and right-arrow) on the numeric keypad behave in the same way as the
left, middle, and right mouse buttons respectively (except that <shift> cannot
be used with the keypad as with the mouse buttons; <control> and <meta> do
work, however).  You can move the pointer left or right using the <=> and <*>
keys on the keypad (useful for inserting annotations);  the pointer accelerates
while these keys are depressed.

To change or delete all annotations in a specified interval:
 1. mark the beginning of the interval with the `<' (begin analysis) marker
 2. mark the end of the interval with the `>' (end analysis marker)
 3. set the Type, Text, Subtype, Chan, and Num fields of the Annotation
    Template as desired
 4. press the `Change all in range' button in the Annotation Template window
Since this operation can have far-reaching consequences, WAVE asks for
confirmation before performing it if either of the `<' or `>' markers is not
on-screen.

During editing, the current state of the annotation buffer is saved frequently
to avoid the possibility of data loss.  The output annotation file is given
the name of the input annotation file.  Since input annotation files are not
necessarily found in the current directory, it may not be necessary to create
a backup file for the input in order to avoid overwriting it.  If, however,
the input file is found in the directory in which the output file is to be
written, it is renamed by appending a tilde (`~') to the annotator name.  Only
one level of backup is preserved, so you will overwrite the original
annotation file if it is in the current directory and you open the same
annotator more than once.

Markers (displayed as `<', `:', and `>') may be edited just as for annotations,
but they are not saved in output annotation files.  It is not necessary to
enable editing from the Edit menu in order to be able to edit markers.  Note
that there can be at most one `<' (beginning of analysis) and one `>' (end of
analysis) marker in the annotation buffer at any time;  inserting one of these
markers has the effect of deleting any other marker of the same type.  You may
have as many `:' (index) markers as you wish.  It is also possible to insert
`<' and `>' markers by entering the time directly into the `Start' and `End'
fields in the Analyze window (obtained from the File menu).  Markers are not
affected by use of the `Change all in range' button.

For information on defining new annotation types, see the help topic called
`Resources'.


Multi-edit mode
---------------

Using the `Show annotations' menu button on WAVE's View panel, you may choose
to have annotations displayed attached to signals.  In this case, the `chan'
field of each annotation specifies the signal number of the signal to which it
is attached.  If annotation editing is enabled when annotations are displayed
in this way, WAVE is in `multi-edit mode'.

WAVE draws the signals in order of signal number from the top to the bottom of
the signal window, beginning with signal number 0 at the top of the signal
window.  When annotations are attached to signals, WAVE draws them about 2 mm
above the center of the range of the attached signal (except for special
annotations that are displaced above or below the usual level).  Although this
presentation usually helps to avoid the visual confusion that might result from
drawing annotations directly on the associated signals, it may contribute to
confusion if the spacing between signals is too small (as may happen if the
signal window is reduced in height, or if many signals are displayed).  If this
becomes a problem, try increasing the height of the signal window (by dragging
on the resize handles on the window frame), or displaying only a subset of the
signals (by specifying which signals are to be shown in the `Signal list' field
of WAVE's Analyze panel, and selecting `Draw: listed signals only' in WAVE's
View panel).

In multi-edit mode, annotation editing operations are slightly different from
those described above.  The most important difference is that you must always
point to the desired signal when inserting or moving annotations.  In this
mode, the `chan' field in the Annotation Template window does not determine the
`chan' field of an inserted annotation; rather, the signal to which you point
determines the `chan' field, and the `chan' field in the Annotation Template
window is updated accordingly after each insertion.  To move an annotation to a
different signal, simply select it and drag the pointer to the desired time and
signal.  If you wish to change the `chan' field of an annotation without
changing its time, select the annotation and use the up-arrow and down-arrow
keys (keys <2> and <8> on the numeric keypad; `Num Lock' must be off) to move
it to the desired signal.  Hold down the <control> key during these operations
to copy the annotation, rather than to move it (simultaneous annotations are
permitted if their `chan' fields differ).

Analyzing Data with WAVE
------------------------

For many users, WAVE's data analysis capabilities will be of greatest
interest.  WAVE itself does not perform analysis of the signals or
annotations it displays.  What WAVE offers is an easy-to-use means of
controlling external analysis programs and viewing their outputs.  The buttons
in the Analyze panel activate these external programs.  These buttons are easy
to create -- in fact, you can add your own buttons to those in the Analyze
panel while WAVE is running.

The controls at the top of the Analyze panel are always the same:
  Start:	The time at which analysis should begin.  When WAVE starts up,
		the contents of this field are `beginning of record'.  To
		change it, either type a time (such as `2:25') into this field,
		or insert a `start of analysis' (`<') marker (see `Editing').
  End:		The time at which analysis should end.  When WAVE starts up,
		the contents of this field are `end of record'.  To change it,
		either type a time into this field, or insert an `end of
		analysis' (`>') marker.
  Signal:	The signal number of the selected signal.  To select a signal,
		either enter its number in this field directly, or point to the
		desired signal in the signal window, depress the <Shift> key,
		and click left.  The selected signal is highlighted if a
		selection has been made since the signal window was redrawn.
  Signal list:	An ordered list of signal numbers specifying which signals are
		to be analyzed, printed, or displayed.  When WAVE starts up,
		the signal list contains all of the available signals for the
		record.  A signal may appear more than once in the signal list.
		To change the signal list, either:
		 1. type directly into the list; or
		 2. point to a signal, then depress the <Control> key and click
		    left (to add it to the list), or depress the <Meta> key
		    and click left (to delete its first occurrence, if any,
		    from the list).
		Note: by default, WAVE displays all available signals, not just
		those on the signal list.  To display the listed signals only,
		change the `Draw' selection in the `View' window.
  Show scope window
		Press this button to open WAVE's `oscilloscope' window.
  Show command window
		Press this button to reopen the Analysis commands window if
		you have closed it.
  Edit menu	Press this button to open an editor window containing WAVE's
		menu file (see below).
  Reread menu	Press this button to force WAVE to reread the menu file (be
		sure to save your changes first) and to reconfigure the Analyze
		panel.  The Analyze panel briefly disappears before returning
		(possibly in a different location on the screen, depending on
		your window manager).

The remaining buttons in the Analyze panel (both their labels and the actions
they perform) are specified by WAVE's menu file.  WAVE's menu file may be named
by the enviroment variable WAVEMENU.  If WAVEMENU is not set, WAVE reads a
file called `wavemenu' if it exists in the current directory, or the system
default menu file (usually `wavemenu.def' in /usr/local/lib) otherwise.

In menu files, comment lines begin with `#'.  The comments at the beginning of
the default menu file describe how it works.  Except for those listed above,
each of the buttons in the Analyze panel corresponds to an entry in the menu
file.  The first part of the entry -- up to the first tab character --
specifies the label that appears on the button; the remainder of the entry
specifies the command that is inserted into the Analysis commands window if you
click left on the button.  Certain strings that begin with `$' are interpreted
by WAVE before being passed to the shell in the Analysis commands window:
	$RECORD		the current record name
	$ANNOTATOR	the current input annotator name
	$START		the current `Start' time as shown in the Analyze panel
			 (the time of the `<' marker, if any)
	$END		the current `End' time as shown in the Analyze panel
			 (the time of the `>' marker, if any)
	$DURATION	the time interval between $END and $START
	$LEFT		the time of the left edge of the signal display window
	$RIGHT		the time of the right edge of the signal display window
	$WIDTH		the time interval between $RIGHT and $LEFT
	$SIGNAL		the number of the selected signal
	$SIGNALS	the signal list
	$LOG		the name of the current log file
	$WFDB		the WFDB path (from the Load panel)
	$WFDBCAL	the name of the WFDB calibration file (from the Load
			  panel)

Other strings that begin with `$' are passed to the shell unchanged.  The
character `\', if immediately followed by a newline, causes the next line to be
treated as a continuation of the current line.

In the default WAVE menu, for example, the `List annotations' and `List
samples' buttons are specified as:
  List annotations	rdann -r $RECORD -a $ANNOTATOR -f $START -t $END
  List samples		rdsamp -r $RECORD -f $START -t $END -s $SIGNALS
(Refer to the `man' pages for `rdann' and `rdsamp', or to the ECG Database
Applications Guide, for details on how these programs interpret their
command-line arguments.)

A common problem in many cases is simply selecting a segment to be analyzed,
from a digitized signal file that may include extraneous material at the
beginning or at the end.  This can be done easily by inspecting the signals
with WAVE and placing `<' and `>' markers at the beginning and end of the
region of interest.  If the analysis program is written to accept starting and
ending times, these times can be passed as command-line arguments by WAVE,
as in the examples above.  Similarly, it's simple to choose one or more of a
larger number of signals to be analyzed after viewing them with WAVE (as in
the `List samples' example).

Editing WAVE's menu file
------------------------

When you click left on `Edit menu' in the Analyze panel, WAVE's menu file
appears in an OpenWindows `textedit' window, unless you have specified a
different editor by setting the EDITOR environment variable.  The command
needed to start the editor appears in the Analysis commands window.  If you
have changed directories within the Analysis commands window, and the name
of WAVE's menu file does not begin with `/', the editor may not open the
correct menu file.  If this happens, exit from the editor, return to the
original directory in the Analysis commands window, and try again.

If WAVEMENU is not set, `wavemenu' doesn't exist, and you click on `Edit menu',
WAVE pops up a notice:
	    You are now using the system default menu file,
	           which you may not edit directly.
          Press `Copy' to copy it into the current directory
	    as `wavemenu' (and remember to set the WAVEMENU
	           environment variable next time),
			        - or -
          Press `Quit' if you prefer not to edit a menu file.
If you select `Copy', you will be able to edit the copy as many times as you
wish in the current session of WAVE.  If you wish to use the edited menu in
future sessions, WAVEMENU should be set to the path name of your customized
menu file (you can give the menu file any name you choose).  For example, if
you use the C-shell, and `wavemenu' is in your home directory, use the command
    setenv WAVEMENU ~/wavemenu
before running WAVE again.  You may wish to add this command to your `.login'
script to set the variable automatically each time you log in.

Be careful when editing the menu file to keep at least one <tab> character
between each button label and its associated command.  If you cut-and-paste
(or drag-and-drop) menu entries from another window, tabs may have been
converted to spaces.

When you have finished editing the menu file, save your work and exit from
the editor before clicking on `Reread menu' in the Analyze panel.

WAVE Logs
---------

WAVE logs are text files, in the format used by `pschart' and `psfd' script
files.  Typically, logs contain notes about interesting sections of one or more
records.  Each entry (line) in a WAVE log contains a record name, a time
reference, and a comment.  Using the `Log ...' window (accessed from the `File'
menu of WAVE's main control panel), you may create or review logs, and add,
modify, or delete entries in them.  Within the WAVE menu, the name of the
current log file can be represented as `$LOG';  this feature may be used to
write WAVE extensions that extract or print segments of interest.

When the log panel is first opened, most of its controls are disabled.  You
must specify a name for the log before you can use any of these controls.
Do so by typing the name into the `File:' field;  press RETURN to tell WAVE
to accept the name.  If the log exists already, WAVE reads its contents and
shows you its first entry.  If the log does not exist, WAVE creates an empty
log with the name you have chosen.  The other controls are enabled as
appropriate (for example, the `Delete' button is not enabled unless there is
an entry to delete).

The `Description:' field contains the description associated with the current
log entry.

The buttons of the log panel are:

 Load		WAVE reads the log file into memory, after saving the current
		contents as a backup file if any changes were made since it
		was most recently loaded.  Use this button to read a log
	        file generated by another process, such as a WAVE analysis
		menu button.

 Add		WAVE adds an entry containing the record name and the contents
		of the description field to the log file.  If an annotation or
		marker within the signal window has been selected (i.e., if it
		is shown marked with a box), WAVE records the time of that
		annotation in the log entry;  when the entry is redisplayed,
		WAVE selects the same annotation again.  Otherwise, WAVE
		records the times in the lower left and right corners of the
		signal window.

 Replace	WAVE replaces the description attached to the current log
		entry with the current contents of the description field.  It
		does not create a new entry (use the `Add' button for that
		purpose).

 Delete		WAVE deletes the current entry from the log, and displays the
		next entry if it exists.

 Edit		This button is currently non-functional.

 |<		WAVE shows the first log entry.

 <<		WAVE reviews each entry in the log file in reverse order,
		pausing 5 seconds between entries.  While a review is in
		progress, only the Pause button is enabled.

 <		WAVE shows the previous log entry.

 Pause		WAVE stops the log review that was begun by the `<<' or `>>'
		button.  This button is disabled unless a review is in
		progress.

 >		WAVE shows the next log entry.

 >>		WAVE reviews each entry in the log file, pausing 5 seconds
		between entries.  While a review is in progress, only the
		Pause button is enabled.

 >|		WAVE shows the last log entry.
Printing
--------

There are three ways to print annotated signals from WAVE:

1. From the File menu, select `Print'.  This produces a `chart recorder' format
   copy of the contents of the Signal window.
2. From the File menu, select `Analyze...' and then `Print chart' from the
   Analyze window.
3. From the File menu, select `Analyze...' and then `Print full disclosure'
   from the Analyze window.

If you choose either of the last two methods, you should first select the
portion of the record you wish to print, either by entering the times directly
in the `Start' and `End' fields of the Analyze window, or by inserting `<' and
`>' markers at the beginning and end of the segment to be printed.

Printing is performed by spawning a `pschart' or `psfd' process (after saving
any edits).  In general, the output has higher resolution than is possible on
screen.

Setting WAVE Resources
======================

You can control many aspects of WAVE's appearance and behaviour 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 the man page for XView can be used with WAVE (type `man
xview' for details).  In addition, the WAVE-specific resources listed below may
also be set.  Those marked with a `*' are recorded in your `.Xdefaults' file
when you use the `Save as new defaults' button in the `View' panel.

If you use WAVE on workstations with different display capabilities, you can
create custom resource settings for each one by moving these resource
definitions from .Xdefaults to .Xdefaults-HOSTNAME (where HOSTNAME specifies
the system to which the display is attached).  The resources marked below with
a `+' are those that are most likely to require different settings on different
displays, but any of the others can also be moved to .Xdefaults-HOSTNAME.

Wave.AllowDottedLines * +
    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' (by editing `.Xdefaults').

Wave.Anntab
    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.

Wave.Dpi * +
    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 X11R4 servers, since this will solve problems common
    to any other applications that require calibrated scales as well.  Sun's
    xnews server, however, labors under the delusion that all displays have 83
    dots per inch resolution (true only for some 19" monitors) and cannot be
    persuaded otherwise, so it is necessary to inform WAVE using this resource
    or the `-dpi' command-line option if you are using xnews on any other type
    of monitor.  The command-line option overrides the resource if both are
    specified.

Wave.GraphicsMode * +
    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).

Wave.SignalWindow.{Grey|Color}.{Background|Grid|Cursor|Annotation|Signal}
    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:
				Grey		Color
		Background	white		white
		Grid		grey75		grey75
		Cursor		grey50		orange red
		Annotation	grey25		yellow green
		Signal		black		blue

Wave.SignalWindow.Mono.Background
    In monochrome mode, the background color is normally white, and all other
    colors are normally black.  The reverse can be obtained by setting this
    resource to `black'.  [There is at least one server for which this fails.]

Wave.SignalWindow.{Height_mm|Width_mm} *
    These resources specify the preferred dimensions (in millimeters) for the
    signal window.  The defaults are 120 and 250 respectively.  The signal
    window can be resized by dragging any of its resize handles using the left
    mouse button.

Wave.SignalWindow.Font
    This resource specifies the font used to display annotations and time
    marks in the signal window.  The default is `fixed'.

Wave.TextEditor
    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 invoke editors.

Wave.View.{Subtype|Chan|Num|Aux|Markers|SignalNames|Baselines|Level} *
    These resources specify which of the `Show:' options at the top of the
    `View' panel are enabled by default;  their values are `True' or `False'.

Wave.View.{TimeScale|AmplitudeScale} *
Wave.View.{SignalMode|AnnotationMode|TimeMode|GridMode} *
    These resources specify the initial positions of the menu choices in the
    corresponding `View' menus, 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 time scale to 50 mm/sec (the item at position 6 in the `Time Scale'
    menu), set Wave.View.TimeScale to 6.

Note that WAVE-specific resources cannot be set using the XView `-default'
or `-xrm' options.

Frequently Asked Questions
==========================

This is the WAVE FAQ (frequently asked questions) list.  It was last revised on
24 May 2000 (recent changes are marked with `*' below).

Hardware questions:
 * Can I use WAVE if I don't have a SparcStation?
 . How can I use WAVE from an X terminal, PC, Mac, etc.?
 . Can I run WAVE remotely using a modem?
 . How can I insert annotations using a two-button mouse?
 . How do I get spot help if I don't have a `Help' key?
Problems starting WAVE:
 * Why won't WAVE run?
 * Why does WAVE take so long to display the first screen?
 . Where do I find the missing fonts?
Display-related questions:
 . I can't see the signals!
 . I can't see text in the signal window!
 * WAVE doesn't draw/erase properly in the scope window!
 . How can I get correct display scales?
 . Why are signals too big or too small?
 . How can I change WAVE's default scales or display colors?
 . Why do colors in other windows change when I use WAVE?
 . Everything in the Analysis Commands window appears twice!
File-related questions:
 . I can't find the file named `RECORD'!
 * Why does WAVE tell me `Record ... is unavailable'?
 * How can I view a record stored on a web site or an FTP server?
Questions about editing:
 * Where are my annotations?
 . Why does WAVE tell me `You may not edit annotations ...'?
 * How do I edit a record on a CD-ROM, a web site, or an FTP server?
 * How can I undo an edit?
 . Can I define my own annotations?
 . How can I recover work after a crash?
 . Can I edit annotations with a text editor?
 . What are `link' annotations?
 . Can WAVE edit signal files?
What else can WAVE do?
 * How can I make a screen dump?
 . Can WAVE read digitized signals in (fill in the blank) format?
 . What is ``high-resolution'' mode?
 . Can WAVE open more than one record at once?
 . Can WAVE open more than 32 signals at once?
 . Can WAVE open more than one annotation file at once? 
 . Can WAVE do smooth scrolling?
 . Can WAVE be used for real-time display of data being acquired?
 . Can WAVE scroll through a record without user intervention?
 . How can I use WAVE's menu variables in a script or other program?
 * Is there a Motif version of WAVE?
 * How can I find out about ...?

If your question is not on this list, and you think it should be, please
send it to me (george@hstbme.mit.edu)!


Hardware questions
==================

Can I use WAVE if I don't have a SparcStation?
----------------------------------------------

If you have a 386, 486, or Pentium-based PC with a VGA card, mouse, at least
8 Mb of RAM and 100 Mb of available disk space, you can run WAVE under Linux,
a freely available UNIX clone for the PC.  Users have reported that WAVE can
be compiled and run successfully on DEC Alpha-based workstations under Linux,
and (in principle) it should be possible to run WAVE on any other type of
CPU supported by Linux (the list currently includes MIPS, PowerPC, Sparc, ARM,
as well as x86 and Alpha CPUs).

If you have any networked computer that can run X11R4 or a later version
(this includes all current UNIX workstations, PCs, Macintoshes, and a variety
of other systems), and access via network to another computer that can host
WAVE (see above), you can run WAVE remotely (see the next question).

Other WFDB applications (WVIEW for Microsoft Windows, VIEW for MS-DOS, MacView
for the Macintosh, and pschart and psfd for PostScript devices) offer many of
the display features of WAVE in other environments;  none of these currently
support annotation editing or control of external programs, however.


How can I use WAVE from an X terminal/PC/Mac/etc?
-------------------------------------------------

As with any X application, you can use an X terminal or any system equipped
with an X server to interact with a copy of WAVE running on another computer
connected to the same network.  To do so, however, requires a few additional
steps:

 - Find out the host names of the two systems.  On a UNIX system, the
   `hostname' command will give you this information.  If your display is
   connected to a PC or other non-UNIX system, you can try remotely logging
   onto the UNIX system on which WAVE resides, and using the `who' command
   to discover the name of the system in front of you.
 - Assume that your system is named HITHER and that WAVE resides on YON.
   You may need to add YON to the X server access control list on HITHER,
   in order to make it possible for X clients on YON to open windows on your
   screen.  If HITHER is a UNIX system, you can accomplish this by typing
   (on HITHER) `xhost +YON'.
 - Remotely log in to YON (for example, via ssh or telnet), and set the DISPLAY
   environment variable on YON to point back to your display.  If you use the
   C-shell on YON, this will normally be done by `setenv DISPLAY HITHER:0.0'.
   Bourne shell, Korn shell, and `bash' users should type `DISPLAY=HITHER:0.0;
   export DISPLAY'.
 - Check the connection by starting an X11 client such as `xterm' on YON.  A
   new window should appear on your display within a few seconds.  (See the
   documentation for your X server if this doesn't work).
 - Once you have succeeded in the test in the previous step, start WAVE in the
   usual way (`wave -r RECORD ...') on YON.  See `Where do I find the missing
   fonts?' (below) if your X server complains about missing fonts.  See `I
   can't find the file named `RECORD'!' (below) if WAVE complains about missing
   files.

X servers are standard on all current UNIX workstations, but not on PCs or
Macintoshes.  There are many MS Windows-hosted X servers available
commercially, as well as a smaller number of MS-DOS and Macintosh-hosted X
servers.


Can I run WAVE remotely using a modem?
--------------------------------------

It is possible, with appropriate (SLIP or PPP) software, to run WAVE
across a serial connection, but this will be painfully slow even with a 28.8
kbps modem.  Using WAVE remotely via Ethernet is usually quite tolerable,
however.


How can I insert annotations using a two-button mouse?
------------------------------------------------------

Normally, the middle button is used to insert annotations, so the problem is to
simulate a middle button click if you don't have a middle button. Most, if not
all, X servers that support two-button mice provide a way to do this. The most
common method is to press both buttons simultaneously (an operation sometimes
called ``chording,'' by analogy with playing a chord on the piano). Typically,
you have an adjustable window of 50 to 100 milliseconds in which to press both
buttons, so that you don't need exactly simultaneous clicks (which would be
impossible to achieve reliably). Some X servers delay reporting a button-down
event until a button-up event occurs; this approach makes chording less
error-prone, but it means that the feedback that WAVE produces in response to
button-down events gets delayed until it may no longer be useful. Another
approach, more commonly used with one-button mice, is to simulate the middle
button (and, if necessary, the right button) using a mouse button and keyboard
key combination, such as clicking while pressing the Shift or Ctrl keys. Check
your X server's manuals for information about which of these methods is
supported. With a little practice, annotation editing can be tolerable with a
button-impaired mouse.

Independent of the X server, WAVE also makes it possible to simulate a middle
button click, by using the F2 key (or the `5' key on the numeric keypad). If
you use this technique, you might also wish to use the F3 and F4 keys to drag
the pointer and marker bars left or right.

Inexpensive three-button mice, trackballs, and touchpads manufactured by
Logitech and many others are widely available for PCs, and are highly
recommended if you do much annotation editing. Most are fully compatible with
Microsoft two-button mice and with X server software for PCs. Some users prefer
trackballs for precision editing since there is no tendency for the pointer to
move when clicking the buttons, as with a mouse.


How do I get spot help if I don't have a `Help' key?
----------------------------------------------------

If you are not using WAVE with a Sun keyboard, use the F1 key to open XView
spot help for WAVE.  If this doesn't work, you may need to use the `xmodmap'
utility (a standard component of X11, usually found in the same directory
as other X clients such as `xterm').  Try the following command:
	xmodmap -e "keysym F1 = Help"
If this command fixes the problem, you may wish to include it in your
`.xinitrc' (a text file in your home directory;  create it if it doesn't
exist) so that spot help via F1 is enabled whenever you log in.

If you are not using olwm or olvwm, spot help may not work properly;  in
particular, your window manager may pass incorrect information about which
window is active when you invoke spot help.  There is no general solution
to this problem;  try using olvwm or olwm, at least until you are familiar
with WAVE's controls.


Problems starting WAVE
======================

Why won't WAVE run?
-------------------

Here are a few things to check:

1. The command used to run WAVE must be typed in lower case, as in:
	wave -r 100s -a atr
   Note that letters in record names and annotator names are also usually in
   lower case.

2. Try typing `wave' with no command-line arguments.  You should see a summary
   of options.  If you don't, `wave' has not been installed properly, is not
   in your PATH, or another program named `wave' is in your PATH.

   Errors similar to
	wave: can't load library 'libxview.so.3'
   indicate an installation problem which is probably shared by other
   applications that use the same libraries.  Use the command
	ldd `which wave`
   to identify which dynamically linked libraries are missing.  Locate these
   on your system (for example, using a command such as
	find / -name libxview.so.3 -print
   If any of these libraries cannot be found on your system, it may be
   downloaded from http://www.physionet.org/.  Add the directories in which the
   missing libraries are found to your LD_LIBRARY_PATH.  For example, if the
   missing libraries are located in /usr/openwin/lib, and you are using the
   C-shell, use the command
	setenv LD_LIBRARY_PATH /usr/openwin/lib:${LD_LIBRARY_PATH}
   Under Linux, if you can obtain root permissions, a more permanent
   solution is to add /usr/openwin/lib to the list of directories
   in /etc/ld.so.conf, and then to run `ldconfig'.

3. If the previous test works, try typing `wave -r 100s -a atr'.  (All WAVE
   distributions come with record 100s.)  One of the following should happen:
  * If you see a summary of options, rather than the WAVE main window, read
    the message carefully;  you may not have set the DISPLAY or WFDB
    environment variables, or the X server may not be running.
  * If you see a lengthy error message referring to missing fonts, see `Where
    do I find the missing fonts?' below.
  * If you see neither a summary of options nor the WAVE main window, the
    DISPLAY environment variable may be set incorrectly, the X server may be
    refusing permission to open a window, or your window manager may be waiting
    for you to specify the location or size of the window to be opened.
  * If you see only a message box reading `Record 100s is unavailable', your
    WFDB environment variable may be set incorrectly;  in this case, find the
    directory (probably /usr/local/database) containing a file named `100s.hea'
    and append the name of that directory to the value of WFDB.
  * If WAVE's signal window appears, but is solid white, your X server has a
    bug. Click on any of the navigation controls (e.g., `<<', `<', `>', or
    `>>'), or resize the window, to make the signals appear.
  * If the signals appear, but there are no annotations or time stamps in the
    signal window, your X server has a (different) bug.  Restart `wave', adding
    the `-S' option to the end of the `wave' command.  Also see `I can't see
    text in the signal window!' below.
  * If you see a correct display, your problem is specific to the record you
    were previously trying to view.  Find the directory containing the header
    file (`RECORD.hea', where RECORD is the record name) for the desired
    record, and append the name of that directory to the value of WFDB.

Why does WAVE take so long to display the first screen?
-------------------------------------------------------

If you are running WAVE remotely, a slow network connection may be the
reason for sluggish performance.  If possible, run WAVE locally, or get
a faster network connection.  You might also try changing the time scale
so that fewer points need to be drawn on each screen.

If you are using WAVE to view a record via FTP, it is currently not possible
to begin until the entire record has been downloaded;  for long records over
slow network connections, this can take a long time.  Some web (HTTP) servers
suffer from the same limitation.  If possible, use a web server that supports
HTTP range requests, such as Apache, or download a copy of the record to your
local disk.


Where do I find the missing fonts?
----------------------------------

WAVE is an XView application, and requires the Open Look cursor font on the
server.  If your server doesn't have this font (`olcursor.snf' for X11R4 and
earlier servers, `olcursor.pcf' for X11R5 and later servers), you must
install it before WAVE will run.  XView applications also use the `olgl??.snf'
or `olgl??.pcf' glyph fonts;  if these are missing, WAVE will run but certain
standard Open Look graphical elements will not have the correct appearance.  To
install these fonts on your X server's system:
 - generate copies of `ol*.snf' or `ol*.pcf' for your X server system's
   architecture;
 - copy `ol*.snf' or `ol*.pcf' to a world-readable directory on the server
   machine;
 - update the font database on the server machine; and
 - force the server to reread the font database.
You should be able to find `ol*.snf' or `ol*.pcf' files on the machine on which
WAVE resides (probably in /usr/lib/X11/fonts/misc).  The `ol*.pcf' files are
portable (although usually optimized for the architecture of the system on
which they are installed).  If you need to use `snf' fonts, however, and the
server machine is not of the same architecture, it will be necessary to find
`ol*.bdf' in the XView distribution and use `bdftosnf' to generate `.snf' files
for your X server system's architecture (see the man page for `bdftosnf'; this
step can be done trivially on the server machine, if `bdftosnf' is available
there, or with a little more trouble on the remote machine).  If the server
machine runs UNIX, read the man pages for `mkfontdir' and `xset' to see how to
update and reread the font database; otherwise, consult the documentation for
your X server.  Note that (under UNIX) you do not need to have write permission
in the standard font directory in order to perform these steps; if you add your
own font directory to the font path using `xset', however, remember that this
setting lasts only until the server exits and will need to be repeated
afterwards.


Display-related questions
=========================

I can't see the signals!
------------------------

If the signal window is solid white, your X server has a bug.  Click on any of
the navigation controls (e.g., `<<', `<', `>', or `>>'), or resize the window,
to make the signals appear.

If the signal window is solid or nearly solid blue (black if you have a
monochrome or greyscale display), the signals are too big.  WAVE may be
attempting to display signals that fill the entire window.  In rare cases,
noise in the signals themselves can produce this effect.  More common causes
include incorrect signal format or gain specifications in the header file for
the record you have opened, incorrect display calibration, or a choice of
amplitude scale that results in excessive vertical range of one or more
signals.  This effect can also occur as a result of various problems related
to the WFDB calibration file, for example, if the WFDBCAL environment variable
does not name an accessible WFDB calibration file (type `man wfdbcal' for
details), if any of the signals in the record are of types not listed in the
WFDB calibration file, or if the WFDB calibration file does not contain
appropriate default display scales for all of the signal types in the record.
See the next several questions for suggestions on correcting these problems.

If the signal window contains horizontal lines (in blue if you have a color
display) where the signals should appear, the signals are too small.  In this
case, the signal gains specified in the header file may be incorrect, the
display calibration may be incorrect, or you may have specified an amplitude
scale that reduces the vertical range of the signals to zero.  Click on
`View...' to check the scales, and adjust them if necessary.

If the signal window contains time indicators in the lower corners, look for
the signal names along the left edge of the window.  If there are no signal
names visible, click on `View...', then on `signal names' and `Redraw' in the
View panel.  If signal names still do not appear, either the header file or
the signal file for the record you have opened may be inaccessible.  Find these
files (see `File-related questions', below), add the directory that contains
them to your WFDB path, and try to read a few samples using
	rdsamp -r RECORD -t 1
If this fails, examine the header file for the record (a text file), and be
sure that it specifies at least one signal in an accessible signal file.


I can't see text in the signal window!
--------------------------------------

This may result from an X server bug.  This bug appears to be limited to X
servers that support `true color' (typically 24-bit) displays, when using
overlay graphics.  Restart `wave', adding the `-S' option to the end of the
`wave' command.

This problem may also occur on 8-bit `pseudo-color' displays, if another
application such as Netscape has already allocated most of the color map.  To
avoid this problem, start `wave' before starting Netscape.


WAVE doesn't draw/erase properly in the scope window!
-----------------------------------------------------

This problem may result from several different X server bugs. You may be
able to avoid it by switching from overlay graphics mode (the usual default) to
shared color mode (selected using WAVE's `-S' command-line option), or vice
versa, since WAVE uses different techniques for drawing in the scope window
depending on the display mode. 

A bug in network file handling can sometimes interfere with correct display
of waveforms in the scope window when reading records via HTTP.  For now,
the only workarounds are to restart WAVE, or to copy the record to local
disk files (this can be done easily using `xform', `snip', or a web browser).
Check http://www.physionet.org/ for updates to WAVE or to the WFDB library
that may correct this bug.


How can I get correct display scales?
-------------------------------------

Use `xdpyinfo' (a standard X client that is provided as part of the X core
distribution) to check several server parameters.  (As with virtually all X
clients, it doesn't matter which machine you find `xdpyinfo' on; it will query
your server from wherever it is run.)  `xdpyinfo' will report the version and
release numbers of your server; you should have version 11, release 3 or later.
It will also report the screen size in pixels and the resolution in pixels per
inch.  Take a minute to verify the screen resolution by direct measurement of
the screen with a ruler.  If the resolution reported by `xdpyinfo' is
incorrect, WAVE will not be able to draw waveforms at properly calibrated
scales.  The sample X11 servers from MIT and the X Consortium, and the XFree86
project's X11 servers, all support a `-dpi' option, which allows you to specify
the correct screen resolution at the time the server is started; read the man
page for X or Xserver for details.  (If your server does not support this
feature, WAVE can be given a similar `-dpi' option; see Options, above.)

You can also double-check your display calibration using WAVE itself.  Run
WAVE, enable the grid display, and set the display scales to their default
values (25 mm/sec, 10 mm/mV).  (Click on `View...' to pop up the controls for
the grid and the display scales; remember that any adjustments you make become
effective only after you click on `Redraw' within the View panel.)  The grid
intervals should measure exactly 5 mm in each direction.  If they are too
small, use a larger value for the `-dpi' specification; if the grid lines are
more than 5 mm apart, decrease the `-dpi' values.


Why are signals too big or too small?
-------------------------------------

There are several reasons why the size of signals may be incorrect.  WAVE
determines display scales for signals based on several parameters:
 - First, the WFDBCAL environment variable specifies the name of a text file
   (located in a directory in the WFDB path) containing the names of many
   common signals and customary display scales for each (expressed as physical
   units per centimeter).  For example, ECG signals are customarily displayed
   at a scale of 1 mV per centimeter.  If a signal appears at an
   inappropriately large or small scale, its name may be missing from the
   WFDBCAL file, the WFDBCAL variable may not correctly specify the name of
   the WFDBCAL file, or the WFDBCAL file may not reside in a directory in the
   WFDB path.  On most systems, the WFDBCAL file is
   `/usr/local/database/wfdbcal', and the WFDBCAL environment variable is set
   by the same command used to set the WFDB path (see above).  Instructions
   for adding additional signal names and scales to the WFDBCAL file are
   located within the WFDBCAL file, and may also be found in the WFDB
   Applications Guide.
 - Second, the header file for the record specifies the gain for each signal
   (the number of analog-to-digital units per physical unit).  If the gain has
   not been determined, or is incorrect, the size of the signal as drawn by
   WAVE may be incorrect as well.  If you know the physical values that
   correspond to at least two levels represented in the signal (for example,
   the top and bottom of a calibration pulse), you can use the `calsig'
   application to determine the gain and to rewrite the header file.  See the
   WFDB Applications Guide for details.  `calsig' can be most conveniently run
   from WAVE's Analysis panel.
 - Finally, the display calibration determines the number of pixels per inch
   (25.4 mm).  WAVE usually gets its information about the display calibration
   from the X server, but the X server may not supply the correct information.
   See `How can I get correct display scales' (above) for details on diagnosing
   and correcting this problem.


How can I change WAVE's default scales or display colors?
---------------------------------------------------------

The easiest way to make simple changes in WAVE's default display parameters is
by using the controls in the View panel to configure the display to your
liking.  If you then click on `Save as new defaults' in the View panel, your
choices are recorded in your `.Xdefaults' file (in your home directory) and
will be used for future WAVE sessions.  (Be sure that you have made your
changes effective by using `Redraw' before `Save as new defaults'.)

Colors are also determined by X resources that may be specified in your
`.Xdefaults' file, but the View panel does not include color controls.  See the
`Resources' topic in WAVE's on-line help, or type `man wave', for guidance on
setting display colors.


Why do colors in other windows change when I use WAVE?
------------------------------------------------------

WAVE queries the X server to determine how many colors it can display, and
what methods it can use to do so.  If the X server does not answer this query
correctly, WAVE may attempt to use a suboptimal or unavailable display mode.
If you find that the colors of other windows change when the cursor moves into
a WAVE window, you may prefer to use the `-S' option to avoid this behavior at
a slight (often unnoticeable) cost in speed.


Everything in the Analysis Commands window appears twice!
---------------------------------------------------------

This problem, which may occur when you are running WAVE under Linux, appears to
result from a bug in an early Linux version of the XView `termsw' package.
Type the command `stty -echo' in the Analysis Commands window, and the problem
should go away.


File-related questions
======================

I can't find the file named `RECORD'!
-------------------------------------

Record names are NOT file names; they are components of file names only.  For
example, three files belong to record 100s: 100s.hea, 100s.dat, and 100s.atr.
There is no file named `100s' belonging to the database.  See the WFDB
Applications Guide, section 5, for information about file types and formats.


Why does WAVE tell me `Record ... is unavailable'?
--------------------------------------------------

In common with other WFDB applications, WAVE searches for its input signals and
annotations in directories named by the WFDB environment variable (see the
discussion of the WFDB path in the WFDB Programmer's Guide).  If WAVE is
running remotely, remember to set WFDB on the WAVE host (a default can usually
be set for C-shell users by `source /usr/local/bin/cshsetwfdb', or for Bourne
shell, Korn shell, and `bash' users by `. setwfdb'; don't omit the `.').  The
directories named by WFDB are those on the WAVE host; thus (unless your WFDB
files are already on the WAVE host, or are accessible to the WAVE host via
HTTP or FTP -- see the next question) you must either transfer them to the
remote machine, or NFS- or RFS-mount the directory in which they reside onto a
suitable point in the file system of the WAVE host.  Furthermore, remember that
output annotation, log, and print files will be written to your current
directory on the WAVE host.

To get the pathname of a WFDB file, use `wfdbwhich' (type `man wfdbwhich' for
details).  For example, the output of `wfdbwhich header 100s' is the pathname
of the header file for record 100s (usually `/usr/local/database/100s.hea').
If `wfdbwhich' can't find the file, neither can WAVE (or any other WFDB
application).  In this case, you will need to check and correct the value of
the WFDB environment variable.  In unusual cases, the WFDB path may be correct,
but you may not have permission to read the file or one of the directories in
the path to the file;  in such cases, you will need to get the file's owner or
your system administrator to give you appropriate permissions.


How can I view a record stored on a web site or an FTP server?
--------------------------------------------------------------

Add the directory containing the record to your WFDB path, then use WAVE just
as you would to view a record stored on your local disk.  For example, suppose
the WFDB path is:
   . /usr/local/database http://www.signals.r.us/data ftp://sand.bar.com/pub
In this case, WAVE would look for input files first in the current directory
(.) of the local disk, then in /usr/local/database (which might be local or
might be part of a networked file system), then on the signals.r.us web site,
and finally on sand.bar.com's FTP server.  Unless you have a slow network
connection, you may not notice any difference between viewing locally and
remotely stored records.

Questions about editing
=======================

Where are my annotations?
-------------------------

When you create a new set of annotations, if you have specified the annotator
name in the Load window, WAVE saves your annotations in a new file with a name
of the form RECORD.ANNOTATOR, in the current directory.  When you edit an
existing set of annotations, WAVE makes a copy of the annotation file
containing your edits, gives it a name of the form RECORD.ANNOTATOR, and saves
it in the current directory (i.e., whatever directory was current when you
started WAVE).  To be able to read your annotations in a later WAVE session, be
sure that the directory that contains your edited copy is listed in your WFDB
path *before* any other directory that contains an older version of the same
annotation file.  Usually, your WFDB path begins with `.', a synonym for the
current directory.  If this is the case, simply return to the directory that
contains your edited annotation file before starting WAVE each time.

If you created an annotation file without specifying an annotator name,
WAVE uses its own name as the annotator name, so you should look for a file
named `RECORD.wave' in this case.  

Old versions of WAVE created annotation files with names of the form
ANNOTATOR.RECORD;  if you have any of these, rename them in order to continue
using them with WAVE.


Why does WAVE tell me `You may not edit annotations ...'?
---------------------------------------------------------

Since WAVE is often used to *view* annotated data, without necessarily editing
annotations, annotation editing is disabled when WAVE starts.  If you have
inadvertently done something (such as clicking the middle mouse button in the
signal window) that WAVE interprets as an editing command, it will warn you
that the editing action is disabled.

If you did intend to edit the annotations, select `Allow editing' from the
`Edit' menu, then repeat the edit.


How do I edit a record on a CD-ROM, a web site, or an FTP server?
-----------------------------------------------------------------

Be sure that your current directory is writable, that both your current
directory and the source (CD-ROM, web, or FTP) directory containing the record
you wish to edit are in your WFDB path, and that your current directory comes
*before* the source directory in your WFDB path.  When WAVE writes your edits,
they always go into the current directory (so the current directory cannot be
on a CD-ROM, since a CD-ROM is not writable).  At a later time, when WAVE (or
any other WFDB application) opens the record, it finds your edited version
first, and doesn't look for the original version, provided only that, in your
WFDB path, the source directory follows the one in which your edits are stored.


How can I undo an edit?
-----------------------

WAVE doesn't support a general mechanism for `undoing' edits.  Once you move an
annotation or change its attributes, you must manually restore its position and
attributes.  Deleted annotations can always be restored, however, by selecting
the `phantom' annotation left behind (these are displayed with a `.' for the
annotation mnemonic) and then `deleting' the phantom.  This action restores the
attributes of the original annotation, including the subtype, chan, num, and
aux fields;  if the annotation was moved, however, its original position (time
field) is not restored.

WAVE is careful not to destroy the version of the annotation file that was
current at the time WAVE loaded the record.  WAVE always saves edited
annotation files to the current directory (even if the original annotation
file was loaded from another directory).  WAVE's saved annotation files are
given names of the form `RECORD.ANNOTATOR'.  If, by saving its output, WAVE
would overwrite an existing file with the same name, WAVE first renames the
existing file by appending a tilde (`~') to its name.  Thus it is always
possible to recover the state of the annotation file as it was before you
began the most recent editing pass.  To do so, exit WAVE, and:
 * If there is a file with a name of the form `RECORD.ANNOTATOR~' in the
   current directory, rename it as `RECORD.ANNOTATOR'.
 * Otherwise, delete or rename `RECORD.ANNOTATOR' so that the previous version
   (which must be in another directory in the WFDB path) becomes visible once
   again to WAVE.


Can I define my own annotations?
--------------------------------

Yes.  See the file named `anntab' in the WAVE distribution for examples.


How can I recover work after a crash?
-------------------------------------

WAVE autosaves your edits at 1-minute intervals, or after every 20 insertions,
deletions, or attribute changes (repositioning doesn't count).  You don't need
to do anything special to recover your work, but you may lose up to a minute's
worth of edits.


Can I edit annotations with a text editor?
------------------------------------------

Believe it or not, sometimes users ask this question.

If you have unusual requirements (for example, if you want to change all
annotations of a certain type), you may be able to edit annotations more
efficiently using a text editor such as emacs. Since annotation files are not
text files, however, you will need to convert your files from binary to text
form to edit them, and then convert the edited text back to binary form in
order to use them further with WAVE. You can do this using rdann and wrann
(see rdann(1) and wrann(1), in the WFDB Applications Guide, for
details). 


What are `link' annotations?
----------------------------

By analogy to hyperlinks in World Wide Web documents, link annotations allow
external data (including documents, images, and audio annotations among other
possibilities) to be associated with specific locations in a record.  In fact,
any URL that can be understood by a supported web browser can be used to
specify the location of external data in a link annotation. Within the link
annotation, the URL appears as the first part of the aux string (in the Text
field of the Annotation Template). If the aux string contains any spaces, any
characters following the space are treated as a label to be displayed by WAVE
in place of the URL itself.

Support for link annotations is a new feature of WAVE 6.0. To view the external
data associated with a link annotation, select the link and press Enter (or
Return). If your web browser is not already running, this may take a few
moments while WAVE starts it. If nothing happens after a minute or so, check
WAVE's Analysis Commands window for errors that may have occurred when WAVE
attempted to start your web browser. (WAVE uses Netscape 1.1 or any later
version by default. See WAVE and the Web for details on obtaining Netscape, or
on configuring WAVE to use a different web browser.)

Link annotations may be moved, copied, attached to specific signals, inserted,
changed, and deleted just as for any other annotation. WAVE does not include
built-in facilities for editing the external data, however; other software such
as a text editor or a special-purpose HTML editor may be useful for this
purpose. 


Can WAVE edit signal files?
---------------------------

WAVE itself doesn't do this, but certain kinds of signal file editing are easy
to do using snip from WAVE's Analyze panel. A common requirement is to remove
unwanted data from the beginning or end of a record. To do this, simply mark
the segment to be retained using the `<' and `>' markers, then click on
`Extract segment'.

If your record contains unwanted signals, remove them from the Signal list
before extracting the segment. You can also rearrange the order of signals
within the signal list if you wish. 

Note that this operation does not modify the original record; rather, the
desired portions of the record are copied to create a new record. If you wish
to copy a set of annotations as well as data from signal files, be sure to load
the annotation file for the original record into WAVE before extracting the
segment. (See snip(1), in the WFDB Applications Guide, if you need to
copy two or more sets of annotations.)

To join two or more records end-to-end, use wfdbcollate to create a
multi-segment record. wfdbcollate writes a special header file for the new
record, but does not copy or modify the signal or header files of the original
records; it will, however, write new annotation files on request, since the
WFDB library does not support multi-segment annotation sets. The records to be
joined must be ordinary (not multi-segment) records. If necessary, xform can be
used to rewrite a multi-segment record as an ordinary record. See
wfdbcollate(1), in the WFDB Applications Guide, for further information.

More complex editing of signal files, such as splicing segments or modifying
individual samples, can be done by converting the signals to text form using
rdsamp (accessible from WAVE via the `List samples' button in the Analyze
window), editing the text as required, and converting the edited text to a
signal file using wrsamp (see wrsamp(1), in the WFDB Applications
Guide, for details). 

What else can WAVE do?
======================

How can I make a screen dump?
-----------------------------

If you really want a screen dump,
	xwd | xpr
will produce one in PostScript form.  (Type `man xwd' and `man xpr' for details
on options.)  Another way to do this, if xpr is not available, is
	xwd | xwdtopnm | pnmdepth 255 | pnmtops
If your printer is not a PostScript printer, you can still print
the output of either of these commands using Ghostscript, a freely available
PostScript interpreter.

Why settle for a screen dump, though?  In most cases, you will prefer to use
`pschart' to produce a much nicer plot, and in much less time.  Select `Print'
from WAVE's File menu to print the current contents of the signal window;  use
the `Print chart' option on the Analyze panel if you wish to specify start and
stop times.  Type `man pschart' or see the WFDB Applications Guide for
information about pschart's numerous formatting options;  if you don't like
the defaults, change them by editing WAVE's menu file (this also allows you
to change the default format for the `Print' choice on the File menu;  see
the comments in the menu file for details).

If you are plotting a great deal of data, you may wish to use `psfd' rather
than `pschart';  to do so, select `Print full disclosure' rather than `Print
chart' on WAVE's Analyze panel.  Most of pschart's options are accepted by
psfd.

If you need to collect a set of figures, either from a single record or from
many records, use WAVE's Log panel to record the times of interest, and enter
captions for each figure in the Description field of the Log panel.  The log
file generated in this way can be interpreted directly as a command file by
pschart, which prints the captions as titles for each figure.


Can WAVE read digitized signals in (fill in the blank) format?
--------------------------------------------------------------

Probably it can.  The most common formats for storage of digitized signals are
fixed-length binary formats that encode integer samples, and WAVE supports
dozens of such formats.  WAVE does not require any embedded header information
within signal files (but it can be made to ignore such information).  In most
cases, all you need to do is to write a header file that describes the format
in terms understandable to WAVE; once you have done so, any of the other WFDB
applications can also read your signals.  Writing a header file can be most
easily done by copying an existing header file and modifying it using a text
editor.  See signal(5) and header(5) in the WFDB Applications Guide for
details on supported signal formats and how to write a header file.

There are at least three common ways of storing multiple signals:  in separate
files, in multiplexed (sample-interleaved) files, and in block-interleaved
files.  In a multiplexed file containing N signals, each set of N consecutive
samples contains one sample from each signal.  In a block-interleaved file
containing N signals in blocks of 512 samples, for example, the first 512
samples come from the first signal, the next 512 samples come from the second
signal, and so on.  WAVE supports reading multiple signals from separate files
or from multiplexed files (or both in the same recording), but it does not
directly support block-interleaved files in general.

WAVE does support reading a special type of file containing signals sampled at
different sampling frequencies.  Files of this type contain "frames" of
samples.  Each frame contains at least one sample of each signal, but there
may be two or more samples of signals sampled at multiples of the frame rate
within each frame.

Block-interleaved files may be described simply as files with very large
frames. If you have a block-interleaved file, therefore, you may be able to
view it with WAVE via this expedient: 

  *  First, check that the block size in samples is no greater than
     WFDB_MAXSPF, a symbol defined in the WFDB library header file wfdb.h
     (which you will probably find in /usr/include/wfdb). If necessary,
     increase the value of WFDB_MAXSPF, recompile and reinstall the shared
     WFDB library (libwfdb.so.*), and check to be sure that WAVE loads this
     version of the WFDB library (use the command ldd `which wave`).
  *  Write a header file describing the layout of the block-interleaved signal
     file (see header(5), in the WFDB Applications Guide, for details). The
     sampling frequency in the first line of the header should be given as the
     frame rate (i.e., the basic sampling rate divided by the number of samples
     per block), and the ``samples per frame'' field in each signal
     specification line should be given as the number of samples per block. 
  *  Open the record in ``high-resolution'' mode with WAVE (see ``What is
     high-resolution mode?'', below). 

One significant limitation of this approach is that the time resolution of any
annotation files created in this way is limited to the frame interval. You can
avoid this limitation by reformatting the signal file (for example, by
following the steps above to verify that the signal file is properly readable,
then using xform with its own -H option; see xform(1) in the WFDB Applications
Guide.

A common feature of many signal file formats is embedded header data: bytes at
the beginning of the signal file that do not contain digitized samples.  By
specifying the length of the embedded header data as the byte offset for the
sample data in the (external) header file, such formats can be easily
accommodated; WAVE and any other applications built using the WFDB library
simply ignore any preamble. If the signal file format is documented, it is
usually not difficult to write a program to generate a header file based on
embedded header data. See header(5), in the WFDB Applications Guide, for
details on byte offsets.

WAVE does not support directly reading signals stored in text files, because
there is no general method for computing the position within such files of
samples occuring at arbitrarily-chosen times.  It is usually simple to convert
such text files into WAVE-compatible binary files using wrsamp(1), an
application supplied with WAVE.

For the same reason, WAVE does not support directly reading signals stored
using variable-length encoding or non-uniform sampling intervals.  If a
decompression utility is available, convert the data to fixed-length, uniform
samples.

WAVE does not support any non-integer storage formats either, mainly because
such formats are not commonly used for digitized data.

If you have signals in an unsupported format, you have two choices if you wish
to analyze them using WAVE:

 * Write a utility to convert your data to a supported format.  This is usually
   easy to do -- use `wrsamp.c' (the source for `wrsamp', provided with WAVE)
   as a model.
 * Add support for your format to the WFDB library, and recompile the shared
   WFDB library.  Once the new library is installed, WAVE and the other WFDB
   applications will be able to use your format without recompilation.
   If you have a large amount of data, this may be the only reasonable choice.
   It may not be much more difficult than writing a conversion utility,
   provided that your format permits computing file position as a function of
   time.  See the appendix titled `Extensions' in the WFDB Programmer's
   Guide for hints on how to proceed.

For example, WAVE does not support directly reading EDF, the European Data
Format first used for recordings of polysomnograms. (This is not the format
used for either the European ST-T Database or the MIT-BIH Polysomnographic
Database, both of which can be read directly by WAVE.)  EDF uses block
interleaving, and also includes an embedded header.  Although the method
outlined above for reading block-interleaved files can be used to read EDF
files, a difficulty in doing so is that the block size is specified within the
embedded header, and may vary between records.  Moreover, since typical block
sizes are quite large, the time resolution of annotations in this case is very
coarse. A format converter for EDF files, edf2mit (available from PhysioNet,
http://www.physionet.org/), may be used to rewrite such files in a format that
WAVE can read without these limitations. This converter also constructs a
suitable header file from the embedded header in the EDF file.

All currently supported signal formats use 16 bits per sample or less.  In
principle, formats requiring up to 32 bits per sample should pose no problem
in environments that support WAVE, but formats requiring more than 16 bits may
be difficult to support in other environments.


What is ``high-resolution'' mode?
---------------------------------

Briefly, it is an alternative display mode for multi-frequency records only.
See the WFDB Programmer's Guide for details on multi-frequency
records. 

The -H option, introduced in WAVE 6.0, selects high-resolution mode. For
ordinary records (those for which all signals are sampled at the same
frequency), high-resolution mode is identical to standard mode. 

In a multi-frequency record, some signals are sampled at multiples of the basic
sampling rate. These are referred to as oversampled signals. In standard mode,
WAVE decimates these signals (i.e., WAVE reduces their sampling rates to the
basic sampling rate by averaging successive samples) before displaying them. In
high-resolution mode, however, WAVE displays each sample from any oversampled
signals if the screen resolution is high enough (note that at standard display
scales, it may be difficult to see the difference).  In this mode, WAVE
replicates additional copies of each sample of any signals sampled at lower
rates before displaying them; in consequence, particularly at highly magnified
display scales, these signals may have a marked stairstep appearance.

Note that the time resolution for placement of annotations is the same in
high-resolution mode and in standard mode. Thus, for example, it is not
possible to place annotations on consecutive samples of an oversampled
signal, since the second annotation will replace the first one. This is a
limitation of the WFDB library, not of WAVE itself, and may be removed in a
future release of the WFDB library. 


Can WAVE open more than one record at once?
-------------------------------------------

Yes. All records should be listed in one command-line argument, following
the -r argument on the command line; separate the record names by `+'
characters. For example, the command 

    wave -r 237+237n &

starts a WAVE process group, opening a separate WAVE signal window for
each of record 237 and record 237n. Each signal window corresponds to a
separate WAVE process; thus you may browse through and edit each record
independently. The signal window assigned to the last record in the group (in
this case, 237n) is the master signal window; it contains a `Sync' button,
which may be used to synchronize the other signal windows with the master
at any time. By synchronizing, we mean that the other windows are redrawn
as necessary so that the times shown in their lower left corners match that
shown in the master signal window. 

Remote-control applications such as wavescript and wave-remote can also
start or control a WAVE process group. All signal windows in the group move
synchronously in response to commands from wavescript or wave-remote.
You may change the record that is open in any signal window, either via the
Load window or using a remote-control application. You may quit from any
signal window without affecting the others. 

Note that there are a few important limitations: 

  *  The number of signal windows (WAVE processes) in any process group
     cannot be increased once the process group has been created.
  *  Although you may run two or more WAVE process groups
     simultaneously, applications such as wavescript can control only a
     single process group at a time (by default, the last one started).
  *  Although you may have the same record open in more than one signal
     window, you should not edit the same annotator of the record in more
     than one window at a time (just as you should not edit the same text file
     in more than one editor window at once). You may edit different
     annotators of the same record freely. 

Taken together, the first two of these points imply that if you decide after
opening a record that you would like to add another record to the group, it
will be necessary to exit and start again, naming all desired records in the
group on the WAVE command line when you do so.

If you wish to move through two records sampled at the same sampling frequency
in lockstep (for example, to view digitally filtered signals and the original
unfiltered signals side-by-side), another approach is to create a single header
file that names the signal files for both records. It is not necessary for all
signals to be in the same signal file, or even on the same disk drive. In this
case, however, the total number of open signals must be 32 or less (see the
next question).


Can WAVE open more than 32 signals at once?
-------------------------------------------

Not without recompiling.  The limit is WFDB_MAXSIG (defined as 32 in
<ecg/wfdb.h>); it is necessary to recompile WAVE itself, as well as the WFDB
library, in order to increase this limit.  In a future version, the current
limit of 32 signals will be substantially increased or removed.


Can WAVE open more than one annotation file at once? 
----------------------------------------------------

No.  In most cases, however, it's not really necessary to do so.

For example, if you want to compare two sets of annotations of the same data in
order to study their differences, use `bxb' with the `-o' option to prepare a
comparison annotation file, and then use WAVE to open that file.  (Type `man
bxb' or see the WFDB Applications Guide for details.)  If your goal is to find
discrepancies, this is by far the best way to do so; `bxb' produces a
statistical summary of them, and you can search for NOTE annotations to find
each disagreement (enter `"' in the `Search for' field of WAVE's Find panel).

If you want to annotate multiple signals independently (for example, ECG and
respiration), set `Show annotations' to `attached to signals' in WAVE's View
window.  See `Multi-edit mode' under the `Editing' topic in WAVE's on-line
help for details.

If you already have multiple independent annotation files for a single record
(whether these contain annotations for independent signals or annotations
for disjoint segments of the record), you can use mrgann to merge them into a
single file, preserving information about which file each annotation came
from if you wish (see mrgann, in the WFDB Applications Guide, for
details). 

`wfdbcollate' can also be used for this purpose if you have separate annotation
files for each segment of a multi-segment record.


Can WAVE do smooth scrolling?
-----------------------------

No.


Can WAVE be used for real-time display of data being acquired?
--------------------------------------------------------------

Not easily.  If you have a UNIX application that can write data in a format
readable by WAVE, it should be possible in principle to run it from WAVE's
Analyze panel, and to use WAVE to review the data being acquired, using the
`Reload' button on WAVE's Analyze panel to read additional samples as they
become available.  (WAVE will not attempt to read beyond what it thinks is
the end of the record;  if it ever catches up with the digitizing process,
therefore, WAVE can only be forced to read further by using the `Reload'
button, or by closing and reopening the record.)


Can WAVE scroll through a record without user intervention?
-----------------------------------------------------------

Yes.  Create a log file that contains entries spaced at the desired intervals
throughout the record.  A suitable interval might be 10 seconds if that is the
width of the signal window, or half of that amount.  Open the log panel, load
the log file, and click on `>>' to start the scrolling.  Adjust the delay
between frames using the slider on the log panel.

Another way to review a record is via the scope window (accessible by clicking
on `Show scope window' on WAVE's Analyze panel).  Note that the scope display,
since it is triggered by annotations, is of no use in detecting erroneously
unannotated waveforms (false negatives), since such waveforms are simply not
displayed in the scope window.  The scope is useful for studying morphologic
variation of waveforms, and for locating erroneously annotated waveforms (false
positives).


How can I use WAVE's menu variables in a script or other program?
-----------------------------------------------------------------

See WAVE's default menu file for examples of passing WAVE's menu variables
as command-line arguments to other programs.

Click on `Export variables' in WAVE's analyze menu if you need to use these
variables within a shell script.  (If you are not using csh or tcsh, edit
the WAVE menu file first to select the alternate definition of this action.)
Once the variables have been exported, they may be used in the same way as
any other environment variables within your shell scripts.  For example, the
time of the left edge of the signal window is $LEFT.  Within a C program,
read the values of these variables using `getenv';  for example, getenv("LEFT")
returns the (string) value of the time of the left edge of the signal window.
Note that the exported values are only a snapshot of the variables at the time
you click on the `Export variables' button;  the values do not track later
actions performed within WAVE.


Is there a Motif version of WAVE?
---------------------------------

No. (Rant begins here.) When I designed WAVE, I attempted to use Motif, but
switched to XView when it became clear that much of the documented
functionality of the Motif toolkit (at the time, version 0.9) was
unimplemented or unusable. It also seemed unlikely that anyone would prefer
Motif's buggy, ugly, proprietary, bloated, kludgy procedural interface over
XView's buggy, attractive, non-proprietary, streamlined, elegant
object-oriented interface (end of rant). 

Motif and its lookalikes (notably GTK+, Qt, and LessTif) have clearly become
the standard, however, and a consequence of this is that the Open Look user
interface presented by WAVE is unfamiliar to many users. There is a scarcity
of introductory material for Open Look in print (but there is an excellent
and comprehensive set of documentation available on CD-ROM from Darwin Open
Systems, http://www.darwinsys.com/).  Unfortunately, the Motif API, and those
of its lookalikes, are vastly different from the XView API with which WAVE is
written, and a port to a Motif-like user interface would be decidedly
non-trivial.


How can I find out about ...?
-----------------------------

There are several sources of information about WAVE:

 * If you have not used WAVE before, start by reading the WAVE User's Guide
   and working through the tutorial examples it contains.  If you need to
   use existing WFDB applications under WAVE's control, refer to the WFDB
   Applications Guide.  If you need to develop your own applications for use
   with WAVE, read the WFDB Programmer's Guide.  Printed copies of
   these guides may be purchased from MIT, or you may read them on-line or
   print your own copies (visit http://www.physionet.org/).
   
 * The on-line version of the WAVE User's Guide can be opened for browsing by
   clicking left on `User's Guide' in WAVE's Help Topics window (this requires
   WAVE 6.0 or later, and Netscape 1.1 or later on the WAVE host). This guide
   may also be read with any Web browser independently of WAVE (point your
   browser to file:///usr/help/html/wug/wug.htm if you have installed WAVE
   6.0 or later, or to http://www.physionet.org/physiotools/wug/ otherwise).

 * Use XView spot help for brief descriptions of WAVE's controls and other
   graphic elements.  Point to any control and press the Help key (see `How
   do I get spot help ...', above, if you don't have a Help key).

 * Use WAVE's task-oriented on-line help (of which this is a part) to learn
   how to use WAVE as a tool for interactive data analysis, control of external
   programs, annotation editing, and other topics.  Click left on `Help' in
   WAVE's main control panel to open the Help window, containing buttons for
   each topic.  Click left on any of these buttons to open a help window for
   the associated topic.  Within the help window, use the scroll bar to move
   through the topic, or click on the `Print' button to obtain a printed copy
   of the entire topic.

 * Select `About WAVE...' from the `Properties' menu, or select `What's new'
   from the Help panel, for a summary of new features in WAVE, a current list
   of known bugs, and instructions for printing a copy of the on-line manual,
   which includes the text of all of the other help topics.  Click on the
   `Print' button to obtain a printed copy of the `What's new' topic.

 * The man page for `wave' contains a concise description of its command-line
   options, the environment variables and X resources it uses, and the WAVE
   menu file.  (This information is also included in the WAVE User's Guide;
   the man page is intended as a compact reference.  The man page for `wave'
   can be found in the WFDB Applications Guide, or on-line by typing
   `man wave', or by using `xman' or `tkman', etc.)

 * For additional information on the WAVE Analyze menu file, see the comments
   in the default menu file distributed with `wave' (usually installed as
   `/usr/lib/wavemenu.def').

 * For information about the data formats supported by WAVE and the other WFDB
   applications, see section 5 of the WFDB Applications Guide, or the man pages
   for annot(5), header(5), signal(5), and wfdbcal(5).
