plot a topographic map of ERP

Share:

Description

Plot a topographic map of an ERP on a specific timepoint or averaging the ERP in a time window. The head is represented as a circle.

Usage

1
2
3
4
5
6
7
topoplot(erpobj, startmsec=-200, endmsec=1200, win.ini, win.end, exclude = NULL,
elec.coord=NULL, projection="orthographic", palette.col="jet", palette.steps=10, 
return.coord = FALSE, zlim=NULL, interpolation = "cubicspline", extrap = TRUE, 
interp.points = 500, return.notfound=FALSE, mask = TRUE,  contour=TRUE, x.rev=FALSE,
draw.elec.pos=TRUE,  elec.pos.toplot="all", elec.pos.pch=19, elec.pos.cex=1, 
draw.nose=FALSE, draw.elec.lab=TRUE, elec.lab.adj=c(0.5, NA), elec.lab.cex=1, 
elec.lab.toplot=elec.pos.toplot, head.col="black", head.lwd=1, ...)

Arguments

erpobj

an ERP dataframe with electrodes in columns and timepoints in rows.

startmsec

start time (in ms) of the ERP data frame. It can be a negative value, indicating the baseline time frame.

endmsec

end time (in ms) of the ERP data frame.

win.ini

the initial edge (in ms) of the window on which the topographic map has to be plotted.

win.end

the final edge (in ms) of the window on which the topographic map has to be plotted. If equal to win.ini, then the map of a single time point is plotted.

exclude

a vector of characters indicating the channel names that are excluded from the plotting

elec.coord

an optional data frame with electrode coordinates (see Note).

projection

the type of electrode projection from 3d to 2d. Two methods available are "orthographic" and "equalarea".

palette.col

the color palette. Two default palettes are available: "jet" or "heat". Otherwise a customized palette can be created. A palette will be built as an interpolation trough the vector of colors provided.

palette.steps

the number of steps in the color palette.

return.coord

if TRUE, the function doesn't create a topoplot, but returns a data frame containing all the built-in electrode coordinates.

zlim

the limits of z axis (i.e. colors in the topographic map). If NULL, then the limits are automatically computed.

interpolation

The interpolation between electrodes. Two methods from package akima are available: "linear" and "cubicspline".

extrap

logical. Extrapolate the data outside the convex hull also. This parameter is ignored if interpolation method is "linear".

interp.points

the number of points to be used for interpolation. This parameter defines the smoothness of the plot.

return.notfound

logical. If TRUE, the function doesn't create a topoplot, but returns a vector with the electrode names in erpobj not contained in the supplied list of electrodes.

mask

logical. Should a circular mask around topographic map be drawn?

contour

logical. Should contour lines be drawn?

x.rev

logical. Should the x axis be reversed?

draw.elec.pos

logical. Should the black points be drawn in correspondence with electrode positions?

elec.pos.toplot

the electrode positions to plot, with a symbol specified in elec.pos.pch. Default is "all" and all electrode positions will be plotted.

elec.pos.pch

the symbol type for electrode position. Default is 19 and electrode positions are plotted as black dots.

elec.pos.cex

The magnification to be used for the electrode position symbols

draw.nose

logical. Should a nose be drawn to indicate upper side of the mask?

draw.elec.lab

logical. Should electrode labels be drawn?

elec.lab.adj

a vector with a pair of values indicating horizontal and vertical adjustment of electrode labels (see text).

elec.lab.cex

The magnification to be used for the electrode labels.

elec.lab.toplot

the electrode labels to plot. As default, the labels for the electrodes specified with the argument elec.pos.toplot are plotted.

head.col

line color of head and nose.

head.lwd

line width of head and nose.

...

further parameters to be passed to image.

Value

The topographic map is plotted. The function also returns a list of values that can be used by other functions. The first item of the list is a pair of values indicating the zlim of the plot. The second item of the list is a vector indicating the palette created by the function (palette). This last vector with palette colors can be used by the topoplot.palette function.

Note

The topographic plots are created according the following steps. 1) The electrodes are projected from 3d space to 2d space. 2) Voltage values are interpolated (and extrapolated, if extrap=TRUE) on 2d space (the interpolation methods come from the nterp function of akima package). The spline interpolation is NOT a spherical spline interpolation.
The function already contains a built-in list of electrode coordinates, but some names may not be the same in the supplied data frame and in the built-in list (even if the case is ignored in the match). An optional object with electrode coordinates can be supplied. This object should be a data frame containing these four columns: a column labeled "el.name" with electrode names, three columns labeled "x", "y", "z" with spherical coordinates of the electrode.
Type topoplot(return.coord=TRUE) to see the data frame structure.
In the "orthographic" projection only "x" and "y" of electrode coordinates are mantained. The "equalarea" projection keeps in the 2d projection the area proprortions as in 3d representation. The topoplot function uses the function interp of package akima, that is released under a non-commercial use license.

Author(s)

Giorgio Arcara

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
if(require(akima)){

data(ERPsets)

word=grandaverage("Exp1_word_subj", 1:20, erplist=ERPsets)

# check if some electrodes are not present in the list 
# and create an object with these electrode names.

notfound=topoplot(word, return.notfound=TRUE)

#make a topoplot excluding not found electrode
topoplot(word, startmsec=-200, endmsec=1500, win.ini=400,
win.end=600, exclude=notfound)
}

Want to suggest features or report bugs for rdrr.io? Use the GitHub issue tracker.