rotasym (version 1.0-5)

vMF: von Mises--Fisher distribution

Description

Density and simulation of the von Mises--Fisher (vMF) distribution on \(S^{p-1}:=\{\mathbf{x}\in R^p:||\mathbf{x}||=1\}\), \(p\ge 1\). The density at \(\mathbf{x} \in S^{p-1}\) is given by $$c^{\mathrm{vMF}}_{p,\kappa} e^{\kappa\mathbf{x}' \boldsymbol{\mu}} \quad\mathrm{with}\quad c^{\mathrm{vMF}}_{p,\kappa}:= \kappa^{(p-2)/2}/((2\pi)^{p/2} I_{(p-2)/2}(\kappa))$$ where \(\boldsymbol{\mu}\in S^{p-1}\) is the directional mean, \(\kappa\ge 0\) is the concentration parameter about \(\boldsymbol{\mu}\), and \(I_\nu\) is the order-\(\nu\) modified Bessel function of the first kind.

The angular function of the vMF is \(g(t) := e^{\kappa t}\). The associated cosines density is \(\tilde g(v):= \omega_{p-1} c^{\mathrm{vMF}}_{p,\kappa} g(v) (1 - v^2)^{(p-3)/2}\), where \(\omega_{p-1}\) is the surface area of \(S^{p-2}\).

Usage

d_vMF(x, mu, kappa, log = FALSE)
c_vMF(p, kappa, log = FALSE)
r_vMF(n, mu, kappa)
g_vMF(t, p, kappa, scaled = TRUE, log = FALSE)
r_g_vMF(n, p, kappa)

Arguments

x

locations in \(S^{p-1}\) to evaluate the density. Either a matrix of size c(nx, p) or a vector of length p. Normalized internally if required (with a warning message).

mu

the directional mean \(\boldsymbol{\mu}\) of the vMF. A unit-norm vector of length p.

kappa

concentration parameter \(\kappa\) of the vMF. A nonnegative scalar.

log

flag to indicate if the logarithm of the density (or the normalizing constant) is to be computed.

p

dimension of the ambient space \(R^p\) that contains \(S^{p-1}\). A positive integer.

n

sample size, a positive integer.

t

a vector with values in \([-1, 1]\).

scaled

whether to scale the angular function by the von Mises--Fisher normalizing constant. Defaults to TRUE.

Value

Depending on the function:

• d_vMF: a vector of length nx or 1 with the evaluated density at x.

• r_vMF: a matrix of size c(n, p) with the random sample.

• c_vMF: the normalizing constant.

• g_vMF: a vector of size length(t) with the evaluated angular function.

• r_g_vMF: a vector of length n containing simulated values from the cosines density associated to the angular function.

Details

r_g_vMF implements algorithm VM in Wood (1994). c_vMF is vectorized on p and kappa.

References

Wood, A. T. A. (1994) Simulation of the von Mises Fisher distribution. Commun. Stat. Simulat., 23(1):157--164.

See Also

tangent-vMF.

Examples

# NOT RUN {
# Simulation and density evaluation for p = 2
mu <- c(0, 1)
kappa <- 2
n <- 1e3
x <- r_vMF(n = n, mu = mu, kappa = kappa)
col <- viridisLite::viridis(n)
r <- runif(n, 0.95, 1.05) # Radius perturbation to improve visualization
plot(r * x, pch = 16, col = col[rank(d_vMF(x = x, mu = mu, kappa = kappa))])

# Simulation and density evaluation for p = 3
mu <- c(0, 0, 1)
kappa <- 2
x <- r_vMF(n = n, mu = mu, kappa = kappa)
rgl::plot3d(x, col = col[rank(d_vMF(x = x, mu = mu, kappa = kappa))],
            size = 5)

# Cosines density
g_tilde <- function(t, p, kappa) {
  exp(w_p(p = p - 1, log = TRUE) +
        g_vMF(t = t, p = p, kappa = kappa, scaled = TRUE, log = TRUE) +
        ((p - 3) / 2) * log(1 - t^2))
}

# Simulated data from the cosines density
n <- 1e3
p <- 3
kappa <- 2
hist(r_g_vMF(n = n, p = p, kappa = kappa), breaks = seq(-1, 1, l = 20),
     probability = TRUE, main = "Simulated data from g_vMF", xlab = "t")
t <- seq(-1, 1, by = 0.01)
lines(t, g_tilde(t = t, p = p, kappa = kappa))

# Cosine density as a function of the dimension
M <- 100
col <- viridisLite::viridis(M)
plot(t, g_tilde(t = t, p = 2, kappa = kappa), col = col[2], type = "l",
     ylab = "Density")
for (p in 3:M) {
  lines(t, g_tilde(t = t, p = p, kappa = kappa), col = col[p])
}
# }