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}\), \[\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\)).
Distribution statement
y ~ von_mises(mu, kappa)
Increment target log probability density with von_mises_lupdf(y | mu, kappa).
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.
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.
real von_mises_cdf(reals y | reals mu, reals kappa)
The von mises cumulative distribution function of y given location mu and scale kappa.
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.
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.
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.
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));
}