overlap.unif: Overlap calculation for uniform niche regions.

In nicheROVER: Niche Region and Niche Overlap Metrics for Multidimensional Ecological Niches

Overlap calculation for uniform niche regions.

Description

Overlap calculation for uniform niche regions.

Usage

overlap.unif(muA, SigmaA, muB, SigmaB, alphaA = 0.95, alphaB = 0.95, nprob)

overlap.sphere(muA, sigmaA, muB, sigmaB, alphaA = 0.95, alphaB = 0.95)

Arguments

muA, muB	Mean of niche regions.
SigmaA, SigmaB	Variance matrix of elliptical niche regions.
alphaA, alphaB	Probabilistic size of niche regions.
nprob	Number of uniform draws from niche region A.
sigmaA, sigmaB	standard deviations (scalars) of spherical niche regions.

Details

The overlap between niche regions A and B is defined as vol(A \cap B)/vol(A \cup B), where the hypervolume of an n-dimensional region S is vol(S) = \int_S dx. For elliptical niche regions, there are simple formulas for vol(A) and vol(B). Thus, we need only determine the volume of the intersection vol(A \cap B), as the volume of the union is given by the formula vol(A \cup B) = vol(A) + vol(B) - vol(A \cap B).

For spherical niche regions, vol(A \cap B) has a closed-form expression (see 'References'). For elliptical regions, no such formula exists and a Monte Carlo method is used instead. That is, vol(A \cap B) is calculated by sampling uniformly from A, then multiplying vol(A) by the fraction of sampled points which fall into B.

While the uniform overlap metric is invariant to permutation of niche regions A and B, the accuracy of the Monte Carlo calculation of vol(A \cap B) is not: higher accuracy is obtained when a higher fraction of sampled points are in the opposite niche region. overlap.unif() does not attempt to determine for which region this is the case, though the choice can be informed by plotting the niche regions, e.g., with niche.plot().

Value

A Monte Carlo estimate of the niche overlap for overlap.unif(), and an analytic calculation for overlap.sphere().

References

Li, S. "Concise formulas for the area and volume of a hyperspherical cap." Asian Journal of Mathematics & Statistics 4.1 (2011): 66-70. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.3923/ajms.2011.66.70")}.

Examples

# spherical case: compare Monte Carlo method to analytic formula

d <- 2 # 2D example
mA <- rnorm(d)
mB <- rnorm(d)
sigA <- rexp(1)
SigA <- sigA^2 * diag(d)
sigB <- rexp(1)
SigB <- sigB^2 * diag(d)

# plot circles
ellA <- ellipse(mA, SigA)
ellB <- ellipse(mB, SigB)
plot(0, type = "n",
     xlim = range(ellA[,1], ellB[,1]),
     ylim = range(ellA[,2], ellB[,2]), xlab = "x", ylab = "y")
lines(ellA, col = "red")
lines(ellB, col = "blue")
legend("topright", legend = c("niche A", "niche B"),
       fill = c("red", "blue"), bg = "white")

# compare niche calculations
overlap.sphere(mA, sigA, mB, sigB)
overlap.unif(mA, SigA, mB, SigB, nprob = 1e5)

nicheROVER documentation built on Oct. 13, 2023, 5:10 p.m.