ShortTimeCCG

ShortTimeCCG - Time-varying auto/cross-correlograms of point processes.

 Determine how xcorrelograms vary in time, i.e. repeatedly compute xcorrelogram
 over successive short time windows.

  USAGE

    [ccg,bins,time] = ShortTimeCCG(times1,times2,<options>)

    times1         first (reference) list of timestamps (in s)
    times2         optional second list of timestamps (in s)
    <options>      optional list of property-value pairs (see table below)

    =========================================================================
     Properties    Values
    -------------------------------------------------------------------------
     'binSize'     bin size in s (default = 0.01)
     'duration'    duration (in s) of each xcorrelogram (default = 2)
     'window'      duration (in s) of the time window over which each
                   xcorrelogram is computed (default = 5*60)
     'overlap'     overlap between successive windows (default = 0.8*window)
     'smooth'      standard deviation for Gaussian kernel (default 0, no
                   smoothing)
     'mode'        'counts' yields raw event counts (default), and 'norm'
                   normalizes each xcorrelogram to yield a probability
                   distribution
     'min'         discard time windows with fewer events than this threshold
                   (default = 1)
    =========================================================================

  OUTPUT

    ccg            MxN matrix, where each column is a xcorrelogram and each line
                   is a time bin
    bins           time bins for xcorrelograms
    time           time

  SEE

    See also CCG, PlotShortTimeCCG.

0001 function [ccg,x,y] = ShortTimeCCG(times1,times2,varargin)
0002 
0003 %ShortTimeCCG - Time-varying auto/cross-correlograms of point processes.
0004 %
0005 % Determine how xcorrelograms vary in time, i.e. repeatedly compute xcorrelogram
0006 % over successive short time windows.
0007 %
0008 %  USAGE
0009 %
0010 %    [ccg,bins,time] = ShortTimeCCG(times1,times2,<options>)
0011 %
0012 %    times1         first (reference) list of timestamps (in s)
0013 %    times2         optional second list of timestamps (in s)
0014 %    <options>      optional list of property-value pairs (see table below)
0015 %
0016 %    =========================================================================
0017 %     Properties    Values
0018 %    -------------------------------------------------------------------------
0019 %     'binSize'     bin size in s (default = 0.01)
0020 %     'duration'    duration (in s) of each xcorrelogram (default = 2)
0021 %     'window'      duration (in s) of the time window over which each
0022 %                   xcorrelogram is computed (default = 5*60)
0023 %     'overlap'     overlap between successive windows (default = 0.8*window)
0024 %     'smooth'      standard deviation for Gaussian kernel (default 0, no
0025 %                   smoothing)
0026 %     'mode'        'counts' yields raw event counts (default), and 'norm'
0027 %                   normalizes each xcorrelogram to yield a probability
0028 %                   distribution
0029 %     'min'         discard time windows with fewer events than this threshold
0030 %                   (default = 1)
0031 %    =========================================================================
0032 %
0033 %  OUTPUT
0034 %
0035 %    ccg            MxN matrix, where each column is a xcorrelogram and each line
0036 %                   is a time bin
0037 %    bins           time bins for xcorrelograms
0038 %    time           time
0039 %
0040 %  SEE
0041 %
0042 %    See also CCG, PlotShortTimeCCG.
0043 
0044 % Copyright (C) 2011 by Michaël Zugaro
0045 %
0046 % This program is free software; you can redistribute it and/or modify
0047 % it under the terms of the GNU General Public License as published by
0048 % the Free Software Foundation; either version 3 of the License, or
0049 % (at your option) any later version.
0050 
0051 % cross/auto correlogram?
0052 auto = 0;
0053 
0054 % Check parameter sizes
0055 if nargin < 1,
0056   error('Incorrect number of parameters (type ''help <a href="matlab:help ShortTimeCCG">ShortTimeCCG</a>'' for details).');
0057 end
0058 if nargin >= 2 && isa(times2,'char'),
0059     % Only one point process => autocorrelogram
0060     varargin = {times2,varargin{:}};
0061     times2 = times1;
0062     auto = 1;
0063 end
0064 if ~isvector(times1) || ~isvector(times2) || isempty(times1) || isempty(times2),
0065     error('Parameters ''times1'' and ''time2'' must be non-empty vectors (type ''help <a href="matlab:help ShortTimeCCG">ShortTimeCCG</a>'' for details).');
0066 end
0067 
0068 % Default values
0069 binSize = 0.01;
0070 duration = 2;
0071 window = 5*60;
0072 overlap = [];
0073 mode = 'count';
0074 smooth = [];
0075 minEvents = 1;
0076 
0077 % Parse parameter list
0078 for i = 1:2:length(varargin),
0079     if ~ischar(varargin{i}),
0080         error(['Parameter ' num2str(i+2) ' is not a property (type ''help <a href="matlab:help ShortTimeCCG">ShortTimeCCG</a>'' for details).']);
0081     end
0082     switch(lower(varargin{i})),
0083 
0084         case 'binsize',
0085             binSize = varargin{i+1};
0086             if ~isdscalar(binSize,'>0'),
0087                 error('Incorrect value for property ''binSize'' (type ''help <a href="matlab:help ShortTimeCCG">ShortTimeCCG</a>'' for details).');
0088             end
0089 
0090         case 'duration',
0091             duration = varargin{i+1};
0092             if ~isdscalar(duration,'>0'),
0093                 error('Incorrect value for property ''duration'' (type ''help <a href="matlab:help ShortTimeCCG">ShortTimeCCG</a>'' for details).');
0094             end
0095 
0096         case 'window',
0097             window = varargin{i+1};
0098             if ~isdscalar(window,'>0'),
0099                 error('Incorrect value for property ''window'' (type ''help <a href="matlab:help ShortTimeCCG">ShortTimeCCG</a>'' for details).');
0100             end
0101 
0102         case 'overlap',
0103             overlap = varargin{i+1};
0104             if ~isdscalar(overlap,'>0'),
0105                 error('Incorrect value for property ''overlap'' (type ''help <a href="matlab:help ShortTimeCCG">ShortTimeCCG</a>'' for details).');
0106             end
0107 
0108         case 'mode',
0109             mode = lower(varargin{i+1});
0110             if ~isastring(mode,'norm','count'),
0111                 error('Incorrect value for property ''mode'' (type ''help <a href="matlab:help ShortTimeCCG">ShortTimeCCG</a>'' for details).');
0112             end
0113 
0114         case 'smooth',
0115             smooth = varargin{i+1};
0116             if ~isdvector(smooth,'>=0') | length(smooth) > 2,
0117             error('Incorrect value for property ''smooth'' (type ''help <a href="matlab:help ShortTimeCCG">ShortTimeCCG</a>'' for details).');
0118             end
0119 
0120         case 'min',
0121             minEvents = varargin{i+1};
0122             if ~isiscalar(minEvents,'>=0'),
0123                 error('Incorrect value for property ''min'' (type ''help <a href="matlab:help ShortTimeCCG">ShortTimeCCG</a>'' for details).');
0124             end
0125 
0126         otherwise,
0127             error(['Unknown property ''' num2str(varargin{i}) ''' (type ''help <a href="matlab:help ShortTimeCCG">ShortTimeCCG</a>'' for details).']);
0128 
0129   end
0130 end
0131 
0132 % Default overlap?
0133 if isempty(overlap), overlap = 0.8*window; end
0134 
0135 % Get ready...
0136 start = min([times1(1) times2(1)]+window/2);
0137 stop = max([times1(end) times2(end)]-window/2);
0138 times1 = times1(:);
0139 times2 = times2(:);
0140 times = [times1;times2];
0141 groups = 1+[zeros(size(times1));ones(size(times2))];
0142 halfBins = round(duration/binSize/2);
0143 
0144 % Loop through data
0145 i = 1;
0146 t = start;
0147 ccg = [];
0148 while t+window/2 <= stop,
0149     x(i,1) = t;
0150     ok = InIntervals(times,t+[-0.5 0.5]*window);
0151     if sum(ok) < minEvents,
0152         ccg(1:(2*halfBins+1),i) = nan;
0153     else
0154         out = CCG(times(ok),groups(ok),'binSize',binSize,'duration',duration);
0155         if auto,
0156             ccg(:,i) = out(:,1,1);
0157         else
0158             ccg(:,i) = out(:,1,2);
0159         end
0160     end
0161     t = t + window - overlap;
0162     i = i + 1;
0163 end
0164 
0165 y = (-duration/2:binSize:duration/2)';
0166 
0167 % Remove center bin for autocorrelograms
0168 if auto,
0169     center = ceil(size(ccg,1)/2);
0170     ccg(center,:) = 0;
0171 end
0172 
0173 % Normalize?
0174 if strcmp(mode,'norm'),
0175     ccg = ccg ./ repmat(sum(ccg,1),size(ccg,1),1);
0176 end
0177 
0178 % Smooth?
0179 if ~isempty(smooth),
0180     ccg = Smooth(ccg,smooth);
0181 end