envtopo.m

来自「含有多种ICA算法的eeglab工具箱」· M 代码 · 共 1,112 行 · 第 1/3 页

% envtopo() - Plot the envelope of a data epoch plus envelopes and scalp maps of largest 
%             contributing or specified components. Click on individual topoplots to examine
%             separately (using axcopy()).
% Usage:
%            >> envtopo(data,weights);
%            >> [compvarorder,compvars,compframes,comptimes,compsplotted,pvaf] ...
%                                       = envtopo(data, weights, 'key1', val1, ...);
% Inputs:
%  data       = single data epoch (chans,frames)
%  weights    = ICA weight matrix (= weights*sphere)
%
% Optional inputs:
%  'chanlocs'  = [string] channel location file or EEG.chanlocs structure. 
%                  See >> topoplot example 
%  'limits'    = [minms maxms minuV maxuV] times values in ms, potential values in uV
%                  {def|[] or both t's 0 -> data uV limits}
%  'limcontrib' = [minms maxms]  time range (in ms) in which to rank component contribution
%                  {default|[]|[0 0] -> data limits}
%  'compnums'  = [integer array] vector of component numbers to plot {default|0 -> all}
%                  Else if n < 0, the number largest-comp. maps  to plot (component with max
%                  variance) {default|[] -> 7}
%  'title'     = [string] plot title {default|[] -> none}
%  'plotchans' = [integer array] data channels to use in computing contributions and envelopes 
%                  {default|[] -> all}
%  'voffsets'  = [float array] vertical line extentions above the data max to disentangle
%                  plot lines (left->right heads, values in y-axis units) {def|[] -> none}
%  'colors'    = [string] filename of file containing colors for envelopes, 3 chars
%                  per line, (. = blank). First color should be "w.." (white)
%                  Else, 'bold' -> plot default colors in thick lines.
%                  {default|[] -> standard Matlab color order}
%  'fillcomp'  = int_vector>0 -> fill the numbered component envelope(s) with 
%                  solid color. Ex: [1] or [1 5] {default|[]|0 -> no fill}
%  'vert'      = vector of times to plot vertical lines {default|[] -> none}
%  'icawinv'   = [float array] inverse weight matrix. By default computed by inverting
%                  the weight matrix (but if some components have been removed, then
%                  weight's pseudo-inverse matrix does not represent component's maps).
%  'icaact'    = [float array] ICA component activations. By default computed using the
%                  weight matrix.
%  'envmode'   = ['avg'|'rms'] compute the average envelope or the root mean square
%                  envelope {default: 'avg'}
%  'subcomps'  = [integer vector] indices of components to remove from data before 
%                  plotting.
%  'sumenv'    = ['on'|'off'|'fill'] 'fill' -> show the filled envelope of the summed projections 
%                  of the selected components; 'on' -> show the envelope only {default: 'fill'}
%  'actscale'  = ['on'|'off'] scale component scalp maps by maximum component activity in the
%                  designated (limcontrib) interval. 'off' -> scale scalp maps individually using
%                  +/-max(abs(map value)) {default: 'off'}
%  'dispmaps'  = ['on'|'off'] display component number and scalp maps. {default: 'on'}
%  'pvaf'      = ['on'|'off'] use percent variance accounted for (if 'on') or relative variance
%                  (if 'off') to select components contributing the most over the limcontrib 
%                  interval {default: 'on'}
%                    pvaf(component) = 100-100*variance(data-component))/variance(data)
%                    rv(component)   = 100*variance(component)/variance(data)
% Outputs:
%  compvarorder  = component numbers in decreasing order of max variance in data
%  compvars      = component max variances
%  compframes    = frames of max variance
%  comptimes     = times of max variance
%  compsplotted  = components plotted
%  pvaf/rv       = percent variance accounted for or relative variance (see 'pvaf' input)
%
% Notes:
%  To label maps with other than component numbers, put 4-char strings into
%  file 'envtopo.labels' (. = space) in time-order of their projection maxima
%
% Author: Scott Makeig & Arnaud Delorme, SCCN/INC/UCSD, La Jolla, 3/1998 
%
% See also: timtopo()

% Copyright (C) 3-10-98 from timtopo.m Scott Makeig, SCCN/INC/UCSD, [e-mail]
%
% This program is free software; you can redistribute it and/or modify
% it under the terms of the GNU General Public License as published by
% the Free Software Foundation; either version 2 of the License, or
% (at your option) any later version.
%
% This program is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU General Public License for more details.
%
% You should have received a copy of the GNU General Public License
% along with this program; if not, write to the Free Software
% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

% $Log: envtopo.m,v $
% Revision 1.61  2004/05/06 23:41:25  scott
% typo
%
% Revision 1.60  2004/05/04 05:35:25  scott
% finished debugging limits
%
% Revision 1.59  2004/05/04 05:24:10  scott
% debug setting g.limits(2) to ms
%
% Revision 1.58  2004/04/28 06:00:53  scott
% debug 'compnums',[2 3 4 6] etc
%
% Revision 1.57  2004/04/25 16:44:41  scott
% converted limits and limcontrib inputs back to ms (for compatibility with pop_envtopo)
%
% Revision 1.56  2004/04/25 16:20:41  scott
% clarified that input times are in sec, not ms; cleaned up commandline info -sm
%
% Revision 1.55  2004/04/24 17:21:37  scott
% fixed pvaf computation and printout. Added 'sumenv' mode as default. Deprecated
% 'colorfile' for 'colors' (backward compatible). Cleaned up printout.
% Edited help message.
%
% Revision 1.54  2004/03/03 21:44:00  arno
% rv for residual variance
%
% Revision 1.53  2004/03/03 21:26:02  arno
% debugging sorting of components; relative variance; text output
%
% Revision 1.52  2004/03/03 18:54:29  arno
% retreive version 1.50
%
% Revision 1.50  2004/02/03 15:58:00  arno
% no interpreter for title
%
% Revision 1.49  2004/01/29 16:56:30  scott
% same
%
% Revision 1.45  2004/01/29 16:50:45  scott
% printout edit
%
% Revision 1.44  2004/01/29 16:44:56  scott
% rm pvaf printout for now
%
% Revision 1.43  2004/01/29 16:39:45  scott
% test for chanlocs file location and size
%
% Revision 1.42  2004/01/26 02:22:13  scott
% same
%
% Revision 1.28  2004/01/26 00:45:14  scott
% improved listing of pvaf in Matlab command window
%
% Revision 1.27  2003/12/03 18:31:35  scott
% percentage -> percent
%
% Revision 1.26  2003/09/17 02:00:06  arno
% debuging pvaf assignment when using compnums
%
% Revision 1.25  2003/07/30 01:56:06  arno
% adding 'actscale' option and cbar
%
% Revision 1.24  2003/04/15 16:55:10  arno
% allowing to plot up to 20 components
%
% Revision 1.23  2003/03/23 20:14:50  scott
% fill msg edit
%
% Revision 1.22  2003/03/23 20:07:38  scott
% making data env overplot bold
%
% Revision 1.21  2003/03/23 20:05:59  scott
% overplot data envelope on filled component projection
%
% Revision 1.20  2003/03/14 16:18:37  arno
% plot pvaf in topoplot
%
% Revision 1.19  2003/03/14 15:23:29  arno
% pvaf -> * 100
%
% Revision 1.18  2003/03/14 02:50:18  arno
% help for pvaf
%
% Revision 1.17  2003/03/14 02:45:48  arno
% now printing pvaf
%
% Revision 1.16  2003/03/11 01:45:03  arno
% first capital letter in labels
%
% Revision 1.15  2003/03/10 18:24:47  arno
% ploting only one contribution
%
% Revision 1.14  2003/03/08 21:02:57  arno
% debugging
%
% Revision 1.13  2003/03/08 00:11:06  arno
% allowing input of ICA component activity
%
% Revision 1.12  2003/03/05 03:23:44  scott
% minor
%
% Revision 1.11  2003/03/03 22:28:03  arno
% update text header
%
% Revision 1.10  2003/02/27 02:52:24  arno
% typo
%
% Revision 1.9  2002/10/25 18:47:33  luca
% sign of comparison typo - ad
%
% Revision 1.8  2002/10/09 21:57:25  arno
% documenting limcontrib
%
% Revision 1.7  2002/10/09 21:32:18  arno
% documenting option subcomp
%
% Revision 1.6  2002/10/05 01:52:20  arno
% debug envmode
%
% Revision 1.5  2002/10/05 01:50:34  arno
% new function with 'key', 'val' args, extra params: envmode, limcontrib, icawinv...
%
% Revision 1.4  2002/09/05 00:57:22  arno
% colorbar->cbar for removing menu bug
%
% Revision 1.3  2002/04/25 17:22:33  scott
% editted help msg -sm
%
% Revision 1.2  2002/04/09 02:13:22  arno
% make the color file internal
%
% Revision 1.1  2002/04/05 17:36:45  jorn
% Initial revision
%

% Edit History:
% 3-18-98 fixed bug in LineStyle for fifth component, topoplot maxproj with 
%         correct orientations, give specified component number labels -sm
% 4-28-98 plot largest components, ranked by max projected variance -sm
% 4-30-98 fixed bug found in icademo() -sm
% 5-08-98 fixed bug found by mw () -sm
% 5-23-98 made vert. line styles for comps 6 & 11 correct -sm
% 5-30-98 added 'envtopo.labels' option -sm
% 5-31-98 implemented plotchans arg -sm
% 7-13-98 gcf->gca to allow plotting in subplots -sm
% 9-18-98 worked more to get plotting in subplot to work -- no luck yet! -sm
% 2-22-99 draw oblique line to max env value if data clipped at max proj -sm
% 2-22-99 added colorfile -sm
% 4-17-99 added support for drawing in subplots -t-pj
% 10-29-99 new versions restores search through all components for max 7 and adds 
%          return variables (>7 if specified. Max of 7 comp envs still plotted. -sm
% 11-17-99 debugged new version -sm
% 12-27-99 improved help msg, moved new version to distribution -sm
% 01-21-00 added 'bold' option for colorfile arg -sm
% 02-28-00 added fill_comp_env arg -sm
% 03-16-00 added axcopy() -sm & tpj
% 05-02-00 added vert option -sm
% 05-30-00 added option to show "envelope" of only 1 channel -sm
% 09-07-00 added [-n] option for compnums, added BOLD_COLORS as default -sm
% 12-19-00 updated icaproj() args -sm
% 12-22-00 trying 'axis square' for topoplots -sm
% 02-02-01 fixed bug in printing component 6 env line styles -sm
% 04-11-01 added [] default option for args -sm
% 01-25-02 reformated help & license, added links -ad 
% 03-15-02 added readlocs and the use of eloc input structure -ad 
% 03-16-02 added all topoplot options -ad

function [compvarorder,compvars,compframes,comptimes,compsplotted,pvaf] = envtopo(data,weights,varargin);

if nargin < 2
   help envtopo
   return
end
if nargin <= 2 | isstr(varargin{1})
	% 'key' 'val' sequency
	fieldlist = { 'chanlocs'      ''         []                       [] ;
				  'title'         'string'   []                       '';
				  'limits'        'real'     []                       0;
				  'plotchans'     'integer'  [1:size(data,1)]         [] ;
				  'icawinv'       'real'     []                       pinv(weights) ;
				  'icaact'        'real'     []                       [] ;
				  'voffsets'      'real'     []                       [] ;
				  'vert'          'real'     []                       [] ;
				  'fillcomp'      'integer'  []                       0 ;  % no fill
				  'colorfile'     'string'   []                       '' ; % deprecated usage
				  'colors'        'string'   []                       '' ; % new usage
				  'compnums'      'integer'  []                       -7; ...
				  'subcomps'      'integer'  []                       []; ...
				  'envmode'       'string'   {'avg' 'rms'}            'avg'; ...
				  'dispmaps'      'string'   {'on' 'off'}             'on'; ...
				  'pvaf'          'string'   {'on' 'off'}             'on'; ...
				  'actscale'      'string'   {'on' 'off'}             'off'; ...
				  'limcontrib'    'real'     []                       0;  ...
                                  'sumenv'        'string'    {'on' 'off' 'fill'}     'fill'};
	
	[g varargin] = finputcheck( varargin, fieldlist, 'envtopo', 'ignore');
	if isstr(g), error(g); end;
else
	if nargin > 3,    g.chanlocs = varargin{1};
	else              g.chanlocs = [];
	end;
	if nargin > 4,	  g.limits = varargin{2};
	else              g.limits = 0; % [];
	end;
	if nargin > 5,    g.compnums = varargin{3};
	else              g.compnums = [];
	end;
	if nargin > 6,    g.title = varargin{4};
	else              g.title = '';
	end;
	if nargin > 7,    g.plotchans = varargin{5};
	else              g.plotchans = [];
	end;
	if nargin > 8,    g.voffsets = varargin{6};
	else              g.voffsets = [];
	end;
	if nargin > 9,    g.colorfile = varargin{7};
	else              g.colorfile = '';
	end;
	if nargin > 10,   g.fillcomp = varargin{8};
	else              g.fillcom = 0;
	end;
	if nargin > 11,   g.vert = varargin{9};
	else              g.vert = [];
	end;
    g.limcontrib = 0;
    g.icawinv = pinv(weights);
    g.subcomps = [];
    g.envmode = 'avg';
    g.dispmaps = 'on';
    if nargin > 12, varargin =varargin(10:end); end;
end;
if ~isempty(g.colors)
    g.colorfile = g.colors; % retain old usage 'colorfile' for 'colors' -sm 4/04
end

%
%%%%%%%%%%%%%%%%% convert limits and limcontrib times to seconds from ms %%%%%%%
%
g.limits(1) = g.limits(1)/1000;
if length(g.limits)>1, g.limits(2) = g.limits(2)/1000; end;
g.limcontrib = g.limcontrib/1000;

uraxes = gca; % the original figure or subplot axes
pos=get(uraxes,'Position');
axcolor = get(uraxes,'Color');
delete(gca)
pvaf = [];

all_bold = 0;
BOLD_COLORS = 1;    % 1 = use solid lines for first 5 components plotted
                    % 0 = use std lines according to component rank only
FILL_COMP_ENV = 0;  % default no fill
MAXTOPOS = 20;      % max topoplots to plot

if ndims(data) == 3
    data = mean(data,3);
end;
[chans,frames] = size(data);

% computing sublimits
% -------------------
if any(g.limcontrib ~= 0) & any(g.limits ~= 0)
    sratems = (size(data,2)-1)/(g.limits(2)-g.limits(1));
    frame1  = round((g.limcontrib(1)-g.limits(1))*sratems)+1;
    frame2  = round((g.limcontrib(2)-g.limits(1))*sratems)+1;
    g.vert(end+1) =  g.limcontrib(1);
    g.vert(end+1) =  g.limcontrib(2);
else
    frame1 = 1;
    frame2 = frames;
end;

	% subtracting components
	% ----------------------
	if ~isempty(g.subcomps)
	    fprintf('envtopo: subtracting components from data\n');
	    proj = icaproj(data,weights,g.subcomps); % updated arg list 12/00 -sm
	    data = data -proj;
	end;
	    
	[wtcomps,wchans] = size(weights);
	if wchans ~= chans
	   fprintf('envtopo(): sizes of weights and data do not agree.\n');
	   return