nicheROVER (version 1.1.2)

overlap.unif: 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)

Value

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

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().

References

Li, S. "Concise formulas for the area and volume of a hyperspherical cap." Asian Journal of Mathematics & Statistics 4.1 (2011): 66-70. 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)