Circular Distributions

Circular distributions are defined for finite values y in any interval of length $2\pi$.

Von Mises distribution

Probability density function

If $\mu \in \mathbb{R}$ and $\kappa \in {\mathbb{R}}^{+}$, then for $y\in \mathbb{R}$, $$\text{VonMises}(y|\mu ,\kappa )=\frac{\exp (\kappa \cos (y-\mu ))}{2\pi I_0(\kappa )}.$$ In order for this density to properly normalize, $y$ must be restricted to some interval $(c,c+2\pi )$ of length $2\pi$, because $${\int }_c^{c+2\pi }\text{VonMises}(y|\mu ,\kappa )dy=1.$$ Similarly, if $\mu$ is a parameter, it will typically be restricted to the same range as $y$.

If $\kappa >0$, a von Mises distribution with its $2\pi$ interval of support centered around its location $\mu$ will have a single mode at $\mu$; for example, restricting $y$ to $(-\pi ,\pi )$ and taking $\mu =0$ leads to a single local optimum at the mode $\mu$. If the location $\mu$ is not in the center of the support, the density is circularly translated and there will be a second local maximum at the boundary furthest from the mode. Ideally, the parameterization and support will be set up so that the bulk of the probability mass is in a continuous interval around the mean $\mu$.

For $\kappa =0$, the Von Mises distribution corresponds to the circular uniform distribution with density $1/(2\pi )$ (independently of the values of $y$ or $\mu$).

Distribution statement

y ~ von_mises(mu, kappa)

Increment target log probability density with von_mises_lupdf(y | mu, kappa).

Available since 2.0

Stan functions

real von_mises_lpdf(reals y | reals mu, reals kappa)
The log of the von mises density of y given location mu and scale kappa.

Available since 2.18

real von_mises_lupdf(reals y | reals mu, reals kappa)
The log of the von mises density of y given location mu and scale kappa dropping constant additive terms.

Available since 2.25

real von_mises_cdf(reals y | reals mu, reals kappa)
The von mises cumulative distribution function of y given location mu and scale kappa.

Available since 2.29

real von_mises_lcdf(reals y | reals mu, reals kappa)
The log of the von mises cumulative distribution function of y given location mu and scale kappa.

Available since 2.29

real von_mises_lccdf(reals y | reals mu, reals kappa)
The log of the von mises complementary cumulative distribution function of y given location mu and scale kappa.

Available since 2.29

R von_mises_rng(reals mu, reals kappa)
Generate a Von Mises variate with location mu and scale kappa (i.e. returns values in the interval $[(\mu \mathrm{mod}2\pi )-\pi ,(\mu \mathrm{mod}2\pi )+\pi ]$); may only be used in transformed data and generated quantities blocks. For a description of argument and return types, see section vectorized PRNG functions.

Available since 2.18

Numerical stability

Evaluating the Von Mises distribution for $\kappa >100$ is numerically unstable in the current implementation. Nathanael I. Lichti suggested the following workaround on the Stan users group, based on the fact that as $\kappa \to \mathrm{\infty }$, $$\text{VonMises}(y|\mu ,\kappa )\to \text{Normal}(\mu ,\sqrt{1/\kappa }).$$ The workaround is to replace y ~ von_mises(mu,kappa) with

if (kappa < 100) {
  y ~ von_mises(mu, kappa);
} else {
  y ~ normal(mu, sqrt(1 / kappa));
}