BAT (version 2.5.1)

kernel.dispersion: Functional dispersion of a n-dimensional hypervolume representing a given community.

Description

Average distance to centroid or dissimilarity between random points within the boundaries of the kernel density hypervolume.

Usage

kernel.dispersion(
  comm,
  trait,
  method = "gaussian",
  func = "dissimilarity",
  abund = TRUE,
  frac = 0.1,
  ...
)

Arguments

comm

A 'Hypervolume' object or a 'HypervolumeList' object (one for each species or community) constructed with the hypervolume R package. Alternatively, a sites x species matrix, data.frame or vector, with incidence or abundance data about the species in the community.

trait

A matrix of traits for each species in comm (a species for each row and traits as columns). Must be provided only if 'comm' is a sites x species matrix.

method

Method for constructing the 'Hypervolume'. One of "box" (box kernel density estimation), "gaussian" (Gaussian kernel density estimation), or "svm" (one-class support vector machine). See respective functions of the hypervolume R package for details. Must be provided only if 'comm' is a sites x species matrix. Default is 'gaussian'.

func

Function for calculating dispersion. One of 'divergence', 'dissimilarity' or 'regression'.

abund

A boolean (T/F) indicating whether abundance data should be used as weights in hypervolume construction. Only works if method = "gaussian". Ignored if a 'Hypervolume' or 'HypervolumeList' is provided as input data.

frac

A value between 0.01 and 1, indicating the fraction of random points to be used. Default is 0.1.

...

further arguments to be passed for other methods in hypervolume package.

Value

A vector of dispersion values for each site.

Details

This function calculates dispersion either: i) as the average distance between stochastic points within the kernel density hypervolume and the centroid of these points (divergence; Laliberte & Legendre, 2010; see also Carmona et al., 2019); ii) as the average distance between all points (dissimilarity, see also function BAT::dispersion); or iii) as the average distance between stochastic points within the kernel density hypervolume and a regression line fitted through the points. The number of stochastic points is controlled by the 'frac' parameter (increase this number for less deviation in the estimation). If abundance data of species in the community are provided as input data (abund = TRUE), each species trait is weighted by replicating it by the abundance in the estimation of the hypervolume.

References

Carmona, C.P., de Bello, F., Mason, N.W.H. & Leps, J. (2019) Trait probability density (TPD): measuring functional diversity across scales based on TPD with R. Ecology, 100: e02876.

Mammola, S. & Cardoso, P. (2020) Functional diversity metrics using kernel density n-dimensional hypervolumes. Methods in Ecology and Evolution, 11: 986-995.

Laliberte, E. & Legendre, P. (2010) A distance-based framework for measuring functional diversity from multiple traits. Ecology 91: 299-305.

Examples

# NOT RUN {
comm <- rbind(c(0,3,2,1), c(1,5,6,2), c(0,0,2,1))
rownames(comm) = c("Community_1", "Community_2", "Community_3")
colnames(comm) = c("Sp_1", "Sp_2", "Sp_3", "Sp_4")

trait <- cbind(c(2.2,4.4,6.1,8.3), c(0.5,1,0.5,0.4), c(0.7,1.2,0.5,0.4))
rownames(trait) = c("Sp_1", "Sp_2", "Sp_3", "Sp_4")
colnames(trait) = c("Trait_1", "Trait_2", "Trait_3")

#Example with community and trait matrices as input data
#kernel.dispersion(comm = comm, trait = trait)
# }