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.

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

The implementation follows in most cases 'Biostatistical Analysis' and all referenced equations and tables are taken from this book, if not otherwise noted. In some cases, the other two books were preferred for implementation was more straightforward for solutions presented there.

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

Disclaimer:
All functions in this toolbox were implemented with care and tested on the examples presented in 'Biostatistical Analysis' were possible. Nevertheless, they may contain errors or bugs, which may affect the outcome of your analysis. We do not take responsibility for any harm coming from using this toolbox, neither if it is caused by errors in the software nor if it is caused by its improper application. Please email us any bugs you find.

By Philipp Berens and Marc J. Velasco, 2009
[e-mail] , [e-mail] - www.kyb.mpg.de/~berens/circStat.html
Distributed under Open Source BSD License

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,
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.