xavr - ERP Data Viewer

Contents

Synopsis

-----------------------------------------------------------------------------
EEP 3.1  Max-Planck-Institute of Cognitive Neuroscience 1996-99
xavr 3.45   (OSF1 V4.0 alpha)                 Wed Sep 15 13:30:19 1999
-----------------------------------------------------------------------------
  xavr <cfg> [<cfg> ...] [<avr in> ...] [options]

options:
  -p [<dir>]     create an average file list from <dir> and its subdirs
                 if <dir> is omitted, the current directory is used
  -G <gav cfg>   create an average file matrix from the avraverage cfg
  -f <fir file>  enable FIR filtering of the displayed averages
  -r <reref cfg> enable referencing of the displayed averages
  -e             display ERP (default if nothing of [-edvs] is set)
  -d             display difference signal
  -v             display standard deviation band
  -s             display significance
  -t             display standard error of mean
  -D <dat file>  sensor positions for potential maps
  -N <number>    number of mesh control points for map interpolation
  -P <ps file>   write PostScript file(A4-Landscape) and exit
  -w             don't popup dialog windows at startup
  -S             slave mode, honor remote control requests

Description

Specifically, xavr can

• collect the .avr files from the project tree in a more handy list or matrix of files
• rereference, average, filter, subtract ERP data "on-line"; save these processed data as .avr files
• display the data in highly configurable time series diagrams and contour plots
• create fully scaleable PostScript plots
• display data in a more interactive windows which allows to inspect signal values, to find peaks or to animate maps
• add annotation texts/pointers and include EPS illustrations in its plots

Configuration

Configuration File

Look at the files xavr*.cfg in the EEP configuration directory. Use one to start xavr, do your modifications and save your own version (Edit - Configuration...)

Resources

Some more permanent dialog settings (current size/position, entered values) can be saved from within xavr (Options - Save Settings). They are stored as standard X resource lines in ~/.eep/xavr.resources. For xrdb gurus: these resources are written with full qualifiers and read after all other resources with lowest priority.

Usage

Collect Average Files

To prepare a list of files:

• Supply a list of average files in the command line. The files are collected in the list and displayed immediately. Use the shell capabilties here to build a list of files. The bash, for example, expands
  xavr xavr.cfg su23/avr1/su23{c1,c2,c3}.avr
  to a command with 3 average files (guess the names...).
• Supply a path to be scanned recursive for avr-files with the -p command line switch. All files found are collected in the list; nothing is displayed. Be careful with this option. It can take a while to scan a huge project tree in a remote directory and in most cases you certainly don't want to see a few hundred ERP's in one session.
• Call File - Load Average List from the menu. This performs the same action like the -p command line switch. If the list would become very large, the filenames can be filtered using a regular expression - typically one would use the subject code or the name of the subdirectory where the interesting averages reside.

To prepare a matrix of files:

• Supply a avraverage configuration file via the -G command line switch. In opposition to avraverage it is not an error if a listed file is not found. Maybe it's a good idea to have a "maximal" configuration file containing all subjects and conditions you expect to have and let xavr remove the currently incomplete rows/columns from this matrix.
• Load a avraverage configuration file via File - Load Average Groups - Grand Average Configuration. See the previous point.
• Scan the directory tree via File - Load Average Groups - Directory Tree.

The preparation of an average list/matrix has no effect to the display. Its only purpose is to give you access to the average files in a convenient way (without the need to surf up and down in the project directory tree). You have to use the selection dialogs to bring the data in the drawing.

Select Displayed Data

• Select - Average Files
  The current list of average files is displayed in a dialog. You can make your selections in the list and add the selected files to the drawing by activating the Add button. Set clears the drawing before adding the selected files.

• Select - Average Groups
  This dialog allows the on-line grand averaging. See the example/explanation.

Process Data

For example, if your find an ERP too noisy and want to compare it with a low-pass filtered version, you could toggle Deferred Processing on, and load a .fir file. If you now Add the same file again in the selection dialog, the filtered ERP is displayed too. With Deferred Processing off, the displayed ERP is filtered immediately. This way is faster but gives no chance to compare different processing states of one file.

One should use the processing functions with care. For example, it might lead to some confusion if a rereferenced average file is rereferenced by the viewer again. For this reason, the processing options cannot be stored elsewhere, but few of them can be requested in the command line.

• Reference
  You can enter reference settings in the dialog fields exactly as you would write them in a avrreref configuration file.

• Baseline
  For each ERP channel, the mean of the given baseline window is calculated and substracted from the whole signal. It is merely a vertical shift, not the same like changing the baseline window in cntaverage.

• FIR Filter
  This point applies a Finite Impulse Response filter and requires a precalculated impulse response (*.fir). Note that this filter is useful only if all displayed ERP's have the same sampling rate.

  ref:    rereference
  bsl:    baseline
  gav:    grand average
  fir:    FIR filter

load -> [ref] -> [bsl] -> [gav] -> [fir] -> draw

Potential Maps

Generals

Normally, the maps are an optional aside. The most information is still in the time series view. And this view usually fills the whole page - no space is left to include map objects. Mainly to solve this problem, xavr supports multiple pages. You add pages via File - Open, where you must load a configuration file. You toggle between the different pages via the Window menu or with [Shift]+Ctrl+Tab.

Spatial Information

The .dat file may contain valid sensor positions for channels whose data are not available or not sufficient for generating potential maps. You have to remove these channels from the .dat file or your maps will become ugly! (i.e. bipolar EOG channels, shorted reserve channels...)

It is possible to request additional control points where the amplitude data come from a spheric spline interpolation. This results in smoother contours but costs some computation time. The number of points controls the map interpolation as follows (n is the number you enter and n_dat is the number of valid sensor positions in the .dat file):

n = 0

no interpolation at all, a value of -1e30 is assigned if no ERP channel is available for an sensor in the .dat file(this is the default)

0 < n <= n_dat

no additional control points, interpolation for sensor positions with missed ERP channels

n_dat < n

insert additional control points, need interpolation always

Map Sequence

Algorithm of Potential Map Generation

1. The sensor coordinates - measured at a real head surface - are projected to an unit sphere surface.
2. The sensor coordinates at the unit sphere surface are unwrapped into the plane.
3. If requested, additional control points are inserted in the plane.
4. The area spanned by the control points in the plane (the smallest convex polygon covering all points) is decomposed into a set of non-overlapping triangles where all control points are triangle corners and vice versa (triangle mesh).
5. A potential value is assigned to each control point in the triangle mesh. For all points without an assigned data channel, the potential values are interpolated. This results into the potential relief.
6. The potential relief is intersected with horizontal planes at certain voltage levels. Each intersection of one triangle in space with one horizontal plane results in exact one straight intersection line. The intersection lines of all triangles at one voltage level form the "isopotential polygons" for this voltage level.
7. The map you finally see is composed by the filled isopotential polygons (one color for each level) and - optionally - the outlines of the polygons(isopotential lines).

Interact with the Drawing

Zoom/Scroll

Button 1 pans the drawing - imagine you grab the sheet clicking onto it and move it below a frame. Keyboard scrolling is possible with cursor keys, Home, End, PageUp, PageDown.

Format

• move an object within the page by pressing Ctrl-Button1 onto it and moving the frame.
• move object groups. Select multiple objects with Shift-Button1, move by pressing Button1 onto one selected object and moving the object group frame.
• delete objects via context menu, Delete key or Edit - Delete Object(s) menu button.
• draw arrows and text directly into the page via the Edit - Create... menu buttons.
• edit text object attributes via the Edit.. button from the context menu
• in preparation to a black/white plot, set all signal trace colors to black and the potential map palette to "gray" using the Options - Black/White menu button. (xavr automatically assigns different dash patterns to signal traces with the same color.)
• assign new colors to signal traces. Click at the small sample line in the legend dialog and select a color from the menu that pops up. The Other... button allows to set the linewidth and the dash pattern too. The new parameters are assigned to the selected legend slot, not to a specific avr file. You get rid of these settings with the Options - Discard Trace Styles menu button.

Inspect

PostScript Plot

There are some prepared print and preview commands available(configurable via resource file). Note that not each of this commands works at each machine. Note also that xavr is blocked until the shell subprocess terminates.

A special print command is avrps. This is a shell script which is intended to generate an A4 landscape PostScript screen preview at each machine. This script is also used as the File - Print Preview menu command.

The Current View option in the dialog allows to print the current content of the xavr window, scaled to fit in the output media. This option is useful if you need a selected piece of the drawing as enlarged plot or as EPS illustration for later use - just zoom/move/resize your window to show the desired area and send it out.