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

Description Usage Arguments Value Note Author(s) Examples

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.

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, nose.lwd=NULL, ears.lwd=NULL, 
                 head.radius=1, ampl.radius=1, ...)

`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.
`nose.lwd`	line width of nose. (if not specified `head.lwd` will be used)
`ears.lwd`	line width of ears. (if not specified `head.lwd` will be used)
`head.radius`	the radius of the circle depicting the head (default is 1).
`ampl.radius`	the radius of the circle depicting the amplitude values (default is 1). Note that in some cases the electrodes could be outside the head radius and values higher than 1 may be necessary.
`...`	further parameters to be passed to `image`.

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.

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

## Not run: 
if(require(akima)){

data(erplistExample)

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

# 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)