Zeta.decline.mc: Zeta diversity decline using Monte Carlo sampling

In zetadiv: Functions to Compute Compositional Turnover Using Zeta Diversity

Zeta diversity decline using Monte Carlo sampling

Description

Computes zeta diversity, the number of species shared by multiple assemblages, for a range of orders (number of assemblages or sites), using combinations of sampled sites, and fits the decline to an exponential and a power law relationship.

Usage

Zeta.decline.mc(
  data.spec,
  xy = NULL,
  orders = 1:10,
  sam = 1000,
  sd.correct = TRUE,
  sd.correct.adapt = FALSE,
  confint.level = 0.95,
  sd.plot = TRUE,
  rescale = FALSE,
  normalize = FALSE,
  NON = FALSE,
  FPO = NULL,
  DIR = FALSE,
  empty.row = "empty",
  plot = TRUE,
  silent = TRUE
)

Arguments

data.spec	Site-by-species presence-absence data frame, with sites as rows and species as columns.
xy	Site coordinates. This is only used if NON = TRUE or DIR = TRUE.
orders	Range of number of assemblages or sites for which zeta diversity is computed.
sam	Number of samples for which the zeta diversity is computed for each number of assemblages or sites.
sd.correct	Boolean value (TRUE or FALSE) indicating if the standard deviation must be computed with an unbiased estimator (using the number of site combinations - 1 as the denominator) or not (using the number of site combinations as the denominator).
sd.correct.adapt	Boolean value (TRUE or FALSE) indicating if the standard deviation must be computed with an unbiased estimator (using the number of site combinations - 1 as the denominator) if sam is higher than the number of possible combinations, or not (using the number of site combinations as the denominator) if sam is lower than the number of possible combinations. If sd.correct.adapt = TRUE, it takes precedence over sd.correct.
confint.level	Percentage for the confidence intervals of the coefficients from the regressions.
sd.plot	Boolean value (TRUE or FALSE) indicating if the standard deviation of each zeta diversity value must be plotted.
rescale	Boolean value (TRUE or FALSE) indicating if the zeta values should be divided by ζ_1, to get a range of values between 0 and 1. Has no effect if normalize != FALSE.
normalize	Indicates if the zeta values for each sample should be divided by the total number of species for this specific sample (normalize = "Jaccard"), by the average number of species per site for this specific sample (normalize = "Sorensen"), or by the minimum number of species in the sites of this specific sample (normalize = "Simpson"). Default value is FALSE, indicating that no normalization is performed.
NON	Boolean value (TRUE or FALSE) indicating if the number of species in common should only be counted for the nearest neighbours.
FPO	A vector with the coordinates of the fixed point origin from which the zeta diversity will be computed (overrides NON). In that case, ζ_1 is the number of species in the closest site to the FPO, ζ_2 is the number of species shared by the 2 closest sites, etc.
DIR	Boolean value (TRUE or FALSE) indicating if zeta diversity must be computed using a directed nearest neighbour scheme in the direction away from the FPO, starting from any site.
empty.row	Determines how to handle empty rows, i.e. sites with no species. Such sites can cause underestimations of zeta diversity, and computation errors for the normalized version of zeta due to divisions by 0. Options are "empty" to let the data untreated, "remove" to remove the empty rows, 0 to set the normalized zeta to 0 when zeta is divided by 0 during normalization (sites share no species, so are completely dissimilar), and 1 to set the normalized zeta to 1 when zeta is divided by 0 during normalization (i.e. sites are perfectly similar).
plot	Boolean value (TRUE or FALSE) indicating if the outputs must be plotted.
silent	Boolean value (TRUE or FALSE) indicating if messages must be printed.

Details

If the number of combinations of sites is lower than the value of the parameter sam, all the combinations are used and an exact solution is computed. In that case, using the number of site combinations as the denominator may be appropriate to compute the standard deviation, if all sites were sampled and the zeta values. This can be adjusted with parameters sd.correct and sd.correct.adapt.

Zeta.decline.mc is faster than Zeta.decline.ex to compute the exact value of zeta diversity when the number of species is higher than C^N_{i}, where N is the total number of sites and i is the order of zeta.

The exponential and the power law fit are performed using linear regressions on log-transformed data (only the zeta values are log-transformed for the exponential fit, and both the orders and the zeta values are log-transformed for the power law fit).

Zeta.decline.mc enables accomodating richness heterogeneity by setting normalize = "Jaccard", normalize = "Sorensen" or normalize = "Simpson". This cannot be performed by
Zeta.decline.ex.

Value

Zeta.decline.mc returns a list containing the following components:

zeta.order	The number of assemblages or sites for which the zeta diversity was computed.
combinations	The number of possible combinations of sites for the chosen orders.
zeta.val	The zeta diversity values.
zeta.val.sd	The zeta diversity standard deviation values.
zeta.ratio	The ratio of zeta diversity values by the zeta diversity values at the lower order ζ_i / ζ_{i-1}.
zeta.exp	Object of class "lm", containing the output of the exponential regression.
zeta.exp.confint	The confidence intervals of the coefficients of the exponential regression.
zeta.pl	Object of class "lm", containing the output of the power law regression.
zeta.pl.confint	The confidence intervals of the coefficients of the power law regression.
aic	AIC values for zeta.exp and zeta.pl.

References

Hui C. & McGeoch M.A. (2014). Zeta diversity as a concept and metric that unifies incidence-based biodiversity patterns. The American Naturalist, 184, 684-694.

See Also

Zeta.decline.ex, Zeta.order.ex, Zeta.order.mc, Plot.zeta.decline

Examples

utils::data(bird.spec.coarse)
xy.bird <- bird.spec.coarse[,1:2]
data.spec.bird <- bird.spec.coarse[,3:193]

dev.new(width = 12, height = 4)
zeta.bird <- Zeta.decline.mc(data.spec.bird, xy.bird, orders = 1:5, sam = 100,
   NON = TRUE)
zeta.bird

##########

utils::data(Marion.species)
xy.marion <- Marion.species[,1:2]
data.spec.marion <- Marion.species[,3:33]

dev.new(width = 12, height = 4)
zeta.marion <- Zeta.decline.mc(data.spec.marion, orders = 1:5, sam = 100,
     normalize = "Jaccard")
zeta.marion

zetadiv documentation built on June 11, 2022, 1:12 a.m.