TOPOPLOT	Plot a topographic map of a scalp data field in a 2-D circular view (looking down at the top of the head) using interpolation on a fine cartesian grid. Can also show specified channnel location(s), or return an interpolated value at an arbitrary scalp location (see 'noplot'). By default, channel locations below head center (arc_length 0.5) are shown in a 'skirt' outside the cartoon head (see 'plotrad' and 'headrad' options below). Nose is at top of plot; left is left; right is right. Using option 'plotgrid', the plot may be one or more rectangular grids.
Usage:	>> topoplot(datavector, EEG.chanlocs); % plot a map using an EEG chanlocs structure >> topoplot(datavector, 'my_chan.locs'); % read a channel locations file and plot a map >> topoplot('example'); % give an example of an electrode location file >> [h grid_or_val plotrad_or_grid, xmesh, ymesh]= topoplot(datavector, chan_locs, 'Input1','Value1', ...);
Required Inputs:
datavector	single vector of channel values. Else, if a vector of selected subset (int) channel numbers -> mark their location(s) using 'style' 'blank'.
chan_locs	name of an EEG electrode position file (>> topoplot example). Else, an EEG.chanlocs structure (>> help readlocs or >> topoplot example)
Optional inputs:
'maplimits'	'absmax' -> scale map colors to +/- the absolute-max (makes green 0); 'maxmin' -> scale colors to the data range (makes green mid-range); [lo.hi] -> use user-definined lo/hi limits {default: 'absmax'}
'style'	'map' -> plot colored map only 'contour' -> plot contour lines only 'both' -> plot both colored map and contour lines 'fill' -> plot constant color between contour lines 'blank' -> plot electrode locations only {default: 'both'}
'electrodes'	'on','off','labels','numbers','ptslabels','ptsnumbers'. To set the 'pts' marker,,see 'Plot detail options' below. {default: 'on' -> mark electrode locations with points ('.') unless more than 64 channels, then 'off'}.
'plotchans'	[vector] channel numbers (indices) to use in making the head plot. {default: [] -> plot all chans}
'chantype'	cell array of channel type(s) to plot. Will also accept a single quoted string type. Channel type for channel k is field EEG.chanlocs(k).type. If present, overrides 'plotchans' and also 'chaninfo' with field 'chantype'. Ex. 'EEG' or {'EEG','EOG'} {default: all, or 'plotchans' arg}
'plotgrid'	[channels] Plot channel data in one or more rectangular grids, as specified by [channels], a position matrix of channel numbers defining the topographic locations of the channels in the grid. Zero values are given the figure background color; negative integers, the color of the polarity-reversed channel values. Ex: >> figure; ... >> topoplot(values,'chanlocs','plotgrid',[11 12 0; 13 14 15]); % Plot a (2,3) grid of data values from channels 11-15 with one empty grid cell (top right) {default: no grid plot}
'nosedir'	['+X'|'-X'|'+Y'|'-Y'] direction of nose {default: '+X'}
'chaninfo'	[struct] optional structure containing fields 'nosedir', 'plotrad' and/or 'chantype'. See these (separate) field definitions above, below. {default: nosedir +X, plotrad 0.5, all channels}
'plotrad'	[0.15<=float<=1.0] plotting radius = max channel arc_length to plot. See >> topoplot example. If plotrad > 0.5, chans with arc_length > 0.5 (i.e. below ears-eyes) are plotted in a circular 'skirt' outside the cartoon head. See 'intrad' below. {default: max(max(chanlocs.radius),0.5); If the chanlocs structure includes a field chanlocs.plotrad, its value is used by default}.
'headrad'	[0.15<=float<=1.0] drawing radius (arc_length) for the cartoon head.
NOTE:	Only headrad = 0.5 is anatomically correct! 0 -> don't draw head; 'rim' -> show cartoon head at outer edge of the plot {default: 0.5}
'intrad'	[0.15<=float<=1.0] radius of the scalp map interpolation area (square or disk, see 'intsquare' below). Interpolate electrodes in this area and use this limit to define boundaries of the scalp map interpolated data matrix {default: max channel location radius}
'intsquare'	['on'|'off'] 'on' -> Interpolate values at electrodes located in the whole square containing the (radius intrad) interpolation disk; 'off' -> Interpolate values from electrodes shown in the interpolation disk only {default: 'on'}.
'conv'	['on'|'off'] Show map interpolation only out to the convext hull of the electrode locations to minimize extrapolation. {default: 'off'}
'noplot'	['on'|'off'|[rad theta]] do not plot (but return interpolated data). Else, if [rad theta] are coordinates of a (possibly missing) channel, returns interpolated value for channel location. For more info, see >> topoplot 'example' {default: 'off'}
'verbose'	['on'|'off'] comment on operations on command line {default: 'on'}.
Plot detail options:
'drawaxis'	['on'|'off'] draw axis on the top left corner.
'emarker'	Matlab marker char | {markerchar color size linewidth} char, else cell array specifying the electrode 'pts' marker. Ex: {'s','r',32,1} -> 32-point solid red square. {default: {'.','k',[],1} where marker size ([]) depends on the number of channels plotted}.
'emarker2'	{markchans}|{markchans marker color size linewidth} cell array specifying an alternate marker for specified 'plotchans'. Ex: {[3 17],'s','g'} {default: none, or if {markchans} only are specified, then {markchans,'o','r',10,1}}
'hcolor'	color of the cartoon head. Use 'hcolor','none' to plot no head. {default: 'k' = black}
'shading'	'flat','interp' {default: 'flat'}
'numcontour'	number of contour lines {default: 6}
'color'	color of the contours {default: dark grey} 'whitebk ' - ('on'|'off') make the background color white (e.g., to print empty plotgrid channels) {default: 'off'}
'gridscale'	[int > 32] size (nrows) of interpolated scalp map data matrix {default: 67}
'colormap'	(n,3) any size colormap {default: existing colormap}
'circgrid'	[int > 100] number of elements (angles) in head and border circles {201}
Dipole plotting options:
'dipole'	[xi yi xe ye ze] plot dipole on the top of the scalp map from coordinate (xi,yi) to coordinates (xe,ye,ze) (dipole head model has radius 1). If several rows, plot one dipole per row. Coordinates returned by dipplot() may be used. Can accept an EEG.dipfit.model structure (See >> help dipplot). Ex: ,'dipole',EEG.dipfit.model(17) % Plot dipole(s) for comp. 17.
'dipnorm'	['on'|'off'] normalize dipole length {default: 'on'}.
'diporient'	[-1|1] invert dipole orientation {default: 1}.
'diplen'	[real] scale dipole length {default: 1}.
'dipscale'	[real] scale dipole size {default: 1}.
'dipsphere'	[real] size of the dipole sphere. {default: 85 mm}.
'dipcolor'	[color] dipole color as Matlab code code or [r g b] vector {default: 'k' = black}.
Outputs:
h	plot axes handle
grid_or_val	[matrix] the interpolated data image (with off-head points = NaN). Else, single interpolated value at the specified 'noplot' arg channel location ([rad theta]), if any.
plotrad_or_grid	IF grid image returned above, then the 'plotrad' radius of the grid. Else, the grid image xmesh, ymesh - x and y values of the returned grid (above)
Chan_locs format:	See >> topoplot 'example'
Examples:
To plot channel locations only:	>> figure; topoplot([],EEG.chanlocs,'style','blank','electrodes','labelpoint','chaninfo',EEG.chaninfo);
Notes:	- To change the plot map masking ring to a new figure background color, >> set(findobj(gca,'type','patch'),'facecolor',get(gcf,'color')) - Topoplots may be rotated. From the commandline >> view([deg 90]) {default: [0 90])
Authors:	Andy Spydell, Colin Humphries, Arnaud Delorme & Scott Makeig CNL / Salk Institute, 8/1996-/10/2001; SCCN/INC/UCSD, Nov. 2001 -
See also:	timtopo, envtopo

See the matlab file topoplot.m (may require other functions)

Back to functions