# topoplot: plot a topographic map of ERP In erpR: Event-Related Potentials (ERP) Analysis, Graphics and Utility Functions

## 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 8 9 10 11 12``` ```topoplot(erpobj, startmsec = -200, endmsec = 1200, win.ini, win.end, exclude = NULL, elec.coord = NULL, projection = "orthographic", palette.col = "jet", palette.steps = 50, return.coord = FALSE, zlim = NULL, interpolation = "cubicspline", extrap = TRUE, interp.points = 100, 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.ears = 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 names of the electrodes 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.ears` logical. Should ears be drawn? (just aesthetic) `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.

Giorgio Arcara

## Examples

 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18``` ```## Not run: 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) } ## End(Not run) ```

erpR documentation built on Nov. 17, 2017, 2:11 p.m.