Table of Contents
topo - display the topography of ERP data within the outlines of heads.
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]
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.
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.
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.
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
topofiles(5)
, avg(1)
, avg_manual(7)
, erp_overview(7)
, gmt(3)
,
gmtdefaults(3)
, spp4 source code (/usr/local/erp/src/spp4).
Paul
Krewski, Eric Boerner
Table of Contents