RunningAverage

RunningAverage - Compute running linear or angular average.

 Computes the running average of y=f(x). Variable y can be linear or circular
 (use radians). The error bars are standard errors of the mean for linear
 data, or 95% confidence intervals for circular data.

  USAGE

    [x,m,e] = RunningAverage(x,y,<options>)

    x              x variable (e.g., time)
    y              values at x
    <options>      optional list of property-value pairs (see table below)

    =========================================================================
     Properties    Values
    -------------------------------------------------------------------------
     'window'      averaging window size (default (max-min)/10)
     'overlap'     overlap between successive windows (default = 0.8*window)
     'limits'      x limits to use instead of min and max
     'type'        either 'linear' or 'circular' (default 'linear')
    =========================================================================

  OUTPUT

    x              new x variable
    m              running average
    e              sem for linear variables, otherwise 95% confidence intervals

0001 function [x,m,e] = RunningAverage(X,Y,varargin)
0002 
0003 %RunningAverage - Compute running linear or angular average.
0004 %
0005 % Computes the running average of y=f(x). Variable y can be linear or circular
0006 % (use radians). The error bars are standard errors of the mean for linear
0007 % data, or 95% confidence intervals for circular data.
0008 %
0009 %  USAGE
0010 %
0011 %    [x,m,e] = RunningAverage(x,y,<options>)
0012 %
0013 %    x              x variable (e.g., time)
0014 %    y              values at x
0015 %    <options>      optional list of property-value pairs (see table below)
0016 %
0017 %    =========================================================================
0018 %     Properties    Values
0019 %    -------------------------------------------------------------------------
0020 %     'window'      averaging window size (default (max-min)/10)
0021 %     'overlap'     overlap between successive windows (default = 0.8*window)
0022 %     'limits'      x limits to use instead of min and max
0023 %     'type'        either 'linear' or 'circular' (default 'linear')
0024 %    =========================================================================
0025 %
0026 %  OUTPUT
0027 %
0028 %    x              new x variable
0029 %    m              running average
0030 %    e              sem for linear variables, otherwise 95% confidence intervals
0031 
0032 % Copyright (C) 2004-2011 by Michaël Zugaro
0033 %
0034 % This program is free software; you can redistribute it and/or modify
0035 % it under the terms of the GNU General Public License as published by
0036 % the Free Software Foundation; either version 3 of the License, or
0037 % (at your option) any later version.
0038 
0039 % Default values
0040 type = 'linear';
0041 limits = [min(X) max(X)];
0042 nBins = 10;
0043 window = 0;
0044 overlap = [];
0045 
0046 if nargin < 2 | mod(length(varargin),2) ~= 0,
0047   error('Incorrect number of parameters (type ''help <a href="matlab:help RunningAverage">RunningAverage</a>'' for details).');
0048 end
0049 
0050 % Parse parameter list
0051 for i = 1:2:length(varargin),
0052     if ~ischar(varargin{i}),
0053         error(['Parameter ' num2str(i+2) ' is not a property (type ''help <a href="matlab:help RunningAverage">RunningAverage</a>'' for details).']);
0054     end
0055     switch(lower(varargin{i})),
0056         case 'type',
0057             type = varargin{i+1};
0058             if ~isastring(type,'linear','circular'),
0059                 error('Incorrect value for property ''type'' (type ''help <a href="matlab:help RunningAverage">RunningAverage</a>'' for details).');
0060             end
0061 
0062         case 'window',
0063             window = varargin{i+1};
0064             if ~isdscalar(window,'>0'),
0065                 error('Incorrect value for property ''window'' (type ''help <a href="matlab:help RunningAverage">RunningAverage</a>'' for details).');
0066             end
0067 
0068         case 'overlap',
0069             overlap = varargin{i+1};
0070             if ~isdscalar(overlap,'>=0'),
0071                 error('Incorrect value for property ''overlap'' (type ''help <a href="matlab:help RunningAverage">RunningAverage</a>'' for details).');
0072             end
0073 
0074         case 'limits',
0075             limits = varargin{i+1};
0076             if ~isdvector(limits,'#2','<'),
0077                 error('Incorrect value for property ''limits'' (type ''help <a href="matlab:help RunningAverage">RunningAverage</a>'' for details).');
0078             end
0079 
0080         otherwise,
0081             error(['Unknown property ''' num2str(varargin{i}) ''' (type ''help <a href="matlab:help RunningAverage">RunningAverage</a>'' for details).']);
0082 
0083     end
0084 end
0085 
0086 x0 = limits(1);
0087 x1 = limits(2);
0088 if window == 0,
0089     window = (x1-x0)/nBins;
0090 end
0091 if isempty(overlap),
0092     overlap = 0.8*window;
0093 end
0094 
0095 % Loop through data
0096 i = 1;
0097 xi = x0+window/2;
0098 while xi+window/2 <= x1,
0099     x(i,1) = xi;
0100     ok = InIntervals(X,xi+[-0.5 0.5]*window);
0101     if sum(ok) == 0,
0102         m(i,1) = NaN;
0103         e(i,:) = [NaN NaN];
0104     elseif strcmp(type,'circular'),
0105         [M,C] = CircularConfidenceIntervals(Y(ok));
0106         m(i,1) = M;
0107         e(i,:) = C;
0108     else
0109         m(i,1) = nanmean(Y(ok));
0110         n = sum(ok);
0111         s = nanstd(Y(ok))/sqrt(n);
0112         e(i,1) = m(i)-s;
0113         e(i,2) = m(i)+s;
0114     end
0115     xi = xi + window - overlap;
0116     i = i + 1;
0117 end