spectopo.m

含有多种ICA算法的eeglab工具箱

% spectopo() - Plot the mean log spectrum of a set of data epochs at all channels 
%              as a bundle of traces. At specified frequencies, plot the relative 
%              topographic distribution of power. If available, uses pwelch() from 
%              the Matlab signal processing toolbox, else the EEGLAB spec() function.
% Usage:
%              >> spectopo(data, frames, srate);
%              >> [spectra,freqs,speccomp,contrib,specstd] = ...
%                     spectopo(data, frames, srate, 'key1', 'val1', 'key2', 'val2' ...);
% Inputs:
%       data   = If 2-D (nchans,frames*epochs); % can be single-epoch
%                else, 3-D (nchans,frames,epochs)
%       frames = frames per epoch {0 -> data length}
%       srate  = sampling rate per channel (Hz)
%
% Optional inputs:
%   'freq'     = [float vector (Hz)] vector of frequencies for topoplot() scalp maps
%                of power at all channels, or single frequency to plot component 
%                contributions at a single channel (see also 'plotchan').
%   'chanlocs' = electrode locations file (format: >> topoplot example)
%   'limits'   = axis limits [xmin xmax ymin ymax cmin cmax]
%                To use data limits, omit final values or use nan's
%                i.e. [-100 900 nan nan -10 10], [-100 900]
%                Note that default color limits are symmetric around 0 and are
%                different for each head {defaults: all nans}
%   'title'    = [quoted string] plot title {default: none}
%   'freqfac'  = [integer] ntimes to oversample -> frequency resolution {default: 2}
%   'nfft'     = [integer] value to zero pad data to. Overwrites 'freqfac' above.
%   'winsize'  = [integer] window size in data points {default: from data}
%   'overlap'  = [integer] window overlap in data points {default: 0}
%   'percent'  = [float 0 to 100] percent of the data to sample in computing the 
%                spectra. Can be used to speed up the computation. {default: 100}.
%   'freqrange' = [min max] frequency range to plot. Changes x-axis limits. Default is
%                1 Hz for the min and niquist (srate/2) for the max (if some scalp
%                maps are plotted, the scalp map at the highest frequency specifies
%                the maximum).
%   'reref'    = ['averef'|'off'] convert input data to average reference 
%                {default: 'off'}
%   'mapnorm'  = [float vector] if 'data' contain the activity of an independant 
%                component, this parameter should contain its scalp map. In this case
%                the spectrum amplitude will be scaled by component RMS scalp power.
%                Useful for comparing component strengths.
%   'boundaries' = data point indices of discontinuities in the signal
%   'plot'     = ['on'|'off'] 'off' -> disable plotting. {default: 'on'}
%
% Optionally plot component contributions:
%   'weights'  = ICA unmixing matrix. Here, 'freq' (above) must be a single frequency.
%                ICA maps of the N (='nicamaps') components that account for the most
%                power at the selected frequency ('freq') are plotted along with
%                the spectra of the selected channel ('plotchan') and components
%                ('icacomps').
%   'plotchan' = [integer] channel at which to compute independent conmponent
%                contributions at the selected frequency ('freq'). {[]=channel with
%                higest power at 'freq'). If 0, plot RMS power at all channels. 
%   'nicamaps' = [integer] number of ICA component maps to plot (default: 4).
%   'icacomps' = [integer array] indices of ICA component spectra to plot ([] -> all).
%   'icamode'  = ['normal'|'sub'] in 'sub' mode, instead of computing the spectrum of
%                individual ICA components, the function computes the spectrum of
%                the data minus their contributions {default: 'normal'}
%   'icamaps'  = [integer array] force plotting of selected ICA compoment maps ([]=the
%                'nicamaps' largest).
%   'icawinv'  = [float array] inverse weight matrix. By default computed by inverting
%                the weight matrix. However, if some components have been removed, then
%                weight's pseudo-inverse matrix does not represent component's maps. 
%   'memory'   = ['low'|'high'] setting to low will use less memory for component 
%                computing, but computing time will be longer.
%
% Topoplot options:
%    opther 'key','val' options are propagated to topoplot() for map display
%    (see help topoplot())
%
% Outputs:
%        spectra  = (nchans,nfreqs) power spectra (mean power over epochs), in dB
%        freqs    = frequencies of spectra (Hz)
%        speccomp = component spectra (ncomps,nfreqs). Warning, only the function  
%                   only computes the spectrum of the components given as input using 
%                   the 'icacomps' parameter. Other component spectrum are filled  
%                   with 0.
%        contrib  = contribution of each component (if 'icamode' is 'normal', relative
%                   variance, if 'icamode' is 'sub', percent variance accounted for)
%        specstd  = spectrum standard deviation in dB
%
% Notes: The original input format is still functional for backward compatibility.
%        psd() has been replaced by pwelch() (see Matlab note 24750 on their web site)
%
% Authors: Scott Makeig, Arnaud Delorme & Marissa Westerfield, 
%          SCCN/INC/UCSD, La Jolla, 3/01 
%
% See also: timtopo(), envtopo(), tftopo(), topoplot()

% Copyright (C) 3/01 Scott Makeig & Arnaud Delorme & Marissa Westerfield, 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: spectopo.m,v $
% Revision 1.88  2004/04/30 17:40:19  arno
% max niquest by default
%
% Revision 1.87  2004/04/29 16:27:30  scott
% removed license() call - expanded license function has disappeared from the matlab path!?
%
% Revision 1.86  2004/04/28 14:46:54  scott
% added license() call to test for pwelch availability -sm
%
% Revision 1.85  2004/04/28 14:36:51  scott
% added commandline tests; edited help msg
%
% Revision 1.84  2004/02/12 02:14:09  arno
% message for spec()
%
% Revision 1.83  2004/02/06 17:19:51  arno
% select at least one epoch
%
% Revision 1.82  2003/12/03 19:30:27  arno
% same
%
% Revision 1.81  2003/12/03 19:29:40  arno
% more warnings if using spec()
%
% Revision 1.80  2003/12/03 19:25:24  arno
% add message
%
% Revision 1.79  2003/12/03 18:28:54  scott
% percentage -> percent
%
% Revision 1.78  2003/12/03 02:44:27  arno
% indenting
%
% Revision 1.77  2003/12/03 02:15:40  arno
% use spec if pwelch absent
%
% Revision 1.76  2003/11/26 17:14:29  arno
% 10*lochanging log label
%
% Revision 1.75  2003/11/19 22:55:31  arno
% changing unit
%
% Revision 1.74  2003/09/25 00:50:14  arno
% mapnorm
%
%
%
%
%
%
%
%
%
%
%
%
% adding comments for mapnorm
%
% Revision 1.73  2003/09/09 23:26:17  arno
% change && to &
%
% Revision 1.72  2003/09/08 15:41:15  arno
% changing test to eegspec
%
% Revision 1.71  2003/09/08 15:12:50  arno
% & -> &&
%
% Revision 1.70  2003/09/02 20:40:40  scott
% help msg
%
% Revision 1.69  2003/08/12 16:55:23  arno
% update comments
%
% Revision 1.68  2003/08/12 16:52:55  arno
% pwelch
%
% Revision 1.66  2003/08/11 15:37:16  arno
% psd -> pwelch
%
% Revision 1.65  2003/07/31 17:18:15  arno
% 20 to winlength
%
% Revision 1.64  2003/07/30 19:05:12  arno
% debuging for boundaries thank to Johannes Sarnthein
%
% Revision 1.63  2003/06/12 00:51:35  arno
% adding 'plot' option
%
% Revision 1.62  2003/06/12 00:41:17  arno
% same
%
% Revision 1.61  2003/06/12 00:31:15  arno
% debug last
%
% Revision 1.60  2003/06/12 00:23:55  arno
% header typo, returns std
%
% Revision 1.59  2003/05/11 19:51:53  arno
% debuging changeunitis
%
% Revision 1.58  2003/04/23 21:24:24  arno
% ignore small data segments
%
% Revision 1.57  2003/04/18 01:11:31  arno
% 3 new options: nfft, winsize, overlap
%
% Revision 1.56  2003/04/18 00:49:57  arno
% adding mapnorm option
%
% Revision 1.55  2003/04/17 00:41:06  arno
% computing pvaf at all channels
%
% Revision 1.54  2003/04/09 23:32:49  arno
% fixing lines
%
% Revision 1.53  2003/03/14 16:17:56  arno
% print pvaf in topoplot
%
% Revision 1.52  2003/02/26 03:00:34  arno
% header edit
%
% Revision 1.51  2003/01/28 18:02:20  arno
% debuging ERP plot if no channel location file
%
% Revision 1.50  2003/01/28 17:37:25  arno
% debugging freqency range if no topoplot
%
% Revision 1.49  2003/01/21 17:21:30  arno
% debug last
%
% Revision 1.48  2003/01/21 17:19:32  arno
% adding strvcat to the y-label
%
% Revision 1.47  2003/01/03 01:42:31  arno
% more details on default percentage
%
% Revision 1.46  2002/11/19 18:55:59  arno
% spectopo now returning component spectrum
%
% Revision 1.45  2002/11/15 01:39:31  scott
% Can not -> cannot
%
% Revision 1.44  2002/11/14 17:12:10  arno
% debugging channel spectra
%
% Revision 1.43  2002/10/30 23:31:00  arno
% changing default pwelch options
%
% Revision 1.42  2002/10/23 02:35:02  arno
% closing figure when error (selective)
%
% Revision 1.41  2002/10/23 02:28:54  arno
% RMS for channel and better implementation for global channel power
%
% Revision 1.40  2002/10/23 00:59:48  arno
% implementing new component scaling
%
% Revision 1.39  2002/10/10 16:00:22  arno
% cle
% move title a little bit
%
% Revision 1.38  2002/10/09 00:21:44  arno
% remove previous modif
%
% Revision 1.37  2002/10/09 00:21:14  arno
% nothing
%
% Revision 1.36  2002/10/08 22:13:39  arno
% typo
%
% Revision 1.35  2002/10/04 16:07:16  arno
% adding icawinv parameter
%
% Revision 1.34  2002/09/05 00:07:40  arno
% raising channel plot when plotting components
%
% Revision 1.33  2002/08/30 17:37:07  arno
% debugging for channel 0
%
% Revision 1.32  2002/08/29 01:10:02  arno
% imaging component square
%
% Revision 1.31  2002/08/22 15:36:56  arno
% decoupling window length and fft length
%
% Revision 1.30  2002/08/17 00:13:35  arno
% same default as in timef for epoched data
%
% Revision 1.29  2002/08/12 22:46:19  arno
% maxfreq->freqrange
%
% Revision 1.28  2002/08/11 18:44:56  arno
% moving main title
%
% Revision 1.27  2002/08/11 18:27:36  arno
% making subplot possible
%
% Revision 1.26  2002/08/09 01:54:06  arno
% weighting by boundary interval length
%
% Revision 1.25  2002/08/09 01:33:50  arno
% debugging boundaries
%
% Revision 1.24  2002/08/09 01:15:36  arno
% updating boundaries
%
% Revision 1.23  2002/07/30 18:12:51  arno
% debugging
%
% Revision 1.22  2002/07/29 22:22:27  arno
% update messages
%
% Revision 1.21  2002/07/26 02:11:02  arno
% debugging max limits
%
% Revision 1.20  2002/07/26 01:15:49  arno
% adding percentage of variance
%
% Revision 1.19  2002/07/25 20:58:33  luca
% divide sum of epoch spectra by length(epoch_subset).
%
% Revision 1.18  2002/07/25 20:44:32  luca
% *** empty log message ***
%
% Revision 1.17  2002/07/25 00:36:32  arno
% debugging
%
% Revision 1.16  2002/07/25 00:18:23  scott
% plot diag comp map lines in same colors as comp spec traces. -sm & ad
%
% Revision 1.15  2002/07/24 17:47:55  arno
% making it nicer for components
%
% Revision 1.14  2002/07/20 19:21:21  arno
% debugging
%
% Revision 1.13  2002/07/20 01:55:54  arno
% add ignore extras
%
% Revision 1.12  2002/07/20 01:51:14  arno
% back to old way of computing average of power
%
% Revision 1.11  2002/07/20 01:44:12  arno
% checking parameter
%
% Revision 1.10  2002/07/20 01:41:07  arno
% percent update
%
% Revision 1.9  2002/07/20 01:35:14  arno
% percent from 0 to 100
%
% Revision 1.8  2002/07/20 01:17:10  arno
% new version with component plotting options
%
% Revision 1.7  2002/07/18 16:00:46  arno
% adding option for not plotting channels
%
% Revision 1.6  2002/07/07 22:44:49  scott
% *** empty log message ***
%
% Revision 1.5  2002/07/07 22:42:17  scott
% help msg -sm
%
% Revision 1.4  2002/07/07 22:38:27  scott
% adding 'reref','averef' option -sm
%
% Revision 1.3  2002/04/21 00:38:25  scott
% 'Selecting randomly' -> 'Randomly selecting' -sm
%
% Revision 1.2  2002/04/18 18:19:28  arno
% adding 3D option
%
% Revision 1.1  2002/04/05 17:36:45  jorn
% Initial revision
%

% 3-20-01 added limits arg -sm
% 01-25-02 reformated help & license -ad