Circular Statistics Toolbox (Directional Statistics)

Compute descriptive and inferential statistics for circular or directional data.

Description

CircStat for Matlab
=======================

Toolbox for circular statistics with Matlab.

Authors: Philipp Berens & Marc J. Velasco
Email: [e-mail]
Homepage: http://www.kyb.tuebingen.mpg.de/~berens/circStat.html

Contributors:
Tal Krasovsky

Reference:
P. Berens, CircStat: A Matlab Toolbox for Circular Statistics, Journal of Statistical Software, Volume 31, Issue 10, 2009
http://www.jstatsoft.org/v31/i10

Please cite this paper when the provided code is used. See licensing terms for details.

Contents:
circ_r Resultant vector length
circ_mean Mean direction of a sample of circular data
circ_axial Mean direction for axial data
circ_median Median direction of a sample of circular data
circ_std Dispersion around the mean direction (std, mardia)
circ_var Circular variance
circ_skewness Circular skewness
circ_kurtosis Circular kurtosis
circ_moment Circular p-th moment
circ_dist Distances around a circle
circ_dist2 Pairwise distances around a circle
circ_confmean Confidence intervals for mean direction
circ_stats Summary statistics

circ_rtest Rayleigh's test for nonuniformity
circ_otest Hodges-Ajne test (omnibus test) for nonuniformity
circ_raotest Rao's spacing test for nonuniformity
circ_vtest V-Test for nonuniformity with known mean direction
circ_medtest Test for median angle
circ_mtest One-sample test for specified mean direction
circ_wwtest Multi-sample test for equal means, one-factor ANOVA
circ_hktest Two-factor ANOVA
circ_ktest Test for equal concentration parameter
circ_symtest Test for symmetry around median angle
circ_kuipertest Test whether two distributions are identical (like KS test)

circ_corrcc Circular-circular correlation coefficient
circ_corrcl Circular-linear correlation coefficient

circ_kappa Compute concentration parameter of a vm distribution

circ_plot Visualization for circular data
circ_clust Simple clustering for circular data
circ_samplecdf Evaluate CDF of a sample of angles

rad2ang Convert radian to angular values
ang2rad Convert angular to radian values

All functions take arguments in radians (expect for ang2rad). For a detailed description of arguments and outputs consult the help text in the files.

Since 2010, most functions for descriptive statistics can be used in Matlab style matrix computations. As a last argument, add the dimension along which you want to average. This changes the behavior slightly from previous relaeses, in that input is not reshaped anymore into vector format. Per default, all computations are performed columnwise (along dimension 1). If you prefer to use the old functions, for now they are contained in the subdirectory 'old'.

References:
- E. Batschelet, Circular Statistics in Biology, Academic Press, 1981
- N.I. Fisher, Statistical analysis of circular data, Cambridge University Press, 1996
- S.R. Jammalamadaka et al., Topics in circular statistics, World Scientific, 2001
- J.H. Zar, Biostatistical Analysis, Prentice Hall, 1999

If you have suggestions, bugs or feature requests or want to contribute code, please email us.

Acknowledgements

The author wishes to acknowledge the following in the creation of this submission:
Circular Cross Correlation

• Required Products: Statistics Toolbox
• MATLAB release: MATLAB 7.5 (R2007b)

Other Files

circ_ang2rad.m,
circ_axial.m,
circ_axialmean.m,
circ_clust.m,
circ_cmtest.m,
circ_confmean.m,
circ_corrcc.m,
circ_corrcl.m,
circ_dist.m,
circ_dist2.m,
circ_hktest.m,
circ_kappa.m,
circ_ktest.m,
circ_kuipertest.m,
circ_kurtosis.m,
circ_mean.m,
circ_median.m,
circ_medtest.m,
circ_moment.m,
circ_mtest.m,
circ_otest.m,
circ_plot.m,
circ_r.m,
circ_rad2ang.m,
circ_raotest.m,
circ_rtest.m,
circ_samplecdf.m,
circ_skewness.m,
circ_stats.m,
circ_std.m,
circ_symtest.m,
circ_var.m,
circ_vmpar.m,
circ_vmpdf.m,
circ_vmrnd.m,
circ_vtest.m,
circ_wwtest.m,
Contents.m,
kuipertable.mat,
license.txt,
old/circ_axialmean.m,
old/circ_confmean.m,
old/circ_kurtosis.m,
old/circ_mean.m,
old/circ_median.m,
old/circ_moment.m,
old/circ_r.m,
old/circ_skewness.m,
old/circ_std.m,
old/circ_var.m,
readme.txt

[sanjay sane]

thanks.

[Sooho Park]

Exactly what I needed

[Lyle Muller]

Would include skewness and kurtosis!

[Adrian Bartlett]

I believe I have found an error in one of your functions:
circ_rtest.m
Line 51: z = R^2 / n;
should be
Line 51: z = R^2 * n;

[Adrian B]

I take that back -- guilty of confusing 'r' and 'R'

[Lorenzo Guerrasio]

I wish I saw it before :)
Very nicely done.

[Lorenzo Guerrasio]

PS:
I think there is an error in the circ_dist function

I think this

r = angle(repmat(exp(1i*x(:)'),length(y),1) ...
       ./ repmat(exp(1i*y(:)),1,length(x)));

Let me know if it's correct

[Richard Heitz]

this is a great toolbox

[Tal Krasovsky]

Excellent toolbox, helped me a lot. Greatly appreciated!

[Richard Courtemanche]

This is a great submission, filling an obvious gap in the statistical world out there. Easy to use, well done, and the author provides great feedback.

Great!

[Richard Heitz]

Sorry, but I think circ_var returns s = (1-r) when it should be s = 2*(1-r).

for this reason, circ_std and circ_var will not agree

[Philipp Berens]

Both definitions are around... I will optionally add computing both with the next update.

[Flurin Honegger]

Good work! So far it helped me a lot. But there are some
errors arround!

1.) function circ_hktest

Line 55 found -> qm = zeros(p,1); qr = qm; qn = pm;
   corrected? -> qm = zeros(p,1); qr = qm; qn = qm;

Line 94 found -> eff_2 = sum(qr.^2 ./ sum(cn,2)) - tr.^2/n;
   corrected? -> eff_2 = sum(qr.^2 ./ sum(cn,1)') - tr.^2/n;

Line 107 found -> beta = 1/(1-1/(5*kk)-1/(10*(kk^2)));
       comment -> beta overloads the beta function (help beta)
                  An other name like betaF should be used

Line 144 found -> F1 = beta * ms_1 / ms_r;
       comment -> if inter is set to 0/false beta is not defined!
       
       
2.) function circ_std

The documentation in the paper

  In CircStat , theangular deviation is computed as
  >>s=circ_std(alpha);
  and the circular standard deviation as
  >>s0=circ_std(alpha,[],[],'mardia');
  
does not fit with neither - paper and Matlab Central - implementation.

[Philipp Berens]

Dear Florin,

thanks for the error report.

With regards to 1: Fixed all bugs. I tested the output on the example in Harrison & Kanji.

With regards to 2: This is unfortunate. The current (and more recent) toolbox version returns both, angular deviation and circular standard deviation as first and second return argument.

Appreciate your feedback,

Philipp

[Shiquan Wang]

This is great work! Thanks.

[Shiquan Wang]

bug report:
function stats = circ_stats(alpha, w, d)
line50:stats.std_mardia = circ_std(alpha,w,d,'mardia');
the function circ_std(alpha, w, d) doesn't accept parameter 'mardia'.

[omzaz]

Encountering same issue as Shiquan

[Philipp Berens]

Issue is fixed in the upload of 11/5/09.

[chairmanK]

Functions do not gracefully handle N-dimensional arrays for powerful MATLAB-style computations; instead, inputs are coerced to be column vectors. There are also numerous errors. One example, in circ_moment.m:
cbar = sum(cos(p*alpha'*w))/n;
(p*alpha'*w) is a SCALAR dot product, so clearly this is not a weighted sum of cosines as it ought to be.
There are many other bugs like this. Please fix!

[Cesare]

something's wrong in the new circ_vmpdf....can't replicate results from previous release

[Tomo]

I think, in circ_skewness, the eponent for the denominator of the last equation should be (3/2), rather than (2/3), according to formula (2.29) of Fisher 1993.

[Philipp Berens]

I fixed the bugs reported in December in the first upload of 2010.

I also added the functionality asked for by chairmanK. The functions for descriptive statistics now handle N dimensional arrays and the computations can be performed 'Matlab-style'. As a backup, the new release comes with a folder 'old', which contains the functions that are thus replaced as backup. If you experience problems or issues with the new functions or would like to see additional functions converted let me know. Unused arguments in between can be left empty.

circ_vmpdf seems to work fine with me and produces data with the correct moments. Please be more specific.

[Cesare]

also with the 2010b.
Thanks,
Cesare

[Cesare]

Ops sorry I must have meesed up with the posts....
I'll repost my doubt properly:

Try to run

points = -pi:((4*pi)/(2*Nbin)):3*pi;
mu = -2.838;
kappa = 0.5125;

p = circ_vmpdf(points(1:end-1).', mu, kappa);

It seems to me that results from version circStat2009 (which I think were correct) differ from those of CircStat2009d and CircStat2010b. Maybe I'm doing something wrong. Please let me know.
Thanks a lot,
Cesare

[Philipp Berens]

There has been a slight (and unfortunately undocumented) change in semantics from 2009 to the later versions.

vmpdf computes the density, i.e. it evaluates the probability density function of the von mises distribution at the designated points. The earlier version computed the approximate probability in a small bin with width (alpha(2)-alpha(1) ), as is needed if you want to plot histograms. As you will see, you can easily recover the old behavior by

p = circ_vmpdf(points(1:end-1).', mu, kappa);
p = p * diff(points(1:2));

to obtain approximate probabilities.