Table of Contents

Name

topo - display the topography of ERP data within the outlines of heads.

Synopsis

topo avgfile bin cap [options1] [options2], or

topo cmdfile [options2]

where [options1] are: [-hfont <number>] [-hfontsize <points>]
[-interval <time>] [-ncols <ncols>] [-nheads <nheads>]
[-nrows <nrows>] [-rlegend] [-start <time>] [-tfont <number>]
[-tfontsize <points>] [-times <t1> [<t2> [<t3>...]]]
[-title <title>] [-view <top|front|back|left|right|all>]
[-winwidth <time>]

and [options2] are: [-baseline <start> <stop> | -nobaseline ]
[-ccontour] [-cmd <cmdfile>] [-csd] [-elecdata]
[-elecdiam <diameter>] [-eleclabels] [-facecolor <r g b>]
[-faceline <npixels>] [-grid] [-hres] [-lambert]
[-landscape] [-mono | -monoinv] [-nocontour] [-nodata]
[-nodel] [-nomax] [-norm <eachhead|eachbin|allheads>]
[-nshades <nshades>] [-ps <psfile>] [-run <runfile>]
[-scale <min> <max>] [-verbose] [-weighted]

Description

Topo was written as a front-end to underlying ERP (Event Related Potential) routines, spp4 (spherical spline interpolation) routines, and GMT (Generic Mapping Tools) routines, for the purpose of generating and invoking the appropriate calls to these routines to produce a postscript file that depicts the topography of ERP data within the outlines of heads.

Topo can generate topographic maps that represent either a) the electric potential, in microvolts (uV), across the scalp, or b) current source density, in microamps per meter squared (uA/m2), across the scalp. The topography is determined using spherical spline interpolation as presented in Perrin et al. 1989 and Perrin et al. 1990 (the 1990 paper corrects typographic errors in the 1989 paper).

There are two ways to run topo:

1) The avgfile (average file) run type uses typical defaults to plot a series of heads that depict the data, and requires three arguments:

avgfile, the ERP averaged data file
bin, the bin number of interest (i.e. 0,1,2,...)
cap, the type of electrode cap used, or an electrode specification file

Valid choices for cap are 23chan, 26chan, 64chan, or the name of an electrode specification file that describes the electrode locations over the sphere of the head. The format of the electrode specification file is described in the topofiles(5) man page, along with example specifications for the known cap types.

2) The cmdfile (command file) run type reads a complete description of the data and heads to plot from a file, and requires

the single argument

cmdfile

which is the name of a file that contains commands specifying the data files and the placement and appearance of the heads. A working command file can be automatically generated by the topo program itself, using the avgfile run type with the -cmd option; the resulting command file can then be edited as desired. The format of this file is described in the topofiles(5) man page.

It is possible to supply data in ascii text format to topo; this is done by invoking topo with a command file that indicates ascii data is to be used. For more information on this, see the ascii data file section of the topofiles(5) man page.

You must have write permission in the current directory to successfully run topo.

Options1 (avgfile Run Type):

The following options apply only to the avgfile run type; they are ignored if used with the cmdfile run type. If the functionality of these options is needed with the cmdfile run type, it must be specified using the commands in the various object sections of the cmdfile (see topofiles(5) ).

-hfont number
The font (0-33) to use for the labels below the heads. The default is 0 (Helvetica). See the gmtdefaults(3) man page for the list of fonts.

-hfontsize points
The font size (in points) for the labels below the heads. The default is 14.

-interval time
The time interval (in ms) to use between latencies for the heads. The default is 100. This option is ignored if the "-times" option is given.

-ncols ncols
The number of columns of heads. The default is the best fit.

-nheads nheads
The number of heads to plot. The default is 6. This option is ignored if the "-times" option is given.

-nrows nrows
The number of rows of heads. The default is the best fit.

-rlegend
Display the legend on the right. The default is to display the legend on the left.

-tfont number
The font (0-33) to use for the title. The default is 1 (Helvetica-Bold). See the gmtdefaults(3) man page for the list of fonts.

-tfontsize points
The font size (in points) for the title. The default is 20.

-times t1 t2 t3 ...
The latencies (in ms) at which to produce the heads. If this option is given, the options "-interval", "-nheads", and "-start" will be ignored.

-title title
The title to appear at the top of the page. The default is the name of the average file and the bin number.

-start time
The latency (in ms) for the first head. The default is 0. This option is ignored if the "-times" option is given.

-view [top | front | left | right | back | all]
The direction from which the heads are viewed. The default is top. If all is selected, the five views of the head will be generated for the latency specified by -start (and the options "-interval", "-ncols", "-nrows", "-times", and "-nheads" will be ignored).

-winwidth time
The time window (in ms) around the latency, over which to average. All data points that have their times within this window will be averaged together. The default is 0.

Options2 (both Run Types):

The following options apply to both the avgfile and cmdfile run types. These options can also be specified in the options section of the cmdfile; when an option is present on both the command line and in the command file, the command line option takes precedence (see topofiles(5) ).

-baseline start stop
This option is used to alter the interval used to calculate the baseline voltage which is subtracted from every point in the data prior to mapping. start and stop are decimal integers which denote the beginning and ending latencies (in ms) of the portion of data which are to be averaged together to form the baseline voltage (note, for those curious about the exact calculation, the data point corresponding to the stop latency is excluded from the baseline average). They are relative to stimulus onset, so if one wanted to use the 50 ms prior to stimulus onset as the baseline interval, one would type "baseline -50 0". If no interval is specified, the default is to baseline using the presampling period to calculate the baseline voltage.

-nobaseline
This option specifies to not subtract a baseline voltage from the data prior to mapping. The default is to baseline using the presampling period to calculate the baseline voltage.

-ccontour
Draw contour lines in color. The default is to draw contour lines in black.

-cmd cmdfile
Create the command file cmdfile that would reproduce the plot generated by the current invocation of the program. The default is to not create a command file. The format of the command file is described in the topofiles(5) man page.

-csd
Plot current source density. The default is to plot potentials.

-elecdata
Instead of plotting electrode symbols, plot actual data values at the electrodes. Use -elecdiam to adjust the size of the text. The font used is -hfont. Text is centered over the electrode site, which may result in text falling outside the head boundary for some electrodes; if this is not acceptable, text positioning can be adjusted by hand by editing the output postscript file (search for the text of interest, and adjust the x,y values at the start of the line). The default is to plot circles for the electrodes.

-elecdiam diameter
The diameter (in inches) of the electrodes that appear on the plot, unless either the -elecdata or -eleclabels option is specified, in which case this refers to the diameter (in inches) of one text character. The default is 0.04, unless either the -elecdata or -eleclabels option is specified, in which case the default is 0.15.

-eleclabels
Instead of plotting electrode symbols, plot channel labels at the electrodes. Use -elecdiam to adjust the size of the text. The font used is -hfont. Text is centered over the electrode site, which may result in text falling outside the head boundary for some electrodes; if this is not acceptable, text positioning can be adjusted by hand by editing the output postscript file (search for the text of interest, and adjust the x,y values at the start of the line). The default is to plot circles for the electrodes.

-facecolor r g b
Plot the face outline using a color as specified by the red, green, and blue values r g b. These values can range from 0 0 0 (black) to 255 255 255 (white). For grey, keep the value the same for each of r g b (i.e. 64 64 64); full red is 255 0 0; etc. The default is 0 0 0 (black).

-faceline npixels
Plot the face outline using a linewidth of npixels pixels. The default is 1.

-grid
Superimpose a coordinate grid over the plot, to help in positioning objects. The default is to not display a grid.

-hres
Draw the contours using high resolution, to reduce the jagged effect between the contour levels. The postscript file will be significantly larger, and take significantly longer to generate and print, so this option should probably only be used when producing final figures. The default is to not use high resolution.

-lambert
Use a Lambert Azimuthal Equal-Area projection, which is not a true perspective, but areas are correct. The default is to use an Orthographic azimuthal projection, which is a true perspective projection viewed from infinite distance, giving the appearance of a globe viewed from space.

-landscape
Produce output in landscape orientation. The default is portrait.

-mono
Use a monochrome scale, with black positive and white negative. The default is to use a color scale, with red positive and blue negative. Only one of -mono and -monoinv is recognized.

-monoinv
Use an inverted monochrome scale, with white positive and black negative. The default is to use a color scale, with red positive and blue negative. Only one of -mono and -monoinv is recognized.

-nocontour
Don’t draw contour lines on the heads. The default is to draw contour lines.

-nodata
Don’t read/interpolate/display the data. This saves much computation time, and can be used for previewing plots that are ’in progress’. The default is to display the data.

-nodel
Don’t delete the temporary files that are created. The default is to delete them.

-nomax
Don’t display the ’(max 6.44uV)’ labels that are automatically generated beneath the heads for the types of normalization that prevent all heads from using the same scale. The default is to display these labels.

-norm [eachbin | eachhead | allheads]
The type of normalization to use. Eachbin normalization will divide the data points for all heads in the same bin by the maximum absolute value data point for the heads in the same bin. Eachhead normalization will divide the data points for each head by the maximum absolute value data point for each head. Allheads normalization will divide the data points for all heads by the maximum absolute value data point for all heads. The default normalization is eachbin.

-nshades nshades
The number of shades to use in the palette. The default is 20.

-ps psfile
The name of the postscript file to produce. The default is a filename of the construction topo.*.ps, where * is the base name of either the average file or command file (depending on the runtype).

-run runfile
Generate a file called runfile that contains all the system commands executed by the program. Most of these commands operate on the temporary files that are created, so if the intent is to later invoke these commands, this option should be used in conjunction with the -nodel option.

-scale min max
Use min and max as the lower and upper bounds for the scale of the topographic heads, e.g. -scale -0.29 2.00 . These will be the bounds displayed on the legend, and will override the default scale of the absolute value of the maximum data value being plotted. The units are assumed to be that for whichever is being plotted, potential or CSD. If not all the data being plotted lay within these bounds, then a warning is printed and the data that lay outside these bounds are not plotted.

This option is only valid when normalization for the heads is such that all heads on the plot share a common scale (i.e. when scale numbers are displayed on the legend to reflect actual data values); it is ignored otherwise.

-verbose
Produce verbose output. This option can be very helpful in diagnosing problems.

-weighted
Use weighted distance interpolation. The default is to use spherical splines interpolation. This option can not be used with the -csd option. For more information see the source code for the spp4 program.

Examples

The following are some basic examples. If you have problems, or the program just isn’t doing what you expect, use the -verbose option and examine the output; it will almost certainly indicate where things are failing. Check that the program is interpreting the arguments and options correctly; these are echoed at the start of the verbose output.


topo conaud.gnd 1 26chan -cmd conaud_bin1.cmd
This avgfile runtype invocation uses default values to generate
a plot of a typical series of heads in the file topo.conaud.ps for the data in bin 1 of the erp averaged data file conaud.gnd, recorded using the 26 channel cap. It also creates a command file called conaud_bin1.cmd that can be used to regenerate exactly the same plot.


topo conaud_bin1.cmd
This cmdfile runtype invocation uses the command file created in the
preceding example to generate a plot in the (default) file topo.conaud_bin1.ps. The resulting plot should be identical to the preceding example’s plot.


topo conaud.gnd 1 26chan -times 250 288 300 309 333
                       -ps conaud.times.ps
Produces a plot in conaud.times.ps for the data in bin 1 of conaud.gnd,
recorded using the 26 channel cap. The plot consists of 5 heads at the specified latencies.


topo conaud.gnd 0 26chan -view all -start 400 -hres
                       -ps conaud.viewall.ps
Generates a plot in conaud.viewall.ps for
the data in bin 0 of conaud.gnd, recorded using the 26 channel cap. The plot consists of the five views of the head at a latency of 400 ms, with contours drawn in high resolution.


topo conaud.gnd 1 26chan -interval 4 -nheads 35
                       -hfontsize 10 -elecdiam 0.02
                       -ps conaud.35heads.ps
Produces a plot in conaud.35heads.ps for the data in bin 1
of conaud.gnd, recorded using the 26 channel cap. The plot consists of 35 heads at latency intervals of 4 ms, and the head labels and electrode diameters are specified at a reduced size to accomodate the large number and small size of the heads on the plot.


topo conaud.gnd 0 26chan -elecdiam 0.10 -grid -hfont 8
                       -hfontsize 10 -interval 100 -ncols 4
                       -nheads 8 -rlegend -tfont 9 -tfontsize 30
                       -title "CONAUD.GND, BIN 0" -view front
                       -winwidth 50 -csd -facecolor 192 192 192
                       -faceline 5 -lambert -landscape -mono
                       -nocontour -norm eachhead -nshades 10
                       -ps conaud.options.ps
Produces a plot that serves to show some of the various parameters
that can be modified with the program options.


topo 21chan.cmd
Uses a command file, an electrode specification file, and an ascii data file
to produce a simple twenty-one channel one-head plot that obtains its electrode specifications from the file 21chan.ele and its data from the file 21chan.asc. The contents of these files are as follows:


21chan.cmd:
# 21chan.cmd
# topo command file
#
#
options
-ps 21chan.ps
head
location 4.75 5.95
radius 2.50
view front
asciifile 21chan.asc
cap 21chan.ele
labellocation 4.75 1.51
labeltext "300 ms"
label
location 4.25 10.25
font 1
fontsize 20
text "21 channel test data"
 
legend
location 0.75 5.36
height 4.50
width 0.20
21chan.ele:
# 21chan.ele
# topo electrode specification file
#
#  label  phi  theta
#  ----- ---- ------
    Fpz   90     90
    Fp1   90    108
    Fp2   90     72
    F7    90    144
    F3    62    123
    Fz    45     90
    F4    62     57
    F8    90     36
    T3    90    180
    C3    45    180
    Cz     0      0
    C4    45      0
    T4    90      0
    T5    90    216
    P3    62    237
    Pz    45    270
    P4    62    303
    T6    90    324
    O1    90    252
    Oz    90    270
    O2    90    288
21chan.asc:
# 21chan.asc
# topo ascii data file
# for use with electrode specification file 21chan.ele
# 
# subject Jane Doe
# 300 ms
#
# label   uvolt
# -----  --------
   Fpz     0.6
   Fp1     0.6
   Fp2     0.6
   F7      0.6
   F3     -0.2
   Fz     -0.2
   F4     -0.2
   F8      0.6
   T3      0.6
   C3     -0.2
   Cz     -0.8
   C4     -0.2
   T4      0.6
   T5      0.6
   P3     -0.2
   Pz     -0.2
   P4     -0.2
   T6      0.6
   O1      0.6
   Oz      0.6
   O2      0.6

See Also

topofiles(5) , avg(1) , avg_manual(7) , erp_overview(7) , gmt(3) , gmtdefaults(3) , spp4 source code (/usr/local/erp/src/spp4).

Author

Paul Krewski, Eric Boerner


Table of Contents