nicheROVER: overlap – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

overlap

Monte Carlo calculation of niche region overlap metrics

Description

Calculates the distribution of a niche region overlap metric for each pairwise species combination and user-specified niche region sizes.

Usage

overlap(niche.par, nreps, nprob, alpha = 0.95, species.names,
  norm.redraw = TRUE)

Arguments

`niche.par`	a list with `nspecies = length(niche.par)`, each element of which in turn is a list with elements `mu` and `Sigma`. See Details.
`nreps`	the number of overlap metric calculations for each species. Defaults to the smallest number of parameter samples supplied by `niche.par`. See Details.
`nprob`	the number of normal draws for each Monte Carlo overlap metric calculation. See Details.
`alpha`	scalar or vector of niche region sizes for calculating the niche overlap metric. Defaults to 0.95.
`species.names`	names of the species. Defaults to `names(niche.par)`.
`norm.redraw`	logical. If `FALSE`, the same `nprobnspecies` iid N(0,1)* draws are used for each calculation of the overlap metric. This increases the Monte Carlo error, but the procedure is about 1.5x faster. Defaults to `TRUE`.

Details

The overlap metric is the probability that a randomly drawn individual from species A will be found within the niche region of species B (for a given niche region size, e.g., alpha = .95). It is a single number which is a function of the parameters for each species, Θ_A = (μ_A, Σ_A) and Θ_B = (μ_B, Σ_B). This number is difficult to calculate directly, but easy to approximate stochastically by generating nprob draws from the distribution of species A and counting the fraction of them which fall in the niche region of species B. Typically the true values of Θ_A and Θ_B are unknown and must be estimated from the data. Thus, the overlap metric is calculated for nreps combinations of samples from p(Θ_A | X) and p(Θ_B | X) which are supplied in niche.par. See Swanson et al. (2014) for a detailed description of niche overlap and its calculation.

Value

Returns an array of size c(nspecies, nspecies, nreps, nlevels), where nlevels is the number of alpha levels at which to calculate the overlap metric. For each of the last two dimensions of the output array, the first two dimensions form an nspecies by nspecies matrix giving each pairwise calculation of overlap metric between two species for given Θ_A, Θ_B, and alpha. In each of these matrices, Species A is along the rows of this matrix and Species B is along the columns.

References

Heidi K. Swanson, Martin Lysy, Ashley D. Stasko, Michael Power, Jim D. Johnson, and James D. Reist (2014). “What Would Hutchinson Think? A Probabilistic Quantification of Multidimensional Ecological Niches and Niche Overlap”. Ecology: Statistical Reports (accepted).

Examples

# fish data
data(fish)

# generate parameter draws from the "default" posteriors of each fish
nsamples <- 500
system.time({
 fish.par <- tapply(1:nrow(fish), fish$species,
                    function(ii) niw.post(nsamples = nsamples, X = fish[ii,2:4]))
})

# overlap calculation. use nsamples = nprob = 1e4 for more accurate results.
system.time({
 over <- overlap(fish.par, nreps = nsamples, nprob = nsamples, alpha = c(.95, .99))
})

# posterior expectations of overlap metrics
over.mean <- apply(over*100, c(1:2, 4), mean)
round(over.mean)

# posterior 95% credible intervals of overlap metrics
over.cred <- apply(over*100, c(1:2, 4), quantile, prob = c(.025, .975), na.rm = TRUE)
round(over.cred[,,,1]) # display alpha = .95 niche region

nicheROVER

(Niche) (R)egion and Niche (Over)lap Metrics for Multidimensional Ecological Niches

v1.0

GPL-2

Authors

Martin Lysy [aut, cre], Ashley D. Stasko [aut, ctb], Heidi K. Swanson [aut, ctb]

Initial release

2014-07-21