zetadiv (version 1.2.0)

Zeta.ddecay: 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 gdist function from package Imap); 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 \(\zeta_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.

See Also

Zeta.decline.mc, Zeta.order.mc, Zeta.decline.ex, Zeta.order.ex, Zeta.ddecays,

Plot.zeta.ddecay

Examples

# NOT RUN {
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")

# }