CV - Compute coefficient of variation for a point process.
Three alternative measures can be computed: regular CV, CV in operational time
(Gestri and Petracchi, 1970; Nawrot et al., 2008) or CV2 (Holt et al., 2006).
While the CV is typically computed for consecutive events, it can also be
applied to intervals between events i and i+2 (order 2), or between events
i and i+3 (order 3), etc. to study higher order variability.
Although operational time is a useful concept, in practice the estimate of CV
strongly depends on the estimated instantaneous frequency of the point process
(here, instantaneous frequency is estimated using an adaptive kernel filtering
method, see <a href="matlab:help Frequency">Frequency</a>). Use this measure with care.
USAGE
[coeff,local] = CV(timestamps,<options>)
timestamps point process
<options> optional list of property-value pairs (see table below)
=========================================================================
Properties Values
-------------------------------------------------------------------------
'measure' either 'cv' (default), 'cvo' (operational time) or 'cv2'
'order' interval order (default = 1)
'method' to estimate instantaneous frequency (default = 'fixed')
'binSize' to estimate instantaneous frequency (default = 0.001 s)
'smooth' to estimate instantaneous frequency (default = 25)
=========================================================================
OUTPUT
coeff (mean) coefficient of variation
local time-dependent coefficient of variation (CV2 only)0001 function [coeff,local] = CV(timestamps,varargin) 0002 0003 %CV - Compute coefficient of variation for a point process. 0004 % 0005 % Three alternative measures can be computed: regular CV, CV in operational time 0006 % (Gestri and Petracchi, 1970; Nawrot et al., 2008) or CV2 (Holt et al., 2006). 0007 % 0008 % While the CV is typically computed for consecutive events, it can also be 0009 % applied to intervals between events i and i+2 (order 2), or between events 0010 % i and i+3 (order 3), etc. to study higher order variability. 0011 % 0012 % Although operational time is a useful concept, in practice the estimate of CV 0013 % strongly depends on the estimated instantaneous frequency of the point process 0014 % (here, instantaneous frequency is estimated using an adaptive kernel filtering 0015 % method, see <a href="matlab:help Frequency">Frequency</a>). Use this measure with care. 0016 % 0017 % USAGE 0018 % 0019 % [coeff,local] = CV(timestamps,<options>) 0020 % 0021 % timestamps point process 0022 % <options> optional list of property-value pairs (see table below) 0023 % 0024 % ========================================================================= 0025 % Properties Values 0026 % ------------------------------------------------------------------------- 0027 % 'measure' either 'cv' (default), 'cvo' (operational time) or 'cv2' 0028 % 'order' interval order (default = 1) 0029 % 'method' to estimate instantaneous frequency (default = 'fixed') 0030 % 'binSize' to estimate instantaneous frequency (default = 0.001 s) 0031 % 'smooth' to estimate instantaneous frequency (default = 25) 0032 % ========================================================================= 0033 % 0034 % OUTPUT 0035 % 0036 % coeff (mean) coefficient of variation 0037 % local time-dependent coefficient of variation (CV2 only) 0038 % 0039 0040 % Copyright (C) 2010-2011 by Michaël Zugaro 0041 % 0042 % This program is free software; you can redistribute it and/or modify 0043 % it under the terms of the GNU General Public License as published by 0044 % the Free Software Foundation; either version 3 of the License, or 0045 % (at your option) any later version. 0046 0047 % Defaults 0048 measure = 'cv'; 0049 binSize = 0.001; 0050 smooth = 25; 0051 order = 1; 0052 method = 'fixed'; 0053 0054 % Check parameters 0055 if nargin < 1, 0056 error('Incorrect number of parameters (type ''help <a href="matlab:help CV">CV</a>'' for details).'); 0057 end 0058 if ~isdvector(timestamps), 0059 error('Incorrect timestamps (type ''help <a href="matlab:help CV">CV</a>'' for details).'); 0060 end 0061 0062 % Parse parameter list 0063 for i = 1:2:length(varargin), 0064 if ~ischar(varargin{i}), 0065 error(['Parameter ' num2str(i+1) ' is not a property (type ''help <a href="matlab:help CV">CV</a>'' for details).']); 0066 end 0067 switch(lower(varargin{i})), 0068 case 'measure', 0069 measure = lower(varargin{i+1}); 0070 if ~isastring(measure,'cv','cv2','cvo'), 0071 error('Incorrect value for property ''measure'' (type ''help <a href="matlab:help CV">CV</a>'' for details).'); 0072 end 0073 case 'method', 0074 method = lower(varargin{i+1}); 0075 if ~isastring(method,'fixed','adaptive','inverse'), 0076 error('Incorrect value for property ''method'' (type ''help <a href="matlab:help CV">CV</a>'' for details).'); 0077 end 0078 case 'order', 0079 order = varargin{i+1}; 0080 if ~isiscalar(order,'>0'), 0081 error('Incorrect value for property ''order'' (type ''help <a href="matlab:help CV">CV</a>'' for details).'); 0082 end 0083 case 'binsize', 0084 binSize = varargin{i+1}; 0085 if ~isdscalar(binSize,'>0'), 0086 error('Incorrect value for property ''binSize'' (type ''help <a href="matlab:help CV">CV</a>'' for details).'); 0087 end 0088 case 'smooth', 0089 smooth = varargin{i+1}; 0090 if ~isdscalar(smooth,'>=0'), 0091 error('Incorrect value for property ''smooth'' (type ''help <a href="matlab:help CV">CV</a>'' for details).'); 0092 end 0093 otherwise, 0094 error(['Unknown property ''' num2str(varargin{i}) ''' (type ''help <a href="matlab:help CV">CV</a>'' for details).']); 0095 end 0096 end 0097 0098 switch(measure), 0099 case 'cv', 0100 dt = ndiff(timestamps,order); 0101 coeff = std(dt)/mean(dt); 0102 local = []; 0103 case 'cvo', 0104 % Operational time 0105 % 1) Compute instantaneous frequency by adaptive filtering 0106 frequency = Frequency(timestamps,'binSize',binSize,'smooth',smooth,'method',method); 0107 % 2) Integrate frequency to yield operational time 0108 operational = [frequency(:,1) cumsum(frequency(:,2))*binSize]; 0109 operational = Interpolate(operational,timestamps); 0110 operational = operational(:,2)+timestamps(1)-operational(1,2); 0111 dto = ndiff(operational,order); 0112 coeff = std(dto)/mean(dto); 0113 local = []; 0114 case 'cv2', 0115 dt = ndiff(timestamps,order); 0116 dt1 = dt(1:end-1); 0117 dt2 = dt(2:end); 0118 x = dt1./dt2; % ratio of consecutive iter-event intervals 0119 local = 2*abs(x-1)./(x+1); 0120 coeff = mean(local); 0121 end 0122 0123 function y = ndiff(x,n) 0124 0125 if n == 1, 0126 y = diff(x); 0127 else 0128 y = x((n+1):end)-x(1:end-n); 0129 end