rotasym (version 1.0-6)

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_{p,\kappa }^{\mathrm{vMF}}{e}^{\kappa {\mathbf{x}}^{\prime }\mathit{\mu }}\mathrm{with}{c}_{p,\kappa }^{\mathrm{vMF}}:={\kappa }^{(p-2)/2}/((2\pi {)}^{p/2}{I}_{(p-2)/2}(\kappa ))$$ where $\mathit{\mu }\in S^{p-1}$ is the directional mean, $\kappa \ge 0$ is the concentration parameter about $\mathit{\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}_{p,\kappa }^{\mathrm{vMF}}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 $\mathit{\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])
}
# }