crossf.m

Cross frecuency relations

% crossf() - Returns estimates and plots event-related coherence (ERCOH) 
%        between two input data time series (X,Y). A lower panel (optionally) 
%        shows the coherence phase difference between the processes. 
%        In this panel:
%           -90 degrees (blue)   means X leads Y by a quarter cycle.
%            90 degrees (orange) means Y leads X by a quarter cycle.
%        Coherence phase units may be radians, degrees, or msec.
%        Click on any subplot to view separately and zoom in/out.
%
% Function description:
%        Uses EITHER fixed-window, zero-padded FFTs (fastest) OR constant-Q 
%        0-padded wavelet DFTs (more even sensitivity across frequencies), 
%        both Hanning-tapered.  Output frequency spacing is the lowest 
%        frequency ('srate'/'winsize') divided by the 'padratio'.
%
%        If an 'alpha' value is given, then bootstrap statistics are 
%        computed (from a distribution of 'naccu' {200} surrogate baseline
%        data epochs) for the baseline epoch, and non-significant features 
%        of the output plots are zeroed (and shown in green). The baseline
%        epoch is all windows with center latencies < the given 'baseline' 
%        value, or if 'baseboot' is 1, the whole epoch. 
% Usage: 
%        >> [coh,mcoh,timesout,freqsout,cohboot,cohangles] ...
%                       = crossf(X,Y,frames,tlimits,srate,cycles, ...
%                                        'key1', 'val1', 'key2', val2' ...);
% Required inputs:
%       X       = first single-channel data set (1,frames*nepochs)      
%       Y       = second single-channel data set (1,frames*nepochs)     
%       frames  = frames per epoch                                 {default: 750}
%       tlimits = [mintime maxtime] (ms) epoch latency limits {def: [-1000 2000]}
%       srate   = data sampling rate (Hz)                          {default: 250}
%       cycles  = 0  -> Use FFTs (with constant window length) 
%               = >0 -> Number of cycles in each analysis wavelet 
%               = [cycles expfactor] -> if 0 < expfactor < 1,  the number 
%                 of wavelet cycles expands with frequency from cycles
%                 If expfactor = 1, no expansion; if = 0, constant
%                 window length (as in FFT)                          {default: 0}
% Optional Coherence Type:
%       'type'  = ['coher'|'phasecoher'] Compute either linear coherence
%                 ('coher') or phase coherence ('phasecoher') also known
%                 as phase coupling factor' {default: 'phasecoher'}.
%       'subitc' = ['on'|'off'] subtract stimulus locked Inter-Trial Coherence 
%                 from X and Y. This computes the  'intrinsic' coherence
%                 X and Y not arising from common synchronization to 
%                 experimental events. See notes. {default: 'off'}
%       'shuffle' = integer indicating the number of estimates to compute
%                 bootstrap coherence based on shuffled trials. This estimates
%                 the coherence arising only from time locking of X and Y
%                 to experimental events (opposite of 'subitc')      {default: 0}
% Optional Detrend:
%       'detret' = ['on'|'off'], Linearly detrend data within epochs {def: 'off'}
%       'detrep' = ['on'|'off'], Linearly detrend data across trials {def: 'off'}
%
% Optional FFT/DFT:
%       'winsize'  = If cycles==0: data subwindow length (fastest, 2^n<frames);
%                    if cycles >0: *longest* window length to use. This
%                    determines the lowest output frequency  {default: ~frames/8}
%       'timesout' = Number of output latencies (int<frames-winsize)   {def: 200}
%       'padratio' = FFTlength/winsize (2^k)                         {default: 2}
%                    Multiplies the number of output frequencies by
%                    dividing their spacing. When cycles==0, frequency
%                    spacing is (low_frequency/padratio).
%       'maxfreq'  = Maximum frequency (Hz) to plot (& output if cycles>0) 
%                    If cycles==0, all FFT frequencies are output  {default: 50}
%       'baseline' = Coherence baseline end latency (ms). NaN -> No baseline  
%                      {default:NaN}
%       'powbase'  = Baseline spectrum to log-subtract      {default: from data}
%
% Optional Bootstrap:
%       'alpha'    = If non-0, compute two-tailed bootstrap significance prob.
%                    level. Show non-signif output values as green. {def: 0}
%       'naccu'    = Number of bootstrap replications to compute {def: 200}
%       'boottype' = ['times'|'timestrials'] Bootstrap type: Either shuffle
%                    windows ('times') or windows and trials ('timestrials')
%                    Option 'timestrials' requires more memory  {default: 'times'}
%       'memory'   = ['low'|'high'] 'low' -> decrease memory use {default: 'high'}
%       'baseboot' = Extent of bootstrap shuffling (0=to 'baseline'; 1=whole epoch) 
%                    If no baseline is given (NaN), extent of bootstrap shuffling 
%                    is the whole epoch                         {default: 0}
%       'rboot'    = Input bootstrap coherence limits (e.g., from crossf()) 
%                    The bootstrap type should be identical to that used
%                    to obtain the input limits. {default: compute from data}
% Optional Scalp Map:
%       'topovec'  = (2,nchans) matrix, plot scalp maps to plot {default: []}
%                    ELSE (c1,c2), plot two cartoons showing channel locations.
%       'elocs'    = Electrode location structure or file for scalp map  
%                    {default: none}
%       'chaninfo' = Electrode location additional information (nose position...)
%                    {default: none}
%
% Optional Plot and Compute Features:
%       'compute'   = ['matlab'|'c'] Use C subroutines to speed up the
%                     computation (currently unimplemented) {def: 'matlab'}
%       'savecoher' - [0|1] 1 --> Accumulate the individual trial coherence 
%                     vectors; output them as cohangles {default: 0 = off}
%       'plotamp'   = ['on'|'off'], Plot coherence magnitude    {def: 'on'}
%       'maxamp'    = [real] Set the maximum for the amp. scale {def: auto}
%       'plotphase' = ['on'|'off'], Plot coherence phase angle  {def: 'on'}
%       'angleunit' = Phase units: 'ms' -> msec, 'deg' -> degrees,
%                     or 'rad' -> radians                  {default: 'deg'}
%       'title'     = Optional figure title                {default:  none}
%       'vert'      = Latencies to mark with a dotted vertical line 
%                                                           {default: none}
%       'linewidth' = Line width for marktimes traces (thick=2, thin=1) 
%                                                              {default: 2}
%       'cmax'      = Maximum amplitude for color scale  {def: data limits}
%       'axesfont'  = Axes font size                          {default: 10}
%       'titlefont' = Title font size                          {default: 8}
%
% Outputs: 
%       coh         = Matrix (nfreqs,timesout) of coherence magnitudes 
%       mcoh        = Vector of mean baseline coherence at each frequency
%       timesout    = Vector of output latencies (window centers) (ms).
%       freqsout    = Vector of frequency bin centers (Hz).
%       cohboot     = Matrix (nfreqs,2) of [lower;upper] coher signif. limits
%                     if 'boottype' is 'trials',  (nfreqs,timesout, 2)
%       cohangle    = (nfreqs,timesout) matrix of coherence angles (in radians)
%       cohangles   = (nfreqs,timesout,trials) matrix of single-trial coherence 
%                      angles (in radians), saved and output only if 'savecoher',1
%
% Plot description:
%   Assuming both 'plotamp' and 'plotphase' options are 'on' (=default), the upper panel
%   presents the magnitude of either phase coherence or linear coherence, depending on 
%   the 'type' parameter (above). The lower panel presents the coherence phase difference 
%   (in degrees). Click on any plot to pop up a new window (using 'axcopy()').
%   -- The upper left marginal panel shows mean coherence during the baseline period
%      (blue), and when significance is set, the significance threshold (dotted black-green).
%   -- The horizontal panel under the coherence magnitude image indicates the maximum 
%      (green) and minimum (blue) coherence values across all frequencies. When significance 
%      is set (using option 'trials' for 'boottype'), an additional curve indicates the 
%      significance threshold (dotted black-green).
%
% Notes: 1) When cycles==0, nfreqs is total number of FFT frequencies.
%        2) As noted above: 'blue' coherence angle -> X leads Y; 'red' -> Y leads X
%        3) The 'boottype' should be ideally 'timesframes', but this creates high 
%           memory demands, so the 'times' method must be used in many cases.
%        4) If 'boottype' is 'trials', the average of the complex bootstrap
%           is subtracted from the coherence to compensate for phase differences 
%           (the average is also subtracted from the bootstrap distribution). 
%           For other bootstraps, this is not necessary since the phase is random.
%        5) If baseline is non-NaN, the baseline is subtracted from
%           the complex coherence. On the left hand side of the coherence
%           amplitude image, the baseline is displayed as a magenta line
%           (if no baseline is selected, this curve represents the average
%           coherence at every given frequency).
%        6) If a out-of-memory error occurs, set the 'memory' option to 'low'
%           (Makes computation time slower; Only the 'times' bootstrap method 
%           can be used in this mode).
%
% Authors: Arnaud Delorme, Sigurd Enghoff & Scott Makeig
%          CNL/Salk Institute 1998-2001; SCCN/INC/UCSD, La Jolla, 2002-
%
% See also: timef()

% Copyright (C) 8/1/98  Arnaud Delorme, Sigurd Enghoff & Scott Makeig, SCCN/INC/UCSD
%
% 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: crossf.m,v $
% Revision 1.73  2007/03/05 21:41:04  toby
% Document removal of reliance on eventlock.m
%
% Revision 1.72  2006/03/13 23:10:50  arno
% significance masking
%
% Revision 1.71  2005/08/19 18:31:45  scott
% fixed
% bug  ( = Tfx2;)  (thanks to Pierre Herremans); edited commandline printouts -sm
%
% Revision 1.70  2005/05/16 20:40:50  hilit
% changing command order to enable right operation
%
% Revision 1.69  2005/04/22 21:11:46  arno
% alltfx twice
%
% Revision 1.68  2005/04/08 22:56:57  arno
% help msg etc.. for chaninfo
%
% Revision 1.67  2005/04/04 17:14:08  scott
% made 'savecoher' option public
%
% Revision 1.66  2005/04/01 16:04:21  arno
% typo
%
% Revision 1.65  2005/03/29 16:46:32  scott
% added to help ms that Rangle output is in radians
% added option 'rad' to 'angleunit' plotting options
%
% Revision 1.64  2005/03/07 21:24:02  arno
% adding chninfo
%
% Revision 1.63  2003/11/26 18:18:52  scott
% help msg
%
% Revision 1.62  2003/08/05 22:06:49  scott
% header edits
%
% Revision 1.61  2003/08/04 16:22:13  arno
% marginal plot color
%
% Revision 1.60  2003/05/05 16:31:18  arno
% debug last
%
% Revision 1.59  2003/05/05 16:25:24  arno
% debuging FFT freq scale
%
% Revision 1.58  2003/01/31 23:57:08  arno
% debuging plotting title
%
% Revision 1.57  2003/01/06 18:12:15  arno
% shuffle along the 3rd dimension
%
% Revision 1.56  2003/01/02 22:40:43  arno
% updateing linear coherence formulas
%
% Revision 1.55  2003/01/02 19:33:55  arno
% removing reverse angle for wavelet
%
% Revision 1.54  2002/11/15 01:54:52  arno
% header for web
%
% Revision 1.53  2002/11/15 01:45:06  scott
% can not -> cannot
%
% Revision 1.52  2002/10/24 15:08:12  arno
% debugging plot scalp map for channel
%
% Revision 1.51  2002/10/18 16:50:40  arno
% win' -> transpose(win)
%
% Revision 1.50  2002/09/26 00:40:48  arno
% updating header
%
% Revision 1.49  2002/09/12 03:22:44  scott
% help msg -sm
%
% Revision 1.48  2002/08/14 21:06:33  arno
% hanning debug
%
% Revision 1.47  2002/08/14 21:02:54  arno
% implementing hanning funciton
%
% Revision 1.46  2002/08/12 01:48:01  arno
% color
%
% Revision 1.45  2002/08/11 22:30:19  arno
% color
%
% Revision 1.44  2002/08/11 22:28:36  arno
% updating cycles
%
% Revision 1.43  2002/08/09 22:37:32  arno
% debugging cyclefact
%
% Revision 1.42  2002/08/09 22:29:42  arno
% implementing wavelet factor
%
% Revision 1.41  2002/07/26 00:27:56  arno
% significance for all plots
%
% Revision 1.40  2002/07/25 23:05:15  arno
% implementing condition comparison
%
% Revision 1.39  2002/07/16 23:08:25  arno
% correcting freqs for wavelet output
%
% Revision 1.38  2002/07/16 23:00:03  arno
% testing
%
% Revision 1.37  2002/07/16 04:51:07  arno
% *** empty log message ***
%
% Revision 1.36  2002/07/12 23:11:03  arno
% dftfilt->1
%
% Revision 1.35  2002/07/11 20:56:28  arno
% debugging maxamp
%
% Revision 1.34  2002/07/11 18:22:07  arno
% same
%
% Revision 1.33  2002/07/11 18:20:21  arno
% maxamp debug
%
% Revision 1.32  2002/07/11 18:16:00  arno
% implmenting maxamp
%
% Revision 1.31  2002/07/11 17:01:30  arno
% implementing phase coherence 2, speeding up 'coher' and 'phasecoher'
%
% Revision 1.30  2002/07/10 19:12:56  arno
% removing warning messages
%
% Revision 1.29  2002/07/03 23:45:03  arno
% correcting rboot output
%
% Revision 1.28  2002/07/02 21:51:41  scott
% edited help message -sm
%
% Revision 1.27  2002/06/28 17:57:10  arno
% returning coherence magnitudes
%
% Revision 1.26  2002/06/25 22:23:37  arno
% NEW MODULAR VERSION WITH SUBITC
%
% Revision 1.24  2002/05/23 23:33:35  scott
% remove subtraction of mean coherence -sm
%
% Revision 1.23  2002/04/25 02:54:07  arno
% debugging topovec
%
% Revision 1.22  2002/04/25 02:38:12  arno
% change significance (only one sided
%
% Revision 1.21  2002/04/25 02:18:19  arno
% debugging topovec
%
% Revision 1.20  2002/04/24 22:04:49  arno
% debugging error check
%
% Revision 1.19  2002/04/24 21:59:11  arno
% debugging