WAVE: Waveform Analyzer, Viewer, and Editor George B. Moody Massachusetts Institute of Technology WAVE version 6.7 was installed Fri Jan 7 11:37:05 EST 2005 ------------------------------------------------------------------------------- WAVE: Waveform analyzer, viewer, and editor Copyright (C) 2002 George B. Moody 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. You may contact the author by e-mail (george@mit.edu) or postal mail (MIT Room E25-505A, Cambridge, MA 02139 USA). If you are submitting a bug report, please include your name and address, and the version number and date shown above. Thanks! For updates to this software, please visit PhysioNet (http://www.physionet.org/). _______________________________________________________________________________ For a copy of this document, print `/usr/local/help/wave/news.hlp' (or click `Print' at the top of the window if you are viewing this from within WAVE). For a copy of the on-line help for WAVE, print `/usr/local/help/wave/wave.hlp'. For a copy of the WAVE User's Guide (a tutorial introduction and reference manual for WAVE), use your web browser to open /usr/local/help/html/wug/wug.htm (or http://www.physionet.org/physiotools/wug/wug.htm), or print /usr/local/help/html/wug/wug.ps on a PostScript printer. Summary of changes from version 5.0 ----------------------------------- - WAVE User's Guide in hypertext - Coordination of multiple WAVE processes - Remote control of and by Netscape - `Level' window - Signals may be rearranged in the signal window - Fine and coarse grid options - Automatic selection of time scale - New controls in the `Analyze' window - New WAVE menu features - Enhanced log functions - Enhanced scope functions - New help topic: frequently asked questions - New versions of WAVE for 386 Linux and Sparc Solaris 2.x are available - New command-line options for specifying the first screen to view - New X11 resources and command-line options for setting display preferences - New controls in the `View' window (annotation, signal, time display options) - Keypad annotation editing and display commands - Multi-edit mode - Signal selection using the mouse - Fewer restrictions on WAVE menu files - Timed autosave - WFDB environment editing - Support for remote file access via web (HTTP) and FTP servers - WAVE sources now available freely under the GPL - All previously reported bugs fixed New features ------------ - If you have a web browser such as Netscape, you can read the WAVE User's Guide on-line. WAVE's Help Topics window contains a `User's Guide' button that opens the guide using Netscape or the browser of your choice. (If you don't use Netscape, you will need to customize the `url_view' script provided with the WAVE distribution.) Some topics in WAVE's spot help have `More' buttons that link in this way to the User's Guide for an in-depth discussion. - You may open two or more records at once if you start WAVE with a command such as wave -r 100+101+102 (which opens records 100, 101, and 102 in separate main windows). Each main window is a separate WAVE process, and may be controlled independently of the others. The `master WAVE process', corresponding to the last named record, has an extra button (labelled `Sync') in the control panel; clicking on this button causes all of the other windows in the process group to become synchronized with the master WAVE process. (This can also be done by clicking on any point in the signal window of the master WAVE process, using the middle mouse button while also pressing .) It is also possible to open the same record in two or more windows, and to select different displays for each one, by a command such as wave -r 100+100 +0/-display +0/some.other.cpu:0 (which opens record 100 in a window on `some.other.cpu', and also in a master WAVE window on the local display; for this to be done successfully, it is usually necessary to run `xhost' on the remote system to permit the WAVE host to open a window on it). For further details on teleconferencing via WAVE, and other applications of this feature, see the WAVE User's Guide. - A new LINK annotation type (mnemonic `@') has been added to the WFDB library. The aux field of a LINK annotation contains a URL and an optional comment. WAVE displays the comment, underlined and distinctively colored, in the manner of a Web browser; if you select a LINK annotation, WAVE uses the `url_view' script included in the WAVE distribution to cause your web browser to open the specified URL. Going in the opposite direction, the `wavescript' application included in the WAVE distribution can be used as a helper by a web browser; `wavescript' starts WAVE if necessary and causes it to display a segment of a record as specified by the file named on its command line. It is therefore possible to use a browser such as Netscape to control WAVE, and vice versa. For details, see `WAVE and the Web' in the WAVE User's Guide. - If you have enabled `levels' in the `View' window, WAVE now opens a `Level' window if you press a mouse button while the pointer is in the signal window. The `Level' window shows the time and amplitudes of the samples at the pointer location; this information is updated continuously whenever a mouse button is depressed. Using the `Show' menu at the top of the `Level' window, you may choose to view the time and amplitudes in physical units (seconds, mV, etc.) or database units (sample intervals and analog-to-digital converter units); you may also choose to view absolute time and levels, or time interval and levels relative to a reference marker. The reference marker (there may be at most one defined in any record) may be inserted, moved, or deleted in the same way as any other marker; its mnemonic is `;'. - If you choose to draw `listed signals only' using the Draw menu in the `View' window, signals shown in the signal window are now arranged as they appear in the signal list. - A new fine grid option (0.04 s x 0.1 mV) has been added to the `Grid' menu in the `View' window. If this option is selected, every fifth grid line is emphasized. At standard display scales (25 mm/s, 10 mm/mV), this option specifies a 1 mm grid. Two more new grid options are for use at condensed time scales. These offer grid lines at 1 minute intervals, with every fifth grid line emphasized; these may be used with 0.5 mV horizontal grid lines, or without horizontal grid lines. - Records sampled at very low frequencies (10 Hz and under) are automatically displayed at a condensed time scale, and with a coarse time grid. You may choose any desired time scale and grid mode for such records if the default is not satisfactory, and you may change the default by saving the desired settings in the `View' window while a low-rate record is open. Doing so does not affect the default time scale or grid mode for high-rate records. - In the `Analyze' window, the standard controls (i.e., those not defined in the menu file) are now all at the top of the window (several appeared at the bottom of the window in previous versions), and six new standard controls (`<', `>', `From', `To', `Signal list' and `Reload') have been added. The `<' and `>' buttons allow you to shift the analysis interval (the interval between the `Start' and `End' markers) in either direction without changing the length of the interval. The `From' and `To' controls show the date and time of day corresponding to `Start' and `End', if the header file for the record contains a start time and date. You can adjust the analysis interval by changing either `Start' and `End' or `From' and `To', as you wish. `Signal list' is a string, initially set to the list of available signal numbers in the current record. The signal list may be edited directly, or the current signal may be appended to or deleted from the signal list using the mouse (point to the desired signal, press and hold down the key, and click the left mouse button to add the signal to the signal list; follow the same procedure using the key instead of the key to delete the first occurrence of a specified signal from the signal list). If you click on `Reload', WAVE waits until any pending foreground commands issued from the Analysis command window are complete, and then WAVE reloads the current record. If a pending command is rewriting the annotations or signals being viewed, using this button allows you to view the revised files as soon as they are complete. You can also use this button to load `snapshots' of files being written by commands running in the background, but do not attempt to edit such `snapshots'. - Several additional variables can now be used within WAVE menu files to control external programs. If the WAVE menu contains the string `$SIGNALS' in a command, the signal list will be inserted at that position in the command. (Note that the meaning of the current $SIGNAL variable is unchanged.) The current display scales used by WAVE are available in the WAVE menu as $VSCALE (the amplitude scale, in mm/mV) and $TSCALE (the time scale, in mm/sec), and other WAVE display options are available in $DISPMODE. See the default WAVE menu file for details on $DISPMODE and for examples of all of these variables in use. - New controls have been added to the log window. The `Load' button forces WAVE to load or reload the current log file; this feature is useful if another process (such as a WAVE analysis menu button) has been used to create or modify the current log file. The `Edit' button now allows you to edit a log file using your favorite text editor (set the EDITOR environment variable or the Wave.TextEditor resource; the default is the standard Open Windows `textedit' utility). New buttons labelled `|<' and `>|' allow you to jump directly to the first or last entry in the log. Finally, the `Delay' slider allows you to change the update frequency (from once per second up to once per ten seconds) while using review mode. - New mouse and keyboard controls have been implemented in the scope window. Click left or right within the scope window to single-step the scope display backward or forward respectively. Click the middle mouse button to pause the continuous mode display and to recenter the main window on the current waveform in the scope window. Press and hold down the key while clicking left or right to resume the continuous mode display. Press while clicking the middle button to adjust the delay time (the interval from the left edge of the scope window to the trigger point). The left, up, and right arrow keys emulate the mouse buttons within the scope window (but you must click at least once using the mouse to move the keyboard focus into the scope window before these keys work). - Frequently asked questions and answers have been gathered in a new help topic. Select `Frequently asked questions' from the Help window to review this topic. Please submit additional questions, answers, and suggestions to the author at the address above. - At last, there is a version of WAVE that runs on a PC! WAVE has been ported to Linux, a freely available UNIX clone for 386/486/Pentium PCs. See file `LINUX', in the WAVE distribution, for further information. There is also a version of WAVE that has been recompiled for Sparc Solaris 2.x. The standard version for SunOS 4.x will also run in SunOS binary compatibility mode under Solaris 2.3 and later versions, but the native version for Solaris is a better (i.e., faster and more robust) choice for such environments. - You can now specify the starting time of the first screen shown by WAVE using the `-f' command-line option. For example, wave -r 100 -a atr -f 25:14 opens record 100 at 25 minutes and 14 seconds from the beginning of the record. You may also set the initial value of the signal list (see below) using the `-s' option. For example, wave -r slp60 -a ecg -s 0 2 3 -f 1:30 opens record slp60 at 1 minute and 30 seconds from the beginning, and initializes the signal list to contain signals 0, 2, and 3. If the option `-VS 1' is also used (see next item), WAVE displays only the signals in the signal list. Note that the meaning of `-s' has been changed from previous versions, to conform with the convention used by many other WFDB applications for specifying signal lists. To force WAVE to use a shared colormap, use the new `-S' option. The new `-O' option forces WAVE to use overlays instead, if the display supports them (this is the default behavior unless the resource Wave.GraphicsMode has been set to a value other than 0 or 8). - WAVE now allows you to specify initial values for the settings controlled from the `View' window using either X11 resources or command-line options. In addition, you may save the current settings as defaults for the next time you run WAVE. The following command-line options and X11 resources may be used to initialize the `View' settings: Option X11 resource -Vs Wave.View.Subtype -Vc Wave.View.Chan -Vn Wave.View.Num -Va Wave.View.Aux -Vm Wave.View.Markers -VN Wave.View.SignalNames -Vb Wave.View.Baselines -Vl Wave.View.Level -Vt CHOICE Wave.View.TimeScale -Vv CHOICE Wave.View.AmplitudeScale -VS CHOICE Wave.View.SignalMode -VA CHOICE Wave.View.AnnotationMode -VT CHOICE Wave.View.TimeMode -VG CHOICE Wave.View.GridMode The options and resources in the first group correspond to the like-named `Show:' options at the top of the `View' window. By default, all of these options are off (false); set any of the X11 resources to `true' to enable these options, or use the command-line options to do so. For example, to enable initial display of markers, either use `-Vm' on the command line, or `Wave.View.Markers:true' in the X11 resource database (for example, in your `.Xdefaults' file). The options and resources in the second group correspond to the menu buttons that appear in the remainder of the `View' window. The CHOICE argument, or the value of the X11 resource, should match the position of the desired menu choice in the corresponding `View' menu, where the top item on the 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), add `-Vt 6' to the command line, or `Wave.View.TimeScale:6' to the X11 resource database. Click left on `Save as new defaults' in the `View' window to retain WAVE's current settings as defaults for future WAVE sessions. In addition to the options on the `View' window, this action also records the screen resolution (which you may specify on the command line using the `-dpi' option), the signal window size (which you may change by dragging the resize handles on the signal window), and the graphics mode (which you may specify on the command line using the `-g', `-m', `-O', or `-S' options). Note that WAVE's current settings, and those that are saved as defaults, are those reflected in the signal window. If you have modified `View' window options since the last time the signal window was redrawn, these modifications have not been applied, and are not saved. - Three controls have been added to the `View' window. Using the `Draw:' menu button, you may instruct WAVE to draw all available signals (the default) or those in the signal list (see below) only. Using the `Show annotations:' menu button, you may view annotations centered in the signal window (the default), attached to the signal specified by the `chan' field of each annotation, or as a signal. This last option replaces the standard annotation display with a signal (drawn in the annotation color, in the center of the signal window) derived from the `num' fields of any annotations in the window. Turn off this selection to restore the normal display. Finally, the `Time display:' menu button allows you to choose to display and enter elapsed times (the default), absolute times (if the header file for the record contains the absolute time of the beginning of the record), or (elapsed) times in sample intervals. WAVE shows elapsed times in the corners of the signal window in the signal color; absolute times are drawn in the annotation color. - Whenever the pointer is in the signal window (as indicated by a crosshair cursor replacing the normal arrow pointer), the numeric keypad and several of the function keys may be used for many annotation editing and display operations. `Num Lock' must be off if you wish to use the keypad for these operations. The keypad commands are: <1> (End): moves the display window to the end of the record <2> (down-arrow): moves the selected annotation down one signal (see next item) <3> (PgDn): moves the display window back half a screenful (or a full screenful if is depressed) <4> (left-arrow): behaves like the left mouse button (*) <5>: behaves like the middle mouse button (*) <6> (right-arrow): behaves like the right mouse button (*) <7> (Home): moves the display window to the beginning of the record <8> (up-arrow): moves the selected annotation up one signal (see next item) <9> (PgUp): moves the display window forward half a screenful (or a full screenful if is depressed) <=>: moves the pointer left (with acceleration while the key is held down) <*>: moves the pointer right (with acceleration while the key is held down) Function key commands are: (or F6): copies the selected annotation into the template (or F9): simulates clicking on `Search >' in the main window; if is depressed, simulates `< Search' (*) Note that the and keys may be used in combination with the numeric keypad keys <4>, <5>, and <6>, and that these combinations work just as when using the mouse buttons. does not work with the numeric keypad, however. See the section on PC keyboard equivalents (below) if you are not using a Sun keyboard. - `Multi-edit mode' is enabled when you open a record with two or more signals, enable annotation editing, and show annotations attached to signals (see the previous item). In multi-edit mode, annotation editing operations are slightly different from the usual ones. 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 key during these operations to copy the annotation, rather than to move it (simultaneous annotations are permitted if their `chan' fields differ). - Signals may be selected using the mouse. Point to the desired signal, press and hold down the key, and click the left mouse button. The selected signal remains highlighted until the signal window is redrawn. The value in the `Signal' field of the `Analyze' window changes to match the selection. - Command strings in the WAVE menu can now be much longer (up to 1024 characters each, including the button label). There is no longer any limit (other than those imposed by the X server and by total available memory) on the number of menu entries (buttons) in the `Analyze' window. If the environment variable WAVEMENU is not set, but a file named `wavemenu' exists in the current directory, WAVE uses that file as its menu file; otherwise, WAVE uses the system default menu file. As always, WAVE offers to create `wavemenu' if you attempt to edit the system default menu file. - WAVE now saves your edits at one-minute intervals. Note that this operation is postponed until you perform an edit. - The `Load' window now allows you to change the WFDB environment (WFDB path and WFDB calibration file) without exiting from WAVE as was necessary previously. Note that any changes you make are local to the current WAVE process, although you can export these values to processes running in the Analyze window using the symbols $WFDB and $WFDBCAL in the WAVE menu file. - WAVE (and all other applications based on the WFDB library) can now read input files from web sites and FTP servers, provided that the WFDB library has been compiled together with libwww (see http://www.w3.org/Library/). To do so, simply add the appropriate http:// or ftp:// base URL to the WFDB path, and use WAVE in the usual way. - Sources for WAVE are now available on the web at http://www.physionet.org/. WAVE has been released under the GNU Public License (GPL), which permits it to be copied and redistributed without cost. Bug fixes --------- - Several bugs that caused WAVE to crash or behave oddly when searching beyond the end or before the beginning of an annotation file have been fixed. - WAVE now contains a work-around for an X server-related problem that sometimes caused annotations to be moved inappropriately when clicking the left or right mouse button rapidly. - In previous versions of WAVE, if the record name was changed while there are unsaved edits, an inappropriate error message appeared (asserting that write permission must be obtained in the current directory before continuing) and it was then impossible to save the edits or to continue. (There may have been other ways of triggering the same bug.) This bug has been fixed. - WAVE now contains a work-around for an XView library bug that occasionally caused earlier versions to dump core after the WAVE menu file was reread. This problem occurred if menu items were added more than once in a single session; there may have been other ways of triggering the same bug. A side effect of the work-around is that the `Analyze' window may reappear in a different location after the menu file has been reread (this depends on the window manager). There is no way to keep the window position fixed and avoid crashes at the same time, short of fixing the bug in the XView library. - WAVE (and other WFDB applications) crashed in some cases after closing a record and reopening it or another record; the cause of this problem was a WFDB library bug, which was fixed in WFDB library version 9.7. - WAVE version 6.0 contained a bug that caused crashes when attempting to change all annotations within a specified range; this has been fixed. PC keyboard equivalents for Sun function and numeric keypad keys ---------------------------------------------------------------- WAVE can be controlled using the mouse and the normal alphanumeric keys only, but there are a few alternate controls that use function keys and the numeric keypad. The on-line help for WAVE generally describes how to use these functions on a Sun keyboard. On a PC keyboard, some substitutions must be made: Action PC key Sun key Open spot help Simulate middle mouse button click keypad <5> Move editing cursor left keypad <=> Move editing cursor right keypad <*> Copy selected annotation to template Search forward Advance to the end of the record Search backward Move to the beginning of the record Advance half a screen Advance a full screen Move back half a screen Move back a full screen These PC equivalents are also usable on Sun keyboards. In addition, all of the actions that can be performed using the Sun arrow keys can also be performed using the PC arrow keys. Cautions -------- Whenever the annotator name appears within parentheses in WAVE's title bar, there are unsaved edits. Unsaved edits may be saved by selecting `Save' from WAVE's `File' menu, by changing to another record or existing annotation file, or by exiting from WAVE via the `Quit' button (but not via `Quit' from the system menu, see below). There are still three known ways to lose your edits in WAVE: - If you are running WAVE in the foreground under SunOS, and you have opened the `Analyze' window or have selected `Print' from the `File' menu, do not attempt to suspend WAVE (for example, by typing control-Z in the terminal window from which WAVE was started). Under these circumstances, WAVE may be killed immediately (without quit confirmation) and any unsaved edits are lost. To avoid this problem, always run WAVE in the background (use `&' at the end of the WAVE command line). Note that it doesn't matter if the `Analysis commands' window is open, only that it has been opened at some time in the current WAVE session. Using the `Print' command invisibly opens the `Analysis commands' window, and thus has the same effect. This problem is the result of a bug in the XView `termsw' package used for the `Analysis commands' window. The Solaris 2.x and Linux versions of the XView library do not have this bug, and this problem does not occur except when running WAVE under SunOS 4.x. - If another process sends any of several termination signals to WAVE, WAVE is killed immediately (without exit confirmation). This may be regarded as a feature rather than as a bug. A system crash has the same effect. - If you select `Quit' from the system menu, WAVE pops up a quit confirmation notice box; if you confirm that you wish to quit, WAVE quits immediately, and any unsaved edits are lost. To avoid this, always use WAVE's `Quit' button on the main control window; when you select it, WAVE pops up a quit confirmation notice box, but saves edits first if you confirm that you wish to quit. To limit the amount of damage resulting from loss of unsaved edits, WAVE autosaves your edits frequently (at one-minute intervals, or after every 20 edits). On some 24-bit displays, an X server bug causes WAVE to start with an empty signal window. Using any of the navigation controls, or resizing the window, should make the signals visible. On some of these displays, text in the signal window may be invisible using overlay graphics mode; if this happens, use the `-S' option. 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.