PlotCircularDistribution

PlotCircularDistribution - Plot phase distribution and statistics.

  Plot one or more phase distributions as histograms and polar plots
  showing circular mean and resultant length. Dotted vectors indicate
  that the data is not significantly clustered around a single peak
  (Rayleigh test, alpha > 0.05).

  USAGE

    PlotCircularDistribution(dist,angles,stats)

    dist           phase distribution(s) (obtained using <a href="matlab:help CircularDistribution">CircularDistribution</a>)
    angles         optional centers of the angular bins
    stats          optional distribution statistics
    <options>      optional list of property-value pairs (see table below)

    =========================================================================
     Properties    Values
    -------------------------------------------------------------------------
     'mode'        one plot for all distributions ('grouped', default) or
                   one per distribution ('separate')
    =========================================================================

  SEE

    See also CircularDistribution.

0001 function PlotCircularDistribution(dist,a,s,varargin)
0002 
0003 %PlotCircularDistribution - Plot phase distribution and statistics.
0004 %
0005 %  Plot one or more phase distributions as histograms and polar plots
0006 %  showing circular mean and resultant length. Dotted vectors indicate
0007 %  that the data is not significantly clustered around a single peak
0008 %  (Rayleigh test, alpha > 0.05).
0009 %
0010 %  USAGE
0011 %
0012 %    PlotCircularDistribution(dist,angles,stats)
0013 %
0014 %    dist           phase distribution(s) (obtained using <a href="matlab:help CircularDistribution">CircularDistribution</a>)
0015 %    angles         optional centers of the angular bins
0016 %    stats          optional distribution statistics
0017 %    <options>      optional list of property-value pairs (see table below)
0018 %
0019 %    =========================================================================
0020 %     Properties    Values
0021 %    -------------------------------------------------------------------------
0022 %     'mode'        one plot for all distributions ('grouped', default) or
0023 %                   one per distribution ('separate')
0024 %    =========================================================================
0025 %
0026 %  SEE
0027 %
0028 %    See also CircularDistribution.
0029 
0030 % Copyright (C) 2011 by Michaël Zugaro
0031 %
0032 % This program is free software; you can redistribute it and/or modify
0033 % it under the terms of the GNU General Public License as published by
0034 % the Free Software Foundation; either version 3 of the License, or
0035 % (at your option) any later version.
0036 
0037 mode = 'grouped';
0038 v = varargin;
0039 
0040 % Check number of parameters
0041 if nargin < 1,
0042   error('Incorrect number of parameters (type ''help <a href="matlab:help PlotCircularDistribution">PlotCircularDistribution</a>'' for details).');
0043 end
0044 
0045 % Check parameter size
0046 if ~isdvector(dist) && ~isdmatrix(dist),
0047     error('Incorrect distributions (type ''help <a href="matlab:help PlotCircularDistribution">PlotCircularDistribution</a>'' for details).');
0048 end
0049 
0050 % Stats provided?
0051 if nargin >= 3 && ~isstruct(s),
0052     v = {s,varargin{:}};
0053 end
0054 if nargin < 3 || ~isstruct(s),
0055     stats = [];
0056 else
0057     stats = s;
0058 end
0059 
0060 % Angles provided?
0061 if nargin >= 2 && ischar(a),
0062     v = {a,s,varargin{:}};
0063 end
0064 if nargin < 2 || ischar(a),
0065     angles = linspace(0,2*pi,size(dist,1)+1)';angles(end) = [];
0066     binSize = angles(2)-angles(1);
0067     angles = angles + binSize/2;
0068 else
0069     angles = a;
0070 end
0071 
0072 varargin = v;
0073 
0074 % Parse parameter list
0075 for i = 1:2:length(varargin),
0076     if ~ischar(varargin{i}),
0077         error(['Parameter ' num2str(i+2) ' is not a property (type ''help <a href="matlab:help PlotCircularDistribution">PlotCircularDistribution</a>'' for details).']);
0078     end
0079     switch(lower(varargin{i})),
0080         case 'mode',
0081             mode = lower(varargin{i+1});
0082             if ~isastring(mode,'separate','grouped'),
0083                 error('Incorrect value for property ''mode'' (type ''help <a href="matlab:help PlotCircularDistribution">PlotCircularDistribution</a>'' for details).');
0084             end
0085         otherwise,
0086             error(['Unknown property ''' num2str(varargin{i}) ''' (type ''help <a href="matlab:help PlotCircularDistribution">PlotCircularDistribution</a>'' for details).']);
0087     end
0088 end
0089 
0090 nGroups = size(dist,2);
0091 color = Bright(nGroups);
0092 
0093 % Plot histograms (or curves) for each group
0094 M = 0; % max y axis value
0095 for i = 1:nGroups,
0096     h = dist(:,i);
0097     if nGroups == 1,
0098         subplot(1,2,1); hold on;
0099         bar([angles;angles+2*pi],[h;h],1,'EdgeColor','none','FaceColor','b');
0100     else
0101         if strcmp(mode,'grouped'),
0102             subplot(1,2,1);
0103         else
0104             subplot(2,nGroups,i);
0105         end
0106         hold on;
0107         plot([angles;angles+2*pi],[h;h],'color',color(i,:));
0108     end
0109     m = ylim;m = m(2);
0110     M = max([m M]);
0111 end
0112 % Adjust axes and labels, plot sinewave
0113 if strcmp(mode,'separate'),
0114     m = 2;
0115     n = nGroups;
0116     N = nGroups;
0117 else
0118     m = 1;
0119     n = 2;
0120     N = 1;
0121 end
0122 for i = 1:N,
0123     subplot(m,n,i);
0124     xlim([0 4*pi]);
0125     x = linspace(0,4*pi,600);
0126     a = M/4;
0127     y = a*cos(x)+M+a;
0128     plot(x,y,'r','linewidth',2);
0129     xlabel('Angle (rad)');
0130     ylabel('Probability');
0131 end
0132 
0133 % Show statistics for each group
0134 for i = 1:nGroups,
0135     if strcmp(mode,'grouped'),
0136         subplot(1,2,2);
0137     else
0138         subplot(2,nGroups,i+nGroups);
0139     end
0140     hold on;
0141     h = dist(:,i);
0142     p = polar([angles;angles(1)],[h;h(1)]);
0143     set(p,'color',color(i,:));
0144     if ~isempty(stats),
0145         c = compass(stats.r(i)*cos(stats.m(i)),stats.r(i)*sin(stats.m(i)));
0146         set(c,'color',color(i,:));
0147         if stats.p(i) > 0.05, set(c,'linestyle',':'); end
0148     end
0149 end
0150 for i = 1:N,
0151     subplot(m,n,i+N);
0152     axis square;
0153     plot([-M M],[0 0],'k:');
0154     plot([0 0],[-M M],'k:');
0155     xlim([-M M]);ylim([-M M]);
0156     set(gca,'xtick',[],'ytick',[],'box','on');
0157     if i == 1,
0158         xlabel('Circular Mean and Resultant Length');
0159     end
0160 end