% 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}
% 'contourvals' - values for contour {default: same as input values}
% 'pmask' - values for masking topoplot. Array of zeros and 1 of the same size as the input
% value array {default: []}
% '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
