Home > FMAToolbox > Analyses > MTSpectrogram.m

MTSpectrogram

PURPOSE ^

MTSpectrogram - Compute LFP spectrogram by multi-taper estimation.

SYNOPSIS ^

function [spectrogram,t,f] = MTSpectrogram(lfp,varargin)

DESCRIPTION ^

MTSpectrogram - Compute LFP spectrogram by multi-taper estimation.

  The spectrogram is computed using the <a href="http://www.chronux.org">chronux</a> toolbox.

  USAGE

    [spectrogram,t,f] = MTSpectrogram(lfp,<options>)

    lfp            unfiltered LFP <a href="matlab:help samples">samples</a> (one channel).
    <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 mtspecgramc">mtspecgramc</a>) (default = 0)
     'show'        plot spectrogram (default = 'off')
     'cutoffs'     cutoff values for color plot (default = [0 13])
    =========================================================================

  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 spectra can be supplied
    either as a 'step' (explicit time difference) or as an 'overlap' (between
    successive time windows).

  OUTPUT

    spectrogram    time-frequency matrix
    t              time bins
    f              frequency bins

  DEPENDENCIES

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

  SEE

    See also MTSpectrum, SpectrogramBands, MTCoherence, MTCoherogram, PlotColorMap.

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SOURCE CODE ^

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