Home > FMAToolbox > Analyses > MTCoherogram.m

MTCoherogram

PURPOSE ^

MTCoherogram - Compute LFP coherogram by multi-taper estimation.

SYNOPSIS ^

function [coherogram,phase,t,f] = MTCoherogram(lfp1,lfp2,varargin)

DESCRIPTION ^

MTCoherogram - Compute LFP coherogram by multi-taper estimation.

  USAGE

    [coherogram,phase,t,f] = MTCoherogram(lfp1,lfp2,<options>)

    lfp1,lfp2      unfiltered LFP <a href="matlab:help samples">samples</a> (one channel each).
    <options>      optional list of property-value pairs (see table below)

    =========================================================================
     Properties    Values
    -------------------------------------------------------------------------
     'frequency'   sampling rate (in Hz) (default = from timestamps if
                   available, otherwise 1250Hz)
     'range'       frequency range (in Hz) (default = all)
     'window'      duration (in s) of the time window (default = 5)
     'overlap'     overlap between successive windows (default = window/2)
     'step'        step between successive windows (default = window/2)
     'tapers'      relative resolution and order of the tapers [NW K]
                   (default = [3 5])
     'pad'         FFT padding (see help for <a href="matlab:help cohgramc">cohgramc</a>) (default = 0)
     'show'        plot results (default = 'off')
     'cutoffs'     cutoff values for color plot (default = [0 1])
    =========================================================================

  NOTES

    The LFP can be provided either as a time stamped matrix (list of time-voltage
    pairs), or as a voltage vector - in which case the frequency must be specified.

    The time displacement between successive short time coherences can be supplied
    either as a 'step' (explicit time difference) or as an 'overlap' (between
    successive time windows).

  OUTPUT

    coherogram     coherogram magnitude
    phase          coherogram phase
    t              time bins
    f              frequency bins

  DEPENDENCIES

    This function requires the <a href="http://www.chronux.org">chronux</a> toolbox.

  SEE

    See also MTCoherence, MTSpectrum, MTSpectrogram, PlotColorMap.

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SOURCE CODE ^

0001 function [coherogram,phase,t,f] = MTCoherogram(lfp1,lfp2,varargin)
0002 
0003 %MTCoherogram - Compute LFP coherogram by multi-taper estimation.
0004 %
0005 %  USAGE
0006 %
0007 %    [coherogram,phase,t,f] = MTCoherogram(lfp1,lfp2,<options>)
0008 %
0009 %    lfp1,lfp2      unfiltered LFP <a href="matlab:help samples">samples</a> (one channel each).
0010 %    <options>      optional list of property-value pairs (see table below)
0011 %
0012 %    =========================================================================
0013 %     Properties    Values
0014 %    -------------------------------------------------------------------------
0015 %     'frequency'   sampling rate (in Hz) (default = from timestamps if
0016 %                   available, otherwise 1250Hz)
0017 %     'range'       frequency range (in Hz) (default = all)
0018 %     'window'      duration (in s) of the time window (default = 5)
0019 %     'overlap'     overlap between successive windows (default = window/2)
0020 %     'step'        step between successive windows (default = window/2)
0021 %     'tapers'      relative resolution and order of the tapers [NW K]
0022 %                   (default = [3 5])
0023 %     'pad'         FFT padding (see help for <a href="matlab:help cohgramc">cohgramc</a>) (default = 0)
0024 %     'show'        plot results (default = 'off')
0025 %     'cutoffs'     cutoff values for color plot (default = [0 1])
0026 %    =========================================================================
0027 %
0028 %  NOTES
0029 %
0030 %    The LFP can be provided either as a time stamped matrix (list of time-voltage
0031 %    pairs), or as a voltage vector - in which case the frequency must be specified.
0032 %
0033 %    The time displacement between successive short time coherences can be supplied
0034 %    either as a 'step' (explicit time difference) or as an 'overlap' (between
0035 %    successive time windows).
0036 %
0037 %  OUTPUT
0038 %
0039 %    coherogram     coherogram magnitude
0040 %    phase          coherogram phase
0041 %    t              time bins
0042 %    f              frequency bins
0043 %
0044 %  DEPENDENCIES
0045 %
0046 %    This function requires the <a href="http://www.chronux.org">chronux</a> toolbox.
0047 %
0048 %  SEE
0049 %
0050 %    See also MTCoherence, MTSpectrum, MTSpectrogram, PlotColorMap.
0051 
0052 % Copyright (C) 2010-2014 by Michaël Zugaro
0053 %
0054 % This program is free software; you can redistribute it and/or modify
0055 % it under the terms of the GNU General Public License as published by
0056 % the Free Software Foundation; either version 3 of the License, or
0057 % (at your option) any later version.
0058 
0059 % Make sure chronux is installed and functional
0060 CheckChronux('cohgramc');
0061 
0062 % Defaults
0063 f = 1250;
0064 frequency = [];
0065 window = 5;
0066 range = [];
0067 overlap = [];
0068 step = [];
0069 show = 'off';
0070 tapers = [3 5];
0071 pad = 0;
0072 cutoffs = [0 1];
0073 
0074 % Check number of parameters
0075 if nargin < 2 | mod(length(varargin),2) ~= 0,
0076   error('Incorrect number of parameters (type ''help <a href="matlab:help MTCoherogram">MTCoherogram</a>'' for details).');
0077 end
0078 
0079 % Check parameter sizes
0080 if size(lfp1,2) ~= 1 && size(lfp1,2) ~= 2,
0081     error('Parameter ''lfp1'' is not a vector or a Nx2 matrix (type ''help <a href="matlab:help MTCoherogram">MTCoherogram</a>'' for details).');
0082 end
0083 if size(lfp2,2) ~= 1 && size(lfp2,2) ~= 2,
0084     error('Parameter ''lfp2'' is not a vector or a Nx2 matrix (type ''help <a href="matlab:help MTCoherogram">MTCoherogram</a>'' for details).');
0085 end
0086 if any(size(lfp1) ~= size(lfp2)),
0087     error('Parameters ''lfp1'' and ''lfp2'' have different sizes (type ''help <a href="matlab:help MTCoherogram">MTCoherogram</a>'' for details).');
0088 end
0089 
0090 % Parse parameter list
0091 for i = 1:2:length(varargin),
0092     if ~ischar(varargin{i}),
0093         error(['Parameter ' num2str(i+2) ' is not a property (type ''help <a href="matlab:help MTCoherogram">MTCoherogram</a>'' for details).']);
0094     end
0095     switch(lower(varargin{i})),
0096         case 'frequency',
0097             frequency = varargin{i+1};
0098             if ~isdscalar(frequency,'>0'),
0099                 error('Incorrect value for property ''frequency'' (type ''help <a href="matlab:help MTCoherogram">MTCoherogram</a>'' for details).');
0100             end
0101         case 'range',
0102             range = varargin{i+1};
0103             if ~isdvector(range,'#2','<','>=0'),
0104                 error('Incorrect value for property ''range'' (type ''help <a href="matlab:help MTCoherogram">MTCoherogram</a>'' for details).');
0105             end
0106         case 'window',
0107             window = varargin{i+1};
0108             if ~isdscalar(window,'>0'),
0109                 error('Incorrect value for property ''window'' (type ''help <a href="matlab:help MTCoherogram">MTCoherogram</a>'' for details).');
0110             end
0111         case 'overlap',
0112             overlap = varargin{i+1};
0113             if ~isdscalar(overlap,'>0'),
0114                 error('Incorrect value for property ''overlap'' (type ''help <a href="matlab:help MTCoherogram">MTCoherogram</a>'' for details).');
0115             end
0116         case 'step',
0117             step = varargin{i+1};
0118             if ~isdscalar(step,'>0'),
0119                 error('Incorrect value for property ''step'' (type ''help <a href="matlab:help MTCoherogram">MTCoherogram</a>'' for details).');
0120             end
0121         case 'tapers',
0122             tapers = varargin{i+1};
0123             if ~isivector(tapers,'#2','>0'),
0124                 error('Incorrect value for property ''tapers'' (type ''help <a href="matlab:help MTCoherogram">MTCoherogram</a>'' for details).');
0125             end
0126         case 'pad',
0127             pad = varargin{i+1};
0128             if ~isiscalar(pad,'>-1'),
0129                 error('Incorrect value for property ''pad'' (type ''help <a href="matlab:help MTCoherogram">MTCoherogram</a>'' for details).');
0130             end
0131         case 'show',
0132             show = varargin{i+1};
0133             if ~isastring(show,'on','off'),
0134                 error('Incorrect value for property ''show'' (type ''help <a href="matlab:help MTCoherogram">MTCoherogram</a>'' for details).');
0135             end
0136         case 'cutoffs',
0137             cutoffs = varargin{i+1};
0138             if ~isdvector(cutoffs,'#2','>=0','<'),
0139                 error('Incorrect value for property ''cutoffs'' (type ''help <a href="matlab:help MTCoherogram">MTCoherogram</a>'' for details).');
0140             end
0141         otherwise,
0142             error(['Unknown property ''' num2str(varargin{i}) ''' (type ''help <a href="matlab:help MTCoherogram">MTCoherogram</a>'' for details).']);
0143     end
0144 end
0145 
0146 % Make sure both LFPs have the same timestamps
0147 if size(lfp1,2) == 2 && any(lfp1(:,1) ~= lfp2(:,1)),
0148     error(['Parameters ''lfp1'' and ''lfp2'' have different timestamps (type ''help <a href="matlab:help MTCoherogram">MTCoherogram</a>'' for details).']);
0149 end
0150 
0151 % Determine LFP frequency
0152 if isempty(frequency),
0153     if size(lfp1,2) == 2,
0154         frequency = 1/median(diff(lfp1(:,1)));
0155     else
0156         frequency = f;
0157     end
0158 end
0159 
0160 % Determine step/overlap
0161 if isempty(step),
0162     if isempty(overlap),
0163         overlap = window/2;
0164     end
0165 else
0166     if isempty(overlap),
0167         overlap = window-step;
0168     elseif overlap ~= window-step,
0169         error('Incompatible ''step'' and ''overlap'' parameters (type ''help <a href="matlab:help MTCoherogram">MTCoherogram</a>'' for details).');
0170     end
0171 end
0172 
0173 % Compute and plot coherogram
0174 parameters.Fs = frequency;
0175 if ~isempty(range), parameters.fpass = range; end
0176 parameters.tapers = tapers;
0177 parameters.pad = pad;
0178 [coherogram,phase,~,~,~,t,f] = cohgramc(lfp1(:,2),lfp2(:,2),[window window-overlap],parameters);
0179 t = t'+lfp1(1,1);
0180 f = f';
0181 coherogram = coherogram';
0182 
0183 % Check for LFP discontinuities and update t accordingly
0184 gaps = diff(lfp1(:,1)) > 2*nanmedian(diff(lfp1(:,1)));
0185 if any(gaps),    
0186     n = length(lfp1(:,1));
0187     t = interp1(1:n,lfp1(:,1),linspace(1,n,length(t))');
0188 end
0189 
0190 % coherogram = permute(coherogram,[2 1 3]);  % Previous code by Gabrielle Girardeau, keep it around just in case
0191 phase = phase';
0192 if strcmp(lower(show),'on'),
0193     figure;
0194     subplot(2,1,1);
0195     PlotColorMap(coherogram,'x',t,'y',f,'cutoffs',cutoffs);
0196     xlabel('Time (s)');
0197     ylabel('Frequency (Hz)');
0198     title('Coherogram Amplitude');
0199     subplot(2,1,2);
0200     PlotColorMap(phase,'x',t,'y',f,'cutoffs',[-pi pi]);
0201     xlabel('Time (s)');
0202     ylabel('Frequency (Hz)');
0203     title('Coherogram Phase');
0204 end
Generated on Fri 16-Mar-2018 13:00:20 by m2html © 2005