movMF_distribution {movMF}

Mixtures of von Mises-Fisher Distributions

Description

Density and random number generation for finite mixtures of von Mises-Fisher distributions.

Usage

dmovMF(x, theta, alpha = 1, log = FALSE)
rmovMF(n, theta, alpha = 1)

Arguments

x

a matrix of rows of points on the unit hypersphere. Standardized to unit row length if necessary.

theta

a matrix with rows giving the parameters of the mixture components.

alpha

a numeric vector with non-negative elements giving the mixture probabilities. Standardized to sum to one if necessary.

log

a logical; if TRUE log-densities are computed.

n

an integer giving the number of samples to draw.

Details

A random d-dimensional unit length vector x has a von Mises-Fisher (or Langevin, short: vMF) distribution with parameter \theta if its density with respect to the uniform distribution on the unit hypersphere is given by

f(x|\theta) = \exp(\theta'x) / {}_0F_1(; d/2; \|\theta\|^2/4),

where {}_0F_1 is a generalized hypergeometric function (e.g., https://en.wikipedia.org/wiki/Generalized_hypergeometric_function) and related to the modified Bessel function I_\nu of the first kind via

{}_0F_1(; \nu+1; z^2/4) = I_\nu(z)\Gamma(\nu+1) / (z/2)^\nu.

With this parametrization, the von Mises-Fisher family is the natural exponential family through the uniform distribution on the unit sphere, with cumulant transform

M(\theta) = \log({}_0F_1(; d/2; \|\theta\|^2/4)).

We note that the vMF distribution is commonly parametrized by the mean direction parameter \mu = \theta / \|\theta\| (which however is not well-defined if \theta = 0) and the concentration parameter \kappa = \|\theta\|, e.g., https://en.wikipedia.org/wiki/Von_Mises%E2%80%93Fisher_distribution (which also uses the un-normalized Haar measure on the unit sphere as the reference distribution, and hence includes the “area” of the unit sphere as an additional normalizing constant).

dmovMF computes the (log) density of mixtures of vMF distributions.

rmovMF generates samples from finite mixtures of vMF distributions, using Algorithm VM* in Wood (1994) for sampling from the vMF distribution.

Arguments theta and alpha are recycled to a common number of mixture components.

Value

For dmovMF, a numeric vector of (log) density values.

For rmovMF, a matrix with n unit length rows representing the samples from the vMF mixture distribution.

References

A. T. A. Wood (1994). Simulation of the von Mises Fisher distribution. Communications in Statistics – Simulation and Computation, 23(1), 157–164.

Examples

## To simulate from the vMF distribution with mean direction
## proportional to c(1, -1) and concentration parameter 3:
rmovMF(10, 3 * c(1, -1) / sqrt(2))
## To simulate from a mixture of vMF distributions with mean direction
## parameters c(1, 0) and c(0, 1), concentration parameters 3 and 4, and
## mixture probabilities 1/3 and 2/3, respectively:
rmovMF(10, c(3, 4) * rbind(c(1, 0), c(0, 1)), c(1, 2))