-------------------------------------------------------------------------------
help for circsummarize
-------------------------------------------------------------------------------

Summary statistics for circular data

        circsummarize varlist [weight] [if exp] [in range] [, ci level(#)
                 rayleigh kuiper detail ]

        circsummarize varname [weight] [if exp] [in range] [, by(byvar) ci
                 level(#) rayleigh kuiper detail ]

    fweights and aweights are allowed; see help weights.  If weights are
    specified, they are used in calculating the mean direction and the vector
    strength (and hence the Rayleigh test and confidence limits if produced,
    although this may not be justifiable). Weights are not used in
    calculating the circular range or the Kuiper test.

    The abbreviation circsu (only) is allowed.


Description

    circsummarize produces summary statistics for circular variables with
    scales between 0 and 360 degrees. These are by default

        the mean direction (in degrees),

        the vector strength or mean resultant length (i.e.  length of
        resultant / number of observations)

        and the circular range (length of smallest arc including all
        observations) (in degrees).

    Suppose we have n measurements of a circular variable t.  Then calculate
    in turn
        C = SUM cos t
        S = SUM sin t
        arctan(S / C), the mean direction
        R = sqrt(C * C + S * S), the length of the resultant vector
        R / n, the vector strength or mean resultant length.


Options

    by() specifies that results are to be shown for each group defined by
        values of byvar. This option is only available if a single varname is
        specified.

    ci produces a confidence interval for the vector mean suitable for large
        samples (at least 25 values, say). This is based on an assumption
        that sampling variation follows a normal distribution.  If we
        calculate further

            m_2 = (1 / n) SUM cos 2(t - vector mean of t),

        then the circular standard error CSE is estimated by

            sqrt[ n * (1 - m_2) / (2 * R * R)

        and the confidence interval is estimated as

            (vector mean - arcsin(z * CSE), vector mean + arcsin(z * CSE)),

        where z is the appropriate percentage point, given level(), from the
        Normal distribution with mean 0 and standard deviation 1.

    level() specifies the confidence level in percent for the confidence
        interval. See help for ci.

    rayleigh produces the Rayleigh test, which tests a null hypothesis of
        uniformity against an alternative hypothesis of unimodality.  The
        resulting P-value is shown.

    kuiper produces the Kuiper test, which tests a null hypothesis of
        uniformity against any alternative. The resulting P-value is shown.
        A numerical approximation due to Stephens (1970, p.118) is used that
        gives accuracy to 3 decimal places for P < 0.447.

    detail is a synonym for ci rayleigh kuiper.


Examples

    . circsummarize axisasp wallasp

    . circsummarize wallasp, by(grade) detail


References 

    Fisher, N.I. 1993. Statistical analysis of circular data. Cambridge:
        Cambridge University Press.

    Stephens, M.A. 1970. Use of the Kolmogorov-Smirnov, Cramér-von Mises and
        related statistics without extensive tables.  Journal, Royal
        Statistical Society Series B 32: 115-22.


Author

    Nicholas J. Cox, University of Durham, U.K.
    n.j.cox@durham.ac.uk


Also see

    On-line:  help for ci