erpimage.m

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

% erpimage() - Image a collection of single-trial data epochs, optionally sorted on 
%              and/or aligned to an input sorting variable and smoothed across trials 
%              with a moving-average.  (To return event-aligned data without plotting, 
%              use eventlock()).  Optionally sort trials on value, amplitude or phase 
%              within a specified latency window. Optionally plot the ERP mean and std. dev.,
%              and moving-window spectral amplitude and inter-trial coherence at a
%              selected or peak frequency. Click on individual figures parts to examine 
%              them separately and zoom (using axcopy()).
% Usage:
%   >> [outdata,outvar,outtrials,limits,axhndls,erp, ...
%         amps,cohers,cohsig,ampsig,outamps,phsangls,phsamp,sortidx,erpsig] ...
%                  = erpimage(data,sortvar,times,'title',avewidth,decimate,...
%                             flag1,arg1,flag2,arg2,...);
% Necessary inputs:
%   data     - [vector or matrix] Single-channel input data to image. 
%               Formats (1,frames*trials) or (frames,trials)
%
% Optional ordered inputs {with defaults}:
%   sortvar  - [vector | []] Variable to sort epochs on (length(sortvar) = nepochs)
%              Example: sortvar may by subject response time in each epoch (in ms)
%              {default|[]: plot in input order}
%   times    - [vector | []] of latencies (ms) (length(times) = frames) 
%               ELSE [startms ntimes srate] Give start latency (ms), time points 
%               (i.e. frames) per epoch, sampling rate (Hz), {default|[]: 0:nframes-1}
%  'title'   - ['string'] Plot titla {default: none}
%   avewidth - Number of trials to moving-average (NB: may be non-int) {default|0->1}
%   decimate - Factor to decimate ntrials out by (NB: may be non-int)  {default|0->1}
%               If this is large ( > sqrt(num. trials)), output this many trials.
%
% Unordered options ('keyword',argument pairs):
%
% Optionally realign data epochs: 
%   'align'  - [latency] Time-lock data to sortvar. Plot sortvar as at latency (ms)
%               If latency == Inf, plot at sortvar median {default: no align}
%   'renorm' - ['yes'|'no'|'formula(x)'] Normalize sorting variable to epoch 
%               latency range and plot. 'yes'= autoscale. Example of formula(x):
%               '3*x+2'. {default: 'no'}
%   'noplot' - Do not plot sortvar {default: Do plot sortvar if in times range}
%   'noshow' - ['yes'|'no'] Do not plot erpimage, simply return outputs {default: 'no'}
%
% Optionally sort input epochs: 
%   'nosort' - Do not sort data epochs.
%  {default} - Sort data epochs by sortvar (see Necessary inputs above).
%  'valsort' - [startms endms direction] Sort data on (mean) value 
%               between startms and (optional) endms. Direction is 1 or -1.
%              If -1, plot max-value epoch at bottom {Default: sort on sortvar}
% 'phasesort' - [ms_center prct freq maxfreq topphase] Sort epochs by phase in 
%                an n-cycle window centered at latency ms_center (ms). 
%                Percentile (prct) in range [0,100] gives percent of trials 
%                to reject for low amplitude. Else, if in range [-100,0], 
%                percent of trials to reject for high amplitude; freq (Hz) 
%                is the phase-sorting frequency. With optional maxfreq,
%                sort by phase at freq of max power in the data in range 
%                [freq,maxfreq] (Note: 'phasesort' arg freq overrides the 
%                frequency specified in 'coher'). With optional topphase, 
%                sort by phase, putting topphase (degrees, in range [-180,180]) 
%                at the top of the image. NB: 'phasesort' now uses circular 
%                smoothing. Use 'cycles' (below) for wavelet length. 
%                {Default: [0 25 8 13 180]}
%  'ampsort' - [center_ms prcnt freq maxfreq] Sort epochs by amplitude. 
%                See 'phasesort'.
%  'showwin' - Show sorting window behind ERP trace. {default: don't show sorting window}
%
% Plot time-varying spectral amplitude instead of potential:
% 'plotamps' - Image amplitudes at each trial and latency instead of potential values. 
%               NB: Currently Requires 'coher' (below) with alpha signif. {default: no}
%
% Specify plot parameters:
%   'limits' - [lotime hitime minerp maxerp loamp hiamp locoher hicoher bamp]
%               Plot axes limits. Can use NaN (or nan, but not Nan) for missing items 
%               and omit late items. Use last input, bamp, to fix the baseline amplitude.
%   'signif' - [lo_amp, hi_amp, coher_signif_level] Use preassigned significance 
%               levels to save computation time. {default: none}
%   'caxis'  - [lo hi] Set color axis limits ELSE [fraction] Set caxis limits at 
%               (+/-)fraction*max(abs(data)) {default: symmetrical, based on data limits}
%
% Add epoch-mean ERP to plot:
%   'erp'    - Plot ERP time average of the trials below the image {default no ERP plotted}
%   'erpalpha' - [alpha] One-sided significance threshold (range: [.001 0.1]). 
%              Requires 'erp' {default no +/-alpha significance thresholds plotted}
%   'erpstd' - Plot ERP +/- stdev. Requires 'erp' {default no +/-stdev plotted}
%   'rmerp'  - Subtract the average ERP from each trial before processing {default no}
%
% Add time/frequency information:
%  'coher'   - [freq] Plot ERP average plus mean amplitude & coherence at freq (Hz)
%               ELSE [minfrq maxfrq] = same, but select frequency with max power in 
%               given range (NB: 'phasesort' freq (above) overwrites these parameters).
%               ELSE [minfrq maxfrq alpha] = plot coher. signif. level line at 
%               probability alpha (range: [0,0.1]) {default: no coher, no probabilities}
%   'srate'  - [freq] Specify the data sampling rate in Hz for amp/coher (if not 
%               implicit in third arg times) {default: as in icadefs.m}
%   'cycles' - Number of cycles in the wavelet time/frequency decomposition {default: 3}
%
% Add other features:
%   'cbar'   - Plot color bar to right of ERP-image {default no}
%   'topo'   - {map_vals,eloc_file} Plot a 2-D scalp map at upper left of image. 
%               See '>> topoplot example' for electrode location file structure.
%   'spec'   - [loHz,hiHz] Plot the mean data spectrum at upper right of image. 
%   'vert'   - [times_vector] Plot vertical dashed lines at specified latencies
%   'horz'   - [epochs_vector] Plot horizontal lines at specified epochs
%   'auxvar' - [(nvars,ntrials) matrix] Plot auxiliary variable(s) for each trial 
%               as separate traces. ELSE, 'auxvar',{[that_matrix],{colorstrings}} 
%               to specify N trace colors.  Ex: colorstrings = {'r','bo-','k:'} 
%               (See also: 'vert' above).
% Miscellaneous options:
% 'noxlabel' - Do not plot "Time (ms)" on the bottom x-axis
% 'yerplabel' - ['string'] ERP ordinate axis label (default is ERP). Get uV with '\muV'
%
% Optional outputs:
%    outdata  = (times,epochsout) data matrix (after smoothing)
%     outvar  = (1,epochsout) actual values trials are sorted on (after smoothing)
%   outtrials = (1,epochsout)  smoothed trial numbers
%     limits  = (1,10) array, 1-9 as in 'limits' above, then analysis frequency (Hz) 
%    axhndls  = vector of 1-7 plot axes handles (img,cbar,erp,amp,coh,topo,spec)
%        erp  = plotted ERP average
%       amps  = mean amplitude time course
%      coher  = mean inter-trial phase coherence time course
%     cohsig  = coherence significance level
%     ampsig  = amplitude significance levels [lo high]
%    outamps  = matrix of imaged amplitudes (from option 'allamps')
%   phsangls  = vector of sorted trial phases at the phase-sorting frequency
%     phsamp  = vector of sorted trial amplitudes at the phase-sorting frequency
%    sortidx  = indices of sorted data epochs plotted
%     erpsig  = trial average significance levels [2,frames]
%
% Example:  >> figure; erpimage(data,RTs,[-400 256 256],'Test',1,1,'erp','cbar','vert',-350);
%
% Plots an ERP-image of 1-s data epochs sampled at 256 Hz, sorted by RTs, title 'Test', 
% sorted epochs not smoothed or decimated. Also plots the epoch-mean ERP, a color bar, 
% and a dashed vertical line at -350 ms.

% Authors: Scott Makeig, Tzyy-Ping Jung & Arnaud Delorme, 
%          CNL/Salk Institute, La Jolla, 3-2-1998 -
%
% See also: erpimages(), phasecoher(), rmbase(), cbar(), movav()

%123456789012345678901234567890123456789012345678901234567890123456789012

% Copyright (C) Scott Makeig & Tzyy-Ping Jung, CNL / Salk Institute, La Jolla 3-2-98
%
% 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

% Uses external toolbox functions: phasecoher(), rmbase(), cbar(), movav()
% Uses included functions:         plot1trace(), phasedet()

% UNIMPLEMENTED - 'allcohers',[data2] -> image the coherences at each latency & epoch. 
%                 Requires arg 'coher' with alpha significance. 
%                 Shows projection on grand mean coherence vector at each latency 
%                 and trial. {default: no}
 
% $Log: erpimage.m,v $
% Revision 1.211  2004/06/09 01:48:43  arno
% make limits and image data consistent
%
% Revision 1.210  2004/06/05 01:52:45  arno
% aligntime as string to avoid really realigning
%
% Revision 1.209  2004/06/05 01:33:07  arno
% spetial option to preserve backward compatibility
%
% Revision 1.208  2004/05/07 04:47:17  scott
% made sotvar = [] work
%
% Revision 1.207  2004/03/26 00:21:06  arno
% same
%
% Revision 1.206  2004/03/26 00:19:48  arno
% minimum number of trials
%
% Revision 1.205  2004/03/26 00:18:11  arno
% plot aligntime
%
% Revision 1.204  2004/02/24 23:04:40  arno
% fixed vertical lines in ERP when RT-aligned
%
% Revision 1.203  2004/01/24 22:01:23  scott
% *** empty log message ***
%
% Revision 1.202  2004/01/24 21:58:33  scott
% same
%
% Revision 1.201  2004/01/24 21:53:38  scott
% same
%
% Revision 1.200  2004/01/24 21:43:59  scott
% *** empty log message ***
%
% Revision 1.199  2004/01/24 21:36:01  scott
% *** empty log message ***
%
% Revision 1.198  2004/01/24 21:26:50  scott
% same
%
% Revision 1.197  2004/01/24 21:25:04  scott
% same
%
% Revision 1.196  2004/01/24 21:22:59  scott
% same
%
% Revision 1.195  2004/01/24 21:17:00  scott
% same
%
% Revision 1.194  2004/01/24 21:16:32  scott
% same
%
% Revision 1.193  2004/01/24 21:10:31  scott
% same
%
% Revision 1.192  2004/01/24 21:08:29  scott
% same
%
% Revision 1.191  2004/01/24 21:04:09  scott
% same
%
% Revision 1.190  2004/01/24 21:01:18  scott
% same
%
% Revision 1.189  2004/01/24 20:59:53  scott
% same
%
% Revision 1.188  2004/01/24 20:51:57  scott
% same
%
% Revision 1.187  2004/01/24 20:45:11  scott
% same
%
% Revision 1.186  2004/01/24 20:42:05  scott
% same
%
% Revision 1.185  2004/01/24 20:40:23  scott
% plotting sorting window
%
% Revision 1.184  2003/12/17 21:42:13  scott
% adjust same
%
% Revision 1.183  2003/12/17 21:40:12  scott
% change y-labels on traces
%
% Revision 1.182  2003/12/04 17:53:52  arno
% debug spec()
%
% Revision 1.181  2003/12/03 02:18:48  arno
% use spec if psd is absent
%
% Revision 1.180  2003/11/26 18:16:23  scott
% help msg
%
% Revision 1.179  2003/11/19 01:06:22  arno
% including makehanning function
%
% Revision 1.178  2003/11/16 17:48:00  scott
% plot1erp() -> plot1trace(); printf "Done."
%
% Revision 1.177  2003/11/14 17:01:59  scott
% bootstrap msg
%
% Revision 1.176  2003/11/14 16:58:02  scott
% debug last
%
% Revision 1.175  2003/11/14 16:56:16  scott
% refining erpsig, sig fills
%
% Revision 1.174  2003/11/14 16:44:06  scott
% changed signif fill color
%
% Revision 1.173  2003/11/14 16:34:31  scott
% debug same
%
% Revision 1.172  2003/11/14 16:32:55  scott
% debug same
%
% Revision 1.171  2003/11/14 16:27:27  scott
% fill coher signif limits
%
% Revision 1.170  2003/11/13 02:32:42  scott
% fill the dB signif limits
%
% Revision 1.169  2003/11/13 02:29:51  scott
% debug
%
% Revision 1.168  2003/11/13 02:28:12  scott
% debug
%
% Revision 1.167  2003/11/13 02:26:25  scott
% debug
%
% Revision 1.166  2003/11/13 02:25:29  scott
% debug
%
% Revision 1.165  2003/11/13 02:24:19  scott
% fill amp signif
%
% Revision 1.164  2003/11/13 02:14:16  scott
% same
%
% Revision 1.163  2003/11/13 01:58:10  scott
% same
%
% Revision 1.162  2003/11/13 01:47:13  scott
% make erpalpha fill less saturated
%
% Revision 1.161  2003/11/10 23:40:32  scott
% fill the bootstrap limits behind the erp if erpalpha
%
% Revision 1.160  2003/11/10 16:57:46  arno
% msg typo
%
% Revision 1.159  2003/10/29 22:15:52  scott
% adjust erp alpha NBOOT to (low) alpha
%
% Revision 1.158  2003/10/29 22:07:10  arno
% nothing
%
% Revision 1.157  2003/09/24 19:36:19  scott
% fixed auxvar bug
%
% Revision 1.156  2003/09/24 18:56:22  scott
% debug
%
% Revision 1.155  2003/09/24 00:45:30  scott
% debug same
%
% Revision 1.154  2003/09/24 00:43:15  scott
% debug same
%
% Revision 1.153  2003/09/24 00:42:10  scott
% debug same
%
% Revision 1.152  2003/09/24 00:39:05  scott
% adding 'horz' -> horizontal line plotting
%
% Revision 1.151  2003/09/21 21:12:27  scott
% edited comments
%
% Revision 1.150  2003/09/11 22:23:25  scott
% debug same
%
% Revision 1.149  2003/09/11 22:19:49  scott
% made 'plotamps' and 'auxvar' work together
%
% Revision 1.148  2003/09/09 23:26:48  arno
% change && to &
%
% Revision 1.147  2003/09/07 00:41:51  arno
% fixing stdev, do not know why it crashed
%
% Revision 1.146  2003/09/06 22:45:04  scott
% same
%
% Revision 1.145  2003/09/06 22:43:57  scott
% add erpsig output
%
% Revision 1.144  2003/09/06 22:24:55  scott
% debug last, add \n before first printed line "Plotting input...
%
% Revision 1.143  2003/09/06 22:15:23  scott
% adjust auxvar if phase sort or amp sort
%
% Revision 1.142  2003/08/27 17:45:07  scott
% header
%
% Revision 1.141  2003/08/25 22:38:25  scott
% auxvars adjust tests -sm
%
% Revision 1.140  2003/08/24 04:49:01  scott
% help msg
%
% Revision 1.139  2003/08/24 04:38:18  scott
% same
%
% Revision 1.138  2003/08/24 04:37:47  scott
% debug last
%
% Revision 1.137  2003/08/24 04:36:29  scott
% fprintf
%
% Revision 1.136  2003/08/24 04:35:19  scott
% added help for 'erpalpha' -sm
%
% Revision 1.135  2003/08/24 04:27:41  scott
% fprintf adjust
%
% Revision 1.134  2003/08/24 04:25:05  scott