CircularDistribution - Compute circular distribution and statistics.
USAGE
[dist,binned,stats] = CircularDistribution(angles,<options>)
angles angles in radians
<options> optional list of property-value pairs (see table below)
=========================================================================
Properties Values
-------------------------------------------------------------------------
'nBins' number of bins (default = 100)
'smooth' standard deviation of Gaussian kernel (default = 0)
'groups' groups for multiple circular distributions (see below)
=========================================================================
OUTPUT
dist circular distribution (one column per group)
binned centers of the angular bins
stats.m mean angle (one per group)
stats.mode distribution mode (one per group)
stats.r mean resultant length (one per group)
stats.k concentration (one per group)
stats.p p-value for Rayleigh test (one per group)
NOTE
For multiple circular distributions, groups can be indicated in two different
manners:
- a vector of group IDs (one per angle)
- a logical matrix (one line per angle, one column per group), where
the element (i,j) is 1 iff angle i belongs to group j
The vector form is convenient when each angle can only belong to one group.
The matrix form is useful when a single angle can belong to multiple groups.
SEE
See also PlotCircularDistribution.0001 function [dist,binned,stats] = CircularDistribution(angles,varargin) 0002 0003 %CircularDistribution - Compute circular distribution and statistics. 0004 % 0005 % USAGE 0006 % 0007 % [dist,binned,stats] = CircularDistribution(angles,<options>) 0008 % 0009 % angles angles in radians 0010 % <options> optional list of property-value pairs (see table below) 0011 % 0012 % ========================================================================= 0013 % Properties Values 0014 % ------------------------------------------------------------------------- 0015 % 'nBins' number of bins (default = 100) 0016 % 'smooth' standard deviation of Gaussian kernel (default = 0) 0017 % 'groups' groups for multiple circular distributions (see below) 0018 % ========================================================================= 0019 % 0020 % OUTPUT 0021 % 0022 % dist circular distribution (one column per group) 0023 % binned centers of the angular bins 0024 % stats.m mean angle (one per group) 0025 % stats.mode distribution mode (one per group) 0026 % stats.r mean resultant length (one per group) 0027 % stats.k concentration (one per group) 0028 % stats.p p-value for Rayleigh test (one per group) 0029 % 0030 % NOTE 0031 % 0032 % For multiple circular distributions, groups can be indicated in two different 0033 % manners: 0034 % 0035 % - a vector of group IDs (one per angle) 0036 % - a logical matrix (one line per angle, one column per group), where 0037 % the element (i,j) is 1 iff angle i belongs to group j 0038 % 0039 % The vector form is convenient when each angle can only belong to one group. 0040 % The matrix form is useful when a single angle can belong to multiple groups. 0041 % 0042 % SEE 0043 % 0044 % See also PlotCircularDistribution. 0045 0046 % Copyright (C) 2011-2012 by Michaël Zugaro 0047 % 0048 % This program is free software; you can redistribute it and/or modify 0049 % it under the terms of the GNU General Public License as published by 0050 % the Free Software Foundation; either version 3 of the License, or 0051 % (at your option) any later version. 0052 0053 % Default values 0054 nBins = 100; 0055 smooth = 0; 0056 0057 % Check number of parameters 0058 if nargin < 1 | mod(length(varargin),2) ~= 0, 0059 error('Incorrect number of parameters (type ''help <a href="matlab:help CircularDistribution">CircularDistribution</a>'' for details).'); 0060 end 0061 0062 % Check parameter size 0063 if ~isdvector(angles), 0064 error('Incorrect angles (type ''help <a href="matlab:help CircularDistribution">CircularDistribution</a>'' for details).'); 0065 end 0066 angles = angles(:); 0067 groups = ones(size(angles)); 0068 0069 % Parse parameter list 0070 for i = 1:2:length(varargin), 0071 if ~ischar(varargin{i}), 0072 error(['Parameter ' num2str(i+2) ' is not a property (type ''help <a href="matlab:help CircularDistribution">CircularDistribution</a>'' for details).']); 0073 end 0074 switch(lower(varargin{i})), 0075 case 'nbins', 0076 nBins = varargin{i+1}; 0077 if ~isiscalar(nBins,'>0'), 0078 error('Incorrect value for property ''nBins'' (type ''help <a href="matlab:help CircularDistribution">CircularDistribution</a>'' for details).'); 0079 end 0080 case 'smooth', 0081 smooth = varargin{i+1}; 0082 if ~isdscalar(smooth,'>=0'), 0083 error('Incorrect value for property ''smooth'' (type ''help <a href="matlab:help CircularDistribution">CircularDistribution</a>'' for details).'); 0084 end 0085 case 'groups', 0086 groups = varargin{i+1}; 0087 if ~isdvector(groups,'>0') && ~islmatrix(groups), 0088 error('Incorrect value for property ''groups'' (type ''help <a href="matlab:help CircularDistribution">CircularDistribution</a>'' for details).'); 0089 end 0090 if isdvector(groups), groups = groups(:); end 0091 if length(angles) ~= size(groups,1), 0092 error('Phases and groups have different numbers of lines (type ''help <a href="matlab:help CircularDistribution">CircularDistribution</a>'' for details).'); 0093 end 0094 otherwise, 0095 error(['Unknown property ''' num2str(varargin{i}) ''' (type ''help <a href="matlab:help CircularDistribution">CircularDistribution</a>'' for details).']); 0096 end 0097 end 0098 0099 % Angle bins 0100 binned = linspace(0,2*pi,nBins+1)';binned(end) = []; 0101 binSize = binned(2)-binned(1); 0102 binned = binned + binSize/2; 0103 0104 % Groups: transform vector form into matrix form 0105 if isdvector(groups), 0106 groupIDs = unique(groups); 0107 nGroups = max(groupIDs); 0108 g = groups; 0109 groups = logical(zeros(length(g),nGroups)); 0110 for i = 1:nGroups, 0111 groups(g==i,i) = 1; 0112 end 0113 end 0114 0115 % Loop through groups 0116 nGroups = size(groups,2); 0117 for i = 1:nGroups, 0118 % Distribution 0119 p = angles(groups(:,i)); 0120 h = Smooth(hist(p,binned),smooth);h = h/sum(h); 0121 dist(:,i) = h; 0122 % Stats 0123 [stats.m(i),stats.r(i)] = CircularMean(p); 0124 stats.k(i) = Concentration(p); 0125 n = sum(groups(:,i)); 0126 R = stats.r(i)*n; 0127 stats.p(i) = exp(sqrt(1+4*n+4*(n^2-R^2))-(1+2*n)); % Zar, Biostatistical Analysis, p. 617 0128 x = find(h==max(h));x = x(1); 0129 stats.mode(i) = binned(x); 0130 end 0131