-------------------------------------------------------------------------------
help for circdpvm
-------------------------------------------------------------------------------

Density probability plot for von Mises distribution fitted to circular data

        circdpvm varname [if exp] [in range] [ , a(#) param(numlist)
                 generate(newvar1 newvar2) line(line_options) graph_options ]


Description

    circdpvm gives a density probability plot for the fit of a von Mises
    (a.k.a. circular normal) distribution to a circular variable on a scale
    between 0 and 360 degrees. By default circvm is used to fit the
    distribution, estimating the two parameters vector mean mu and
    concentration parameter kappa. Both observed and expected densities are
    rotated so that each set is centred on the vector mean.  Each is
    nevertheless labelled in terms of varname.


Remarks

    To establish notation, and to fix ideas with a concrete example: consider
    an observed variable theta, whose distribution we wish to compare with a
    von Mises distributed variable phi. That variable has density function
    f(phi), distribution function P = F(phi) and quantile function Q(P).
    (The distribution function and the quantile function are inverses of each
    other.) Clearly, this notation is fairly general and also covers other
    distributions, at least for continuous variables.

    The particular density function f(theta | parameters) most pertinent to
    comparison with data for phi can be computed given values for its
    parameters, either estimates from data on theta, or parameter values
    chosen for some other good reason. In the case of a von Mises
    distribution, these parameters would usually be the vector mean and the
    concentration parameter kappa.

    The density function can also be computed indirectly via the quantile
    function as f(Q(P)). In the case of von Mises distributions, it is
    convenient to centre variables at the vector mean, so that P = 0.5
    corresponds to the vector mean.  In practice P is calculated as so-called
    plotting positions p_i attached to values of a sample of size n which
    have rank i.  One simple rule uses p_i = (i - 0.5) / n.  Most other rules
    follow one of a family (i - a) / (n - 2a + 1) indexed by a.

    Plotting both f(theta | parameters) and f(Q(P = p_i)), calculated using
    plotting positions, versus observed theta gives two curves. In our
    example, the first is von Mises by construction and the second would be a
    good estimate of a von Mises density if theta were truly von Mises with
    the same parameters. The match or mismatch between the curves allows
    graphical assessment of goodness or badness of fit. What is more, we can
    use experience from comparing frequency distributions, as shown on
    histograms, dot plots or other similar displays, in comparing or
    identifying location and scale differences, skewness, tail weight, tied
    values, gaps, outliers and so forth.

    Such density probability plots were suggested by Jones and Daly (1995).
    See also Jones (2004). For further discussion see dpplot.


Options

    a() specifies a family of plotting positions, as explained above. The
        default is 0.5. Choice of a is rarely material unless the sample size
        is very small, and then the exercise is moot whatever is done.

    param() specifies two parameter values which give an alternative
        reference distribution. The first is the vector mean and the second
        is the concentration parameter kappa. (By default these parameters
        are estimated from the data.)

    generate() specifies two new variable names to hold the results of
        densities estimated from the data directly (as f() given parameters)
        and indirectly (as f(Q(P)) given parameters).

    line(line_options) are options of twoway mspline and twoway line, which
        may be used to control the rendition of the density function curve.

    show() specifies a numlist of axis labels to be shown, overriding the
        default.

    graph_options are options of twoway.


Examples

    . circdpvm wallasp
 
    . circdpvm wallasp, show(0(45)315)


References

    Jones, M.C. 2004. Hazelton, M.L. (2003), "A graphical tool for assessing
        normality," The American Statistician 57: 285-288: Comment. The
        American Statistician 58: 176-177.

    Jones, M.C. and F. Daly. 1995. Density probability plots.  Communications
        in Statistics, Simulation and Computation 24: 911-927.


Author

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


Also see

    On-line: help for circvm, circpvm, dpplot (if installed)