Zeta.ddecay: Zeta distance decay for a specific number of assemblages or...
In zetadiv: Functions to Compute Compositional Turnover Using Zeta Diversity

Zeta.ddecay

R Documentation

Zeta distance decay for a specific number of assemblages or sites

Description

Computes the distance decay of zeta diversity for a specific order (number of assemblages or sites), using either a generalised linear model with possible constraint on the coefficients, a generalised additive model, or a shape constrained additive model.

Usage

Zeta.ddecay(
  xy,
  data.spec,
  order = 2,
  sam = 1000,
  distance.type = "Euclidean",
  dist.custom = NULL,
  method = "mean",
  reg.type = "glm",
  family = stats::gaussian(),
  method.glm = "glm.fit.cons",
  cons = -1,
  cons.inter = 1,
  confint.level = 0.95,
  kn = -1,
  bs = "mpd",
  trsf = "NULL",
  cutoff = NULL,
  rescale = FALSE,
  normalize = FALSE,
  empty.row = "remove",
  plot = TRUE
)

Arguments

`xy`	Site-by-coordinate data frame, with sites as rows and coordinates as columns.
`data.spec`	Site-by-species presence-absence data frame, with sites as rows and species as columns.
`order`	Specific number of assemblages or sites at which zeta diversity is computed.
`sam`	Number of samples for which the zeta diversity is computed.
`distance.type`	Method to compute distance. Default is "`Euclidean`", for Euclidean distance. The other options are (i) "`ortho`" for orthodromic distance, if xy correspond to longitudes and latitudes (orthodromic distance is computed using the `geodist` function from package `geodist`); and (ii) "`custom`", in which case the user must provide a distance matrix for `dist.custom`.
`dist.custom`	Distance matrix provided by the user when `distance.type` = `"custom"`.
`method`	Name of a function (as a string) indicating how to combine the pairwise differences and distances for more than 3 sites. It can be a basic R-function such as "`mean`" or "`max`", but also a custom function.
`reg.type`	Type of regression. Options are "`glm`" for generalised linear models "`gam`" for generalised additive models and "`scam`" for shape constrained additive models (with monotonic decreasing by default).
`family`	A description of the error distribution and link function to be used in the `glm`, `gam` and `scam` models (see `family` for details of family functions).
`method.glm`	Method used in fitting the generalised linear model. The default method "glm.fit.cons" is an adaptation of method `glm.fit2` from package `glm2` using a negative least squares regression in the reweighted least squares. Another option is "glm.fit2", which calls `glm.fit2`.; see help documentation for `glm.fit2` in package `glm`.
`cons`	type of constraint in the glm if `method.glm = "glm.fit.cons"`. Default is -1 for negative coefficients on the predictors. The other option is 1 for positive coefficients on the predictors.
`cons.inter`	type of constraint for the intercept. Default is 1 for positive intercept, suitable for Gaussian family. The other option is -1 for negative intercept, suitable for binomial family.
`confint.level`	Percentage for the confidence intervals of the coefficients from the generalised linear models.
`kn`	Number of knots in the GAM and SCAM. Default is -1 for determining kn automatically using Generalized Cross-validation.
`bs`	A two-letter character string indicating the (penalized) smoothing basis to use in the scam model. Default is "`mpd`" for monotonic decreasing splines. see `smooth.terms` for an overview of what is available.
`trsf`	Name of a function (as a string) indicating how to transform distance.
`cutoff`	If specified, maximum distance value for which the linear regression must be performed.
`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.
`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.

Value

Zeta.ddecay returns a list containing the following components:

`order`	The order of zeta for which the distance decay was computed.
`reg.type`	A character string indicating the type of regression that was performed.
`reg`	An object whose class depends on the type of regression (`glm`, `gam` or `scam`), corresponding to the regression over distance for the number of assemblages or sites specified in 'order'.
`confint`	The confidence intervals for the coefficients from the generalised linear model. `confint` is not generated for generalised additive models and shape constrained additive models.
`zeta.val`	The values of zeta for the sampled sites used in the regression.
`distance`	The distances for the sampled sites used in the regression.

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.

Examples

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

dev.new()
zeta.ddecay.bird <- Zeta.ddecay(xy.bird, data.spec.bird, sam = 100, order = 3,
    method.glm = "glm.fit2", confint.level = 0.95)
    
dev.new()
zeta.ddecay.bird <- Zeta.ddecay(data.spec=data.spec.bird, distance.type = "custom",
    dist.custom = as.matrix(dist(xy.bird)), cutoff = 800000, sam = 100, order = 3,
    reg.type = "gam", confint.level = 0.95)

##########

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

dev.new()
zeta.ddecay.marion <- Zeta.ddecay(xy.marion, data.spec.marion, sam = 100, order = 3,
    method.glm = "glm.fit2", confint.level = 0.95, trsf = "log", normalize = "Jaccard")

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