Table of Contents

Name

topofiles - input files to the ERP topo program

Description

This document describes the content and format of input files associated with the topo program, namely: - the command file
- the ascii data file
- the electrode specification file


Each of these files is described in its own section below.

the Command File

The command file is a text file capable of completely specifying the plot to be generated by topo (see the topo(1) man page, cmdfile run type). It is divided into sections of different types, with each section beginning with one of the following keywords: options, head, label, line, arrow, or legend. A section consists of all lines following a keyword, up until the next keyword (or end-of-file). White space (spaces, tabs, and empty lines) and lines beginning with the # character are ignored.

The options keyword indicates the start of a section used to specify command line options, one per line. This section need not be present, but if it is, must be the first section in the file.

The other keywords (head, label, line, arrow, legend) indicate the start of sections that describe objects to be plotted. These sections are also optional, and can appear in any order and number after the options section. They contain commands, one per line, that describe the object indicated by the keyword. Some commands are required to be present for an object, while others will have a default value applied for them if they are not present. Commands that are required are noted as such in their description below.

A working command file can be automatically generated by the topo program itself, using the avgfile run type with the -cmd option (see the topo(1) man page); the resulting command file can then be edited as desired.

The keywords and their sections are as follows:

options

The options section is meant for specifying any of the command line options that apply to the cmdfile run type (see the topo(1) man page). This section is optional, but if present must be present only once, and must be the first section in the file. Wnen an option is present both on the command line and here, the command line option takes precedence; when an option is present both here and as a command in one of the object sections that follow (possible only with a limited number of options), the value given here takes precedence. The following options are valid in this section, one per line, in any order (see the topo(1) man page for descriptions): 


-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

head

The head keyword introduces an object that is a topographic representation of the electric potentials present on the surface of the head at a specified moment (or moments) in time. It is described by the following commands:
location x y
(required) The location of the center of the sphere of the head, where x and y are given in inches from the bottom left corner of the page. For example,

location 4.25 5.5

positions a head in the center of a portrait-oriented 8.5" x 11" page.

avgfile filename
(either avgfile or asciifile is required) The name of the file containing the averaged ERP data. Note that either avgfile or asciifile must be given, but not both!
bin number
(required with avgfile, ignored with asciifile) The bin number (0,1,2,...) that contains the data of interest in the avgfile.
time time
(required with avgfile, ignored with asciifile) The latency (in msec) for the head. In other words, this is the amount of time after the event, at which the data to display were recorded.
asciifile filename
(either avgfile or asciifile is required) The name of an ascii text file to use, rather than an ERP average file, as the source of the data to be plotted. See the ASCII DATA FILE section of this man page for a description of this file. Note that either avgfile or asciifile must be given, but not both! Also note that ’eachbin’ normalization is not permitted when using an asciifile because there is no bin associated with ascii data.
cap captype | elec_spec_file
(required) The type of electrode cap used to collect the data being plotted; the cap types currently known by the program are 23chan and 26chan. Other caps types can be specified using an electrode specification file (see the ELECTRODE SPECIFICATION FILE section of this man page for a description of this file).
radius radius
(required) The radius (in inches) of the sphere of the head.
winwidth time
(ignored with asciifile) The time window (in msec) 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.
baseline start stop
(ignored with asciifile) This command 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. This command can be overridden by -baseline (or -nobaseline) in the options section, which in turn can be overridden by -baseline (or -nobaseline) on the command line.
nobaseline
(ignored with asciifile) This command 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. This command can be overridden by -baseline in the options section, which in turn can be overridden by -baseline (or -nobaseline) on the command line.
view top | front | back | left | right
The direction from which the head is viewed. The default is top.
elecdiam diameter
The diameter (in inches) of the electrodes that appear on the plot. The default is 0.04, unless either the -elecdata or -eleclabels command line option is specified, in which case the default is 0.15 (inches per character). This value can be overridden by -elecdiam in the options section, which in turn can be overridden by -elecdiam on the command line.
labeltext text
(if given, labellocation must also be given) The text to use for the head label. If it contains one or more spaces, it must be surrounded by double quotes, for example

labeltext "difference wave 500 ms"

labellocation x y
(required if labeltext is given, ignored otherwise) The location of the head label, where x and y are given in inches from the bottom left corner of the page. To specify the justification of the label, see labeljustify, below.
labelfont number
The font (0-33) to use for the head label. The default is 0 (Helvetica). See the gmtdefaults(3) man page for the list of fonts.
labelfontsize points
The font size (in points) for the head label. The default is 14.
labeljustify number
The justification to use for the head label, as follows: 1 = lower left
2 = lower center
3 = lower right
5 = mid left
6 = mid center
7 = mid right
9 = top left
10 = top center
11 = top right


The default is 6 (mid-center). (Note: These numbers follow the convention used by the GMT routine pstext(3) )

label

The label keyword introduces a simple text string object. It is described by the following commands:
text text
(required) The text to use for the label. If it contains one or more spaces, it must be surrounded by double quotes, for example

text "Simple Visual Target X"

location x y
(required) The location of the label, where x and y are given in inches from the bottom left corner of the page. To specify the justification of the label, see justify, below.
font number
The font (0-33) to use for the label. The default is 0 (Helvetica). See the gmtdefaults(3) man page for the list of fonts.
fontsize points
The font size (in points) for the label. The default is 14.
justify number
The justification to use for the label, as follows: 1 = lower left
2 = lower center
3 = lower right
5 = mid left
6 = mid center
7 = mid right
9 = top left
10 = top center
11 = top right


The default is 6 (mid-center). (Note: These numbers follow the convention used by the GMT routine pstext(3) )

line

The line keyword introduces a simple line object. It is described by the following commands:
location x1 y1 x2 y2
(required) The location of the endpoints of the line, where x1, y1, x2, and y2 are given in inches from the bottom left corner of the page.
width pixels
The width (in pixels) of the line. The default is 5. Note that differences in linewidths may not always be visible on screen output, but will be visible on hardcopy output.

arrow

The arrow keyword introduces a simple arrow object, which is a line with an arrow head at one end. It is described by the following commands:
location x1 y1 x2 y2
(required) The location of the endpoints of the line, where x1, y1, x2, and y2 are given in inches from the bottom left corner of the page. The arrowhead is drawn at x2, y2.
width pixels
The width (in pixels) of the lines used to draw the arrow. The default is 5. Note that differences in linewidths may not always be visible on screen output, but will be visible on hardcopy output.

legend

The legend keyword introduces a legend object that provides a scale for the topographic heads. It is described by the commands below.


If the normalization used is such that all heads share the same scale (as with allheads normalization, eachbin normalization when all heads are from the same bin, and eachhead normalization when there is only one head), then the scale numbers drawn on the legend reflect actual data values, and a legend label is automatically generated that displays the units (either uV or uA/m2). Otherwise, the scale numbers are given from -1.0 to 1.0 and a label is automatically generated beneath each head to indicate the maximum data value for the head (see topo’s -nomax option to prevent the generation of the labels beneath the heads).

location x1 y1
(required) The location of the center left of the legend, where x and y are given in inches from the bottom left corner of the page.
width width
The width (in inches) of the scale bar. The default is 0.2
height height
The height (in inches) of the scale bar. The default is 4.5
label1text text
The text to use for the first of two possible legend labels. If it contains one or more spaces, it must be surrounded by double quotes, for example

label1text "current source density"

Support for two labels is provided so the legend label can use two fonts, as required when printing ’microvolts’ using the symbol mu.

Normally this and the following legend commands are not specified in the command file, since the legend label is instead automatically generated by the program to indicate the appropriate scale units (i.e. uV or uA/m2). However, if the user wishes to create her own label for the legend, these commands can be used to do so. If label1text is specified in the command file, the legend label will not be automatically generated and these commands will be used to construct the legend label instead.

label1location x y
(required if label1text is given) The location of the label, where x and y are given in inches from the bottom left corner of the page. To specify the justification of the label, see label1justify, below.
label1font font
The font (0-33) to use for the label. The default is 0 (Helvetica). See the gmtdefaults(3) man page for the list of fonts.
label1fontsize points
The font size (in points) for the head label. The default is 14.
label1justify number
The justification to use for the label, as follows: 1 = lower left
2 = lower center
3 = lower right
5 = mid left
6 = mid center
7 = mid right
9 = top left
10 = top center
11 = top right


The default is 6 (mid-center). (Note: These numbers follow the convention used by the GMT routine pstext(3) )

label2text text
The text to use for the second of two possible legend labels. If it contains one or more spaces, it must be surrounded by double quotes, for example

label2text "current source density"

Support for two labels is provided so the legend label can use two fonts, as required when printing ’microvolts’ using the symbol mu.

label2location x y
(required if label1text is given) The location of the label, where x and y are given in inches from the bottom left corner of the page. To specify the justification of the label, see label2justify, below.
label2font font
The font (0-33) to use for the label. The default is 0 (Helvetica). See the gmtdefaults(3) man page for the list of fonts.
label2fontsize points
The font size (in points) for the head label. The default is 14.
label2justify number
The justification to use for the label, as follows: 1 = lower left
2 = lower center
3 = lower right
5 = mid left
6 = mid center
7 = mid right
9 = top left
10 = top center
11 = top right


The default is 6 (mid-center). (Note: These numbers follow the convention used by the GMT routine pstext(3) )

the Ascii Data File

The ascii data file is a text file that can be used instead of the ERP averaged data file as the source of the data to be plotted for a head object. It is specified in the command file using the asciifile command for the head object (see the COMMAND FILE section of this man page), and provides a method for plotting data that is not in the ERP format.

The file contains as many lines as there are channels of data, and each line has two parameters: a channel label (a simple text string); and a data value (in microvolts) for the channel. White space (spaces, tabs, and empty lines) and lines beginning with the # character are ignored.

The channel labels specified in this file must correspond with the electrode labels as they are specified for the captype or electrode specification file being used (see the cap command for the head object in the COMMAND FILE section of this man page, or the ELECTRODE SPECIFICATION FILE section of this man page). The channels need not be listed in the same order as the electrodes, but it is required that each electrode given in the electrode specifications have a counterpart with exactly the same label (case ignored) in this ascii data file.

For example, the following ascii data file would work with the 26chan cap type:

#
# topo ascii data file
# 26chan cap
# lrp experiment
# subject thomas muente
# right, nogo
# 100 msec
#
# label uvolt
# ----- --------
MiPf 0.0067
LLPf 0.2000
LLFr 0.1107
LLTe -0.0673
LLOc -0.0915
MiOc -0.0417
RLOc 0.1612
RLTe 0.2108
RLFr 0.1597
RLPf -0.1003
LMPf 0.2492
LDFr 0.2376
LDCe 0.1644
LDPa 0.0663
LMOc 0.0329
RMOc 0.1460
RDPa 0.2904
RDCe 0.2589
RDFr 0.1351
RMPf 0.1735
LMFr 0.3612
LMCe 0.2359
MiPa 0.2699
RMCe 0.3123
RMFr 0.3573
MiCe 0.2401

the Electrode Specification File

The electrode specification file is a text file that details the names and positions of electrodes used to collect data to be plotted by topo. It is declared with either the cap argument to the avgfile run type (see the topo(1) man page), or the cap command for the head object in the command file (see the COMMAND FILE section of this man page).

The file contains as many lines as there are electrodes (white space and lines beginning with the # character are ignored), with each line having exactly three parameters: the electrode label (a text string); the spherical coordinate phi (angle in degrees from z-axis); and the spherical coordinate theta (angle in degrees, in x-y plane, from x-axis). To visualize the spherical coordinates phi and theta, looking down on the top of a head with the nose pointing forward, phi is the angle measured by an arc drawn from the top center of the head to the electrode, and theta is the angle measured counterclockwise around the perimeter of the head, from the right ear to the electrode.

The electrode labels specified in this file must correspond with the channel labels specified in the data file (for avg files see the headinfo man page, for ascii files see the ASCII DATA FILE section of this man page). It is required that each electrode given in this file have a counterpart with exactly the same label (case ignored) in the data file.

Topo knows the electrode specifications for the commonly used caps; for these an electrode specification file is not necessary, the file is needed when data were collected with an electrode cap unknown to topo. It will also have to be used when the data were collected with a known cap, yet the channel labels in the data file are different from the standard electrode labels assumed for the cap (see below); the course of action in this case is to use the values below to create an electrode specification file for the cap, then edit the labels in this file to match the channel labels as found in the data file.

The following are electrode specification files for the cap types currently known to topo:

23chan
#
# topo electrode specification file
# 23 channel cap
#
# looking down on the top of a head with the nose
# pointing forward:
# phi - is the angle measured by an arc drawn from
# the top center of the head to the electrode
# theta - is the angle measured counterclockwise around
# the perimeter of the head, from the right ear
# to the electrode
#
# label phi theta
# ----- --- -----
Fpz 90.0 90.0
Fp1 90.0 108.0
Fp2 90.0 72.0
F7 90.0 144.0
F3 62.0 123.0
Fz 45.0 90.0
F4 62.0 57.0
F8 90.0 36.0
A1 118.0 180.0
T3 90.0 180.0
C3 45.0 180.0
Cz 0.0 0.0
C4 45.0 0.0
T4 90.0 0.0
T5 90.0 216.0
P3 62.0 237.0
Pz 45.0 270.0
P4 62.0 303.0
T6 90.0 324.0
O1 90.0 252.0
Oz 90.0 270.0
O2 90.0 288.0
A2 118.0 0.0

26chan
#
# topo electrode specification file
# 26 channel cap
#
# looking down on the top of a head with the nose
# pointing forward:
# phi - is the angle measured by an arc drawn from
# the top center of the head to the electrode
# theta - is the angle measured counterclockwise around
# the perimeter of the head, from the right ear
# to the electrode
#
# label phi theta
# ----- ---- ------
MiPf 90.0 90.0
LLPf 90.0 126.0
LLFr 90.0 162.0
LLTe 90.0 198.0
LLOc 90.0 234.0
MiOc 90.0 270.0
RLOc 90.0 306.0
RLTe 90.0 342.0
RLFr 90.0 18.0
RLPf 90.0 54.0
LMPf 59.0 108.0
LDFr 59.0 144.0
LDCe 59.0 180.0
LDPa 59.0 216.0
LMOc 59.0 252.0
RMOc 59.0 288.0
RDPa 59.0 324.0
RDCe 59.0 0.0
RDFr 59.0 36.0
RMPf 59.0 72.0
LMFr 26.0 126.0
LMCe 26.0 198.0
MiPa 26.0 270.0
RMCe 26.0 342.0
RMFr 26.0 54.0
MiCe 0.0 0.0

64chan
#
# topo electrode specification file
# 64 channel cap
#
# looking down on the top of a head with the nose
# pointing forward:
# phi - is the angle measured by an arc drawn from
# the top center of the head to the electrode
# theta - is the angle measured counterclockwise around
# the perimeter of the head, from the right ear
# to the electrode
#
# label phi theta
# ----- ---- ------
LOPf 90.0 114.0
ROPf 90.0 66.0
LMPf 66.8 102.0
RMPf 66.8 78.0
LTPf 90.0 138.0
RTPf 90.0 42.0
LLPf 77.1 126.0
RLPf 77.1 54.0
LPrA 111.3 174.0
RPrA 111.3 366.0
LTFr 90.0 162.0
RTFr 90.0 18.0
LLFr 66.8 150.0
RLFr 66.8 30.0
LDPf 51.4 126.0
RDPf 51.4 54.0
LTOc 133.6 210.0
RTOc 133.6 330.0
LTCe 90.0 186.0
RTCe 90.0 354.0
LLCe 66.8 174.0
RLCe 66.8 366.0
LDFr 44.5 162.0
RDFr 44.5 18.0
LMFr 25.7 126.0
RMFr 25.7 54.0
MiFo 90.0 90.0
MiPf 44.5 90.0
MiFr 0.0 0.0
A2 111.3 330.0
LHEy 111.3 150.0
RHEy 111.3 30.0
LIOc 133.6 234.0
RIOc 133.6 306.0
LLOc 111.3 222.0
RLOc 111.3 318.0
LLPP 90.0 210.0
RLPP 90.0 330.0
LLPa 77.1 198.0
RLPa 77.1 342.0
LDCe 51.4 198.0
RDCe 51.4 342.0
LMCe 25.7 198.0
RMCe 25.7 342.0
LDOc 111.3 246.0
RDOc 111.3 294.0
LDPP 90.0 234.0
RDPP 90.0 306.0
LDPa 66.8 222.0
RDPa 66.8 318.0
LCer 133.6 258.0
RCer 133.6 282.0
LMOc 90.0 258.0
RMOc 90.0 282.0
LMPP 66.8 246.0
RMPP 66.8 294.0
LMPa 44.5 234.0
RMPa 44.5 306.0
MiCe 25.7 270.0
MiPa 51.4 270.0
MiPP 77.1 270.0
MiOc 111.3 270.0
LLEy 133.6 126.0
RLEy 133.6 42.0

See Also

topo(1) , gmtdefaults(3) , pstext(3) , headinfo(1) , erp_overview(7)

Author

Paul Krewski

Table of Contents