von Mises Distribution Family Function

Estimates the location and scale parameters of the von Mises distribution by maximum likelihood estimation.

Usage

vonmises(llocation = "extlogitlink(min = 0, max = 2*pi)",
         lscale = "loglink", ilocation = NULL, iscale = NULL,
         imethod = 1, zero = NULL)

Arguments

llocation, lscale

Parameter link functions applied to the location $a$ parameter and scale parameter $k$, respectively. See Links for more choices. For $k$, a log link is the default because the parameter is positive.

ilocation

Initial value for the location $a$ parameter. By default, an initial value is chosen internally using imethod. Assigning a value will override the argument imethod.

iscale

Initial value for the scale $k$ parameter. By default, an initial value is chosen internally using imethod. Assigning a value will override the argument imethod.

imethod

An integer with value 1 or 2 which specifies the initialization method. If failure to converge occurs try the other value, or else specify a value for ilocation and iscale.

zero

An integer-valued vector specifying which linear/additive predictors are modelled as intercepts only. The default is none of them. If used, one can choose one value from the set {1,2}. See CommonVGAMffArguments for more information.

Details

The (two-parameter) von Mises is the most commonly used distribution in practice for circular data. It has a density that can be written as $$f(y;a,k) = \frac{\exp[k\cos(y-a)]}{ 2\pi I_0(k)}$$ where $0 \leq y < 2\pi$, $k>0$ is the scale parameter, $a$ is the location parameter, and $I_0(k)$ is the modified Bessel function of order 0 evaluated at $k$. The mean of $Y$ (which is the fitted value) is $a$ and the circular variance is $1 - I_1(k) / I_0(k)$ where $I_1(k)$ is the modified Bessel function of order 1. By default, $\eta_1=\log(a/(2\pi-a))$ and $\eta_2=\log(k)$ for this family function.

Value

An object of class "vglmff" (see vglmff-class). The object is used by modelling functions such as vglm, rrvglm and vgam.

References

Forbes, C., Evans, M., Hastings, N. and Peacock, B. (2011). Statistical Distributions, Hoboken, NJ, USA: John Wiley and Sons, Fourth edition.

Author

T. W. Yee

Note

The response and the fitted values are scaled so that $0\leq y< 2\pi$. The linear/additive predictors are left alone. Fisher scoring is used.

Warning

Numerically, the von Mises can be difficult to fit because of a log-likelihood having multiple maximums. The user is therefore encouraged to try different starting values, i.e., make use of ilocation and iscale.

Examples

vdata <- data.frame(x2 = runif(nn <- 1000))
vdata <- transform(vdata,
                   y = rnorm(nn, 2+x2, exp(0.2)))  # Bad data!!
fit <- vglm(y  ~ x2, vonmises(zero = 2), vdata, trace = TRUE)
#> Iteration 1: loglikelihood = 253.45854
#> Iteration 2: loglikelihood = 254.3956
#> Iteration 3: loglikelihood = 254.39575
#> Iteration 4: loglikelihood = 254.39575
coef(fit, matrix = TRUE)
#>             extlogitlink(location, min = 0, max = 6.28318530717959)
#> (Intercept)                                              -0.7886798
#> x2                                                        0.7555448
#>             loglink(scale)
#> (Intercept)      0.1147673
#> x2               0.0000000
Coef(fit)
#> (Intercept):1 (Intercept):2            x2 
#>    -0.7886798     0.1147673     0.7555448 
with(vdata, range(y))  # Original data
#> [1] -2.177470  5.976995
range(depvar(fit))     # Processed data is in [0,2*pi)
#> [1] 0.003213038 6.263874838