tftopo.m

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

% tftopo()  - Generates a figure showing a selected image (e.g., an ERSP or ITC) from 
%             a supplied set of images for every scalp channel, plus topoplot() scalp 
%             maps at specified (x,y) (e.g., time,frequency) points.  Else, images the 
%             signed (selected) channel std(). Inputs may be outputs of timef(); else,
%             e.g., can be used to image a set of smoothed erpimage() images.
% Usage:
%        >> tftopo(tfdata,times,freqs, 'key1', 'val1', 'key2', val2' ...)
% Inputs:
%   tfdata    = Set of nchans time/freq ERSPs or ITCs from timef() (or any other
%               time/freq matrix), one for each channel. Size (time,freq,chans) or
%               (time,freq,chans,subjects) for grand RMS.
%   times     = Vector of times in msec from timef()
%   freqs     = Vector of frequencies in Hz from timef() 
%
% Optional inputs:
%  'timefreqs' = Array of time/frequency points to show topoplot() maps for
%                Format: size (nrows,2), each row [ms Hz]
%  'showchan'  = [integer] Channel number of tfdata to image, or 0
%                {default=0 -> image the median-signed st. dev. across channels} 
%  'chanlocs'  = ['string'|structure] Electrode locations file (for format see 
%                >> topoplot example) or structure             {default none}
%  'limits'    = Vector of plotting limits [minms maxms minhz maxhz mincaxis maxcaxis]
%                Omit, or use nan's to use tfdata limits. Ex: [nan nan -100 400];
%  'signifs'   = Significance level(s) (e.g., from timef()), for zero'ing non-significant 
%                tfdata. Size must be (1 or 2, freq, chans, subjects) or 
%                (1 or 2, freq, times, chans, subjects). If first dimension is
%                of size 1, tfdata is assumed to contain positive values   {default: none}
%  'sigthresh' = [integer], i.e. [K L] after masking time-frequency decomposition using 
%                'signifs' array, concatenate time/freq values only if more than K electrodes
%                have non-0 (significant) values. If several subject, the second value L
%                is used to concatenate subject in the same fashion. Default is [1 1].
%  'selchans'  = Channels to include in topoplot() scalp maps (and image std()) {default: all}
%  'smooth'    = [pow2] magnification and smoothing factor. Only in power of 2 (Default: 1}.
%  'mode'      = ['rms'|'ave'] average dB power ('ave') or return root-mean-square ('rms')
%                {Default: 'rms' }
%  'logfreq'   = ['on'|'off'] use logarithmic base for frequencies { Default: 'off' }
%  'vert'      = [times vector] -> plot vertical dashed lines at specified times in ms.
%                { Default: 0 }
%  'shiftimgs' = [time vector] - shift time frequency images (for several subject) by the
%                median reaction time of each subject (provided here).
%
% Note:
%  1) Additional topoplot() options can be used.
%  2) For topoplot maps, the average power (not masked by significance is used (instead
%     of the root-mean-square (RMS) for averaging electrode activity).
%  3) If several subjects (4-D tfdata input) RMS is first computed across electrodes
%     then across subjects.
%
% Authors: Scott Makeig, Arnaud Delorme & Marissa Westerfield, SCCN/INC/UCSD, La Jolla, 3/01 
%
% See also: timef(), topoplot(), spectopo(), timtopo(), envtopo(), changeunits()

% hidden parameter: 'shiftimgs' = array with one value per subject for shifting in time
%                                 time/freq images. Had to be inserted in tftopo because
%                                 the shift happen after the smoothing

% Copyright (C) Scott Makeig, Arnaud Delorme & Marissa Westerfield, SCCN/INC/UCSD, 
% La Jolla, 3/01
%
% 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: tftopo.m,v $
% Revision 1.64  2004/03/22 03:27:49  scott
% removing topoplot shrink mode - topoplot default now shows all channels
%
% Revision 1.63  2003/09/11 18:59:34  arno
% allowing image significance
%
% Revision 1.62  2003/08/28 17:41:21  arno
% debuging the first dimension for significance
%
% Revision 1.61  2003/08/27 21:49:48  arno
% fixing mode error
%
% Revision 1.60  2003/08/27 00:31:09  arno
% fix rms/average
%
% Revision 1.59  2003/03/08 02:26:32  arno
% document the shiftimgs option
%
% Revision 1.58  2003/03/08 02:23:54  arno
% update header
%
% Revision 1.57  2003/03/04 18:12:07  arno
% color limits debug
%
% Revision 1.56  2002/10/09 18:20:21  arno
% line thickness
%
% Revision 1.55  2002/10/09 18:12:00  arno
% new inputs logfreq, shiftdims, vert, smooth ...
%
% Revision 1.54  2002/10/08 23:55:35  arno
% debug
%
% Revision 1.53  2002/10/08 23:54:34  arno
% 'key', 'val' sequence, new args, new header
%
% Revision 1.52  2002/10/07 18:51:11  arno
% all data -> 3D, significance, RMS, subject RMS, ...
%
% Revision 1.51  2002/10/07 15:44:48  arno
% updating header and axis off
%
% Revision 1.50  2002/10/03 23:39:44  scott
% added sbplot() plotting -sm & ad
%
% Revision 1.49  2002/05/19 14:30:15  scott
% *** empty log message ***
%
% Revision 1.48  2002/05/19 14:28:55  scott
% improved out-of-bounds testing -sm
%
% Revision 1.47  2002/05/19 14:21:52  scott
% *** empty log message ***
%
% Revision 1.46  2002/05/19 14:20:34  scott
% *** empty log message ***
%
% Revision 1.45  2002/05/19 14:19:35  scott
% added cartoon of showchan if > 0  -sm
%
% Revision 1.44  2002/05/19 14:17:55  scott
% *** empty log message ***
%
% Revision 1.43  2002/05/19 14:16:11  scott
% *** empty log message ***
%
% Revision 1.42  2002/05/19 14:15:03  scott
% *** empty log message ***
%
% Revision 1.41  2002/05/19 14:12:53  scott
% *** empty log message ***
%
% Revision 1.40  2002/05/19 14:12:08  scott
% *** empty log message ***
%
% Revision 1.39  2002/05/19 14:07:12  scott
% *** empty log message ***
%
% Revision 1.38  2002/05/19 14:06:40  scott
% *** empty log message ***
%
% Revision 1.37  2002/05/19 14:05:50  scott
% testing -sm
%
% Revision 1.36  2002/05/19 14:00:45  scott
% *** empty log message ***
%
% Revision 1.35  2002/05/19 13:57:54  scott
% *** empty log message ***
%
% Revision 1.34  2002/05/19 13:52:24  scott
% showchans=0 -> image std() of selchans images -sm
%
% Revision 1.33  2002/05/19 13:35:16  scott
% *** empty log message ***
%
% Revision 1.32  2002/05/19 13:34:12  scott
% showchan==0 -> image signed st dev -sm
%
% Revision 1.31  2002/05/19 13:26:10  scott
% adjusted channel label -sm
%
% Revision 1.30  2002/05/19 03:04:46  scott
% *** empty log message ***
%
% Revision 1.29  2002/05/19 02:57:24  scott
% *** empty log message ***
%
% Revision 1.28  2002/05/19 02:55:45  scott
% *** empty log message ***
%
% Revision 1.27  2002/05/19 02:53:45  scott
% *** empty log message ***
%
% Revision 1.26  2002/05/19 02:50:40  scott
% *** empty log message ***
%
% Revision 1.25  2002/05/19 02:28:08  scott
% *** empty log message ***
%
% Revision 1.24  2002/05/19 02:24:15  scott
% *** empty log message ***
%
% Revision 1.23  2002/05/19 02:21:17  scott
% *** empty log message ***
%
% Revision 1.22  2002/05/19 02:20:26  scott
% *** empty log message ***
%
% Revision 1.21  2002/05/19 02:18:36  scott
% *** empty log message ***
%
% Revision 1.20  2002/05/19 02:15:13  scott
% adding separate scale for showchan==0 -sm
%
% Revision 1.19  2002/04/30 21:24:48  scott
% *** empty log message ***
%
% Revision 1.18  2002/04/30 21:23:58  scott
% *** empty log message ***
%
% Revision 1.17  2002/04/30 21:22:46  scott
% *** empty log message ***
%
% Revision 1.16  2002/04/30 21:21:50  scott
% *** empty log message ***
%
% Revision 1.15  2002/04/30 21:21:15  scott
% *** empty log message ***
%
% Revision 1.14  2002/04/30 21:19:05  scott
% debugging sign feature for showchans==0 -sm
%
% Revision 1.13  2002/04/30 21:17:59  scott
% fg
%
% Revision 1.12  2002/04/30 21:17:01  scott
% adding sign -sm
%
% Revision 1.11  2002/04/30 20:53:35  scott
% debugging showchans==0 option -sm
%
% Revision 1.10  2002/04/30 20:47:39  scott
% *** empty log message ***
%
% Revision 1.9  2002/04/30 20:45:56  scott
% showchan==0 -> blockave(abs(tfdata)) -sm
%
% Revision 1.8  2002/04/27 01:37:19  scott
% same -sm
%
% Revision 1.7  2002/04/27 01:26:40  scott
% updated topoplot call -sm
%
% Revision 1.6  2002/04/27 01:19:33  scott
% same -sm
%
% Revision 1.5  2002/04/27 01:13:46  scott
% same -sm
%
% Revision 1.4  2002/04/27 01:10:29  scott
% same -sm
%
% Revision 1.3  2002/04/27 01:06:00  scott
% same -sm
%
% Revision 1.2  2002/04/27 01:04:12  scott
% added handling of 3-d tftopo data -sm
%
% Revision 1.1  2002/04/05 17:36:45  jorn
% Initial revision
%

% 01-25-02 reformated help & license -ad 

function tfave = tftopo(tfdata,times,freqs,varargin);
    %timefreqs,showchan,chanlocs,limits,signifs,selchans)

LINECOLOR= 'k';
LINEWIDTH = 2;
ZEROLINEWIDTH = 2.8;

if nargin<3
   help tftopo
   return
end

% reshape tfdata
% --------------
if length(size(tfdata))==2
   nchans = round(size(tfdata,2)/length(times));
   tfdata = reshape(tfdata, size(tfdata,1), length(times), nchans); 
elseif length(size(tfdata))>=3
   nchans = size(tfdata,3);
else
   help tftopo
   return
end
tfdataori = mean(tfdata,4); % for topoplot

% test inputs
% -----------
% 'key' 'val' sequence
fieldlist = { 'chanlocs'      { 'string' 'struct' }       []       '' ;
              'limits'        'real'     []                        [nan nan nan nan nan nan];
              'logfreq'       'string'   {'on' 'off' }             'off';
              'mode'          'string'   { 'ave' 'rms' }           'rms';
              'selchans'      'integer'  [1 nchans]                [1:nchans];
              'shiftimgs'     'real'     []                        [] ;
              'showchan'      'integer'  [0 nchans]                0 ;
              'signifs'       'real'     []                        [];
              'sigthresh'     'integer'  [1 Inf]                   [1 1];
              'smooth'        'real'     [0 Inf]                   1;
              'timefreqs'     'real'     []                        [];
              'vert'          'real'     [times(1) times(end)]     [0] };

[g varargin] = finputcheck( varargin, fieldlist, 'tftopo', 'ignore');
if isstr(g), error(g); end;

% setting more defaults
% ---------------------
if length(times) ~= size(tfdata,2)
   fprintf('tftopo(): tfdata columns must be a multiple of the length of times (%d)\n',...
                 length(times));
   return
end
if length(g.showchan) > 1
    error('tftopo(): showchan must be a single number');
end;
if length(g.limits)<1 | isnan(g.limits(1))
  g.limits(1) = times(1);
end
if length(g.limits)<2 | isnan(g.limits(2))
  g.limits(2) = times(end);
end
if length(g.limits)<3 | isnan(g.limits(3))
  g.limits(3) = freqs(1);
end
if length(g.limits)<4 | isnan(g.limits(4))
  g.limits(4) = freqs(end);
end
if length(g.limits)<5 | isnan(g.limits(5)) % default caxis plotting limits
  g.limits(5) = -max(abs(tfdata(:)));
  mincax = g.limits(5); 
end
if length(g.limits)<6 | isnan(g.limits(6))
    defaultlim = 1;
    if exist('mincax')
        g.limits(6) = -mincax; % avoid recalculation
    else
        g.limits(6) = max(abs(tfdata(:)));
    end
else 
    defaultlim = 0;