23.1 Von Mises distribution

23.1.1 Probability density function

If $$\mu \in \mathbb{R}$$ and $$\kappa \in \mathbb{R}^+$$, then for $$y \in \mathbb{R}$$, $\begin{equation*} \text{VonMises}(y|\mu,\kappa) = \frac{\exp(\kappa\cos(y-\mu))}{2\pi I_0(\kappa)} \!. \end{equation*}$ In order for this density to properly normalize, $$y$$ must be restricted to some interval $$(c, c + 2\pi)$$ of length $$2 \pi$$, because $\begin{equation*} \int_{c}^{c + 2\pi} \text{VonMises}(y|\mu,\kappa) dy = 1. \end{equation*}$ 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$$).

23.1.2 Sampling statement

y ~ von_mises(mu, kappa)

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

23.1.3 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 \mod 2\pi)-\pi,(\mu \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

23.1.4 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 \rightarrow \infty$$, $\begin{equation*} \text{VonMises}(y|\mu,\kappa) \rightarrow \text{Normal}(\mu, \sqrt{1 / \kappa}). \end{equation*}$ 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));
}