-------------------------------------------------------------------------------
help for egencirc
-------------------------------------------------------------------------------

Extensions to generate (circular functions)

        egen [type] newvar = fcn(arguments) [if exp] [in range] [, options]


Description

    egen creates newvar of the optionally specified storage type equal to
    fcn(arguments).  Depending on fcn(), arguments, if present, refers to an
    expression, varlist, or a numlist and the options are similarly fcn
    dependent.

    This help file documents various user-written egen functions for use with
    circular variables, usually measured on a scale from 0 to 360 degrees.


egen functions

    atan2(sinevar cosinevar) [ , radians ] returns the arctangent of two
        variables sinevar and cosinevar as a angle in the range 0 to 360
        degrees.  The option radians specifies that the results should be in
        radians.

    invvm(exp) [, kappa(#) tol(#) log radians ] returns the inverse
        distribution function (quantile function) of a variable following a
        von Mises distribution with vector mean zero and concentration
        parameter specified by the kappa() option as angles in the range -180
        to 180 degrees, and as a function of an expression giving cumulative
        probabilities and so taking values between 0 and 1.  If kappa() is
        not specified, the function looks for r(kappa), as is left in memory
        by circvm. The quantile function is calculated using the vm()
        function documented below and an algorithm given by Fisher (1993,
        p.53). (Note that the steps of that algorithm should be numbered 1 to
        4, contrary to early printings of Fisher 1993.) The default tolerance
        for that algorithm is 1e-6. This may be varied by the tol() option.
        The log option may be used to see a display of the maximum error of
        approximation as the algorithm proceeds, as a check on convergence.
        tol and log() are technical options and are rarely used.  The option
        radians specifies that the results should be in radians.

    rndvm(), [, kappa(#) mu(#) radians ] returns a random sample from a von
        Mises distribution with vector mean specified by the mu() option and
        concentration parameter specified by the kappa() option, as angles in
        the range 0 to 360 degrees. Note that no argument is required or
        allowed.  If mu() is not specified, the function looks for
        r(vecmean), as is left in memory by circvm; if that is not found, a
        value of 0 is assumed.  Any argument of mu() should be in degrees.
        If kappa() is not specified, the function looks for r(kappa), as is
        left in memory by circvm. The random sample is calculated using an
        algorithm introduced by Best and Fisher (1979) and given by Fisher
        (1993, p.49) and Mardia and Jupp (2000, p.43). The option radians
        specifies that the results should be in radians.

    vm(varname), [, kappa(#) mu(#) radians ] returns the cumulative
        distribution function of a von Mises distribution with vector mean
        specified by the mu() option and concentration parameter specified by
        the kappa() option, given angles in the range 0 to 360 degrees.  If
        mu() is not specified, the function looks for r(vecmean), as is left
        in memory by circvm; if that is not found, a value of 0 is assumed.
        Any argument of mu() should be in degrees, unless the radians option
        is also specified.  If kappa() is not specified, the function looks
        for r(kappa), as is left in memory by circvm. The distribution
        function is calculated using an algorithm discussed and implemented
        in Fortran by Hill (1976, 1977), using choices of constants to ensure
        accuracy to 8 decimal places (see Hill 1977, p.280).  The option
        radians specifies that the inputs are in radians.

    vmden(varname) [, kappa(#) mu(#) radians ] returns the density function
        of a von Mises distribution with vector mean specified by the mu()
        option and concentration parameter specified by the kappa() option,
        given angles in the range 0 to 360 degrees.  If mu() is not
        specified, the function looks for r(vecmean), as is left in memory by
        circvm; if that is not found, a value of 0 is assumed.  Any argument
        of mu() should be in degrees, unless the radians option is also
        specified.  If kappa() is not specified, the function looks for
        r(kappa), as is left in memory by circvm.  The option radians
        specifies that the inputs are in radians.


Remarks 
   
    invvm() and vmden() use the calculator function i0kappa.


Examples

    . egen angle = atan2(sine cosine)

    . circvm wallasp
    . egen rndvm = rndvm()
    . egen Fvm = vm(wallasp)
    . egen vmden = vmden(wallasp)


Author 

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


References

    Best, D.J. and Fisher, N.I. 1979.  Efficient simulation of the von Mises
        distribution.  Applied Statistics 28: 152--157.

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

    Hill, G.W. 1976. New approximations to the von Mises distribution.
        Biometrika 63: 673--676. (Erratum 1997, 64: 655.)

    Hill, G.W. 1977. ALGORITHM 518: Incomplete Bessel function I_0:  the von
        Mises distribution. ACM Transactions on Mathematical Software 3:
        279--284.

    Mardia, K.V. and Jupp, P.E. 2000. Directional statistics.  Chichester:
        John Wiley.


Also see

    Manual:  [R] egen