estimate3D: Compute species diversity with a particular of sample...

In KaiHsiangHu/iNEXT3D: Interpolation and Extrapolation for Species Diversity in three dimensions

Description

estimate3D: computes species diversity (Hill numbers with q = 0, 1 and 2) with a particular user-specified level of sample size or sample coverage.

Usage

estimate3D(
  data,
  diversity = "TD",
  q = c(0, 1, 2),
  datatype = "abundance",
  base = "coverage",
  level = NULL,
  nboot = 50,
  conf = 0.95,
  nT,
  PDtree,
  PDreftime = NULL,
  PDtype = "meanPD",
  FDdistM,
  FDtype = "AUC",
  FDtau = NULL
)

Arguments

data	(a) For datatype = "abundance", data can be input as a vector of species abundances (for a single assemblage), matrix/data.frame (species by assemblages), or a list of species abundance vectors. (b) For datatype = "incidence_freq", data can be input as a vector of incidence frequencies (for a single assemblage), matrix/data.frame (species by assemblages), or a list of incidence frequencies; the first entry in all types of input must be the number of sampling units in each assemblage. (c) For datatype = "incidence_raw", data can be input as a list of matrix/data.frame (species by sampling units); data can also be input as a matrix/data.frame by merging all sampling units across assemblages based on species identity; in this case, the number of sampling units (nT, see below) must be input.
diversity	selection of diversity type: 'TD' = Taxonomic diversity, 'PD' = Phylogenetic diversity, and 'FD' = Functional diversity.
q	a numerical vector specifying the diversity orders. Default is seq(0, 2, by = 0.2).
datatype	data type of input data: individual-based abundance data (datatype = "abundance"), sampling-unit-based incidence frequencies data (datatype = "incidence_freq"), or species by sampling-units incidence matrix (datatype = "incidence_raw") with all entries being 0 (non-detection) or 1 (detection)
base	selection of sample-size-based (base = "size") or coverage-based (base = "coverage") rarefaction and extrapolation.
level	A numerical vector specifying the particular sample sizes or sample coverages (between 0 and 1). If base = "coverage" (default) and level = NULL, then this function computes the diversity estimates for the minimum sample coverage among all samples extrapolated to double reference sizes. If base = "size" and level = NULL, then this function computes the diversity estimates for the minimum sample size among all samples extrapolated to double reference sizes.
nboot	a positive integer specifying the number of bootstrap replications when assessing sampling uncertainty and constructing confidence intervals. Enter 0 to skip the bootstrap procedures. Default is 50.
conf	a positive number < 1 specifying the level of confidence interval. Default is 0.95.
nT	(required only when datatype = "incidence_raw" and input data is matrix/data.frame) a vector of nonnegative integers specifying the number of sampling units in each assemblage. If assemblage names are not specified, then assemblages are automatically named as "assemblage1", "assemblage2",..., etc.
PDtree	(required only when diversity = "PD"), a phylogenetic tree in Newick format for all observed species in the pooled assemblage.
PDreftime	(required only when diversity = "PD"), a vector of numerical values specifying reference times for PD. Default is NULL (i.e., the age of the root of PDtree).
PDtype	(required only when diversity = "PD"), select PD type: PDtype = "PD" (effective total branch length) or PDtype = "meanPD" (effective number of equally divergent lineages). Default is "meanPD", where meanPD = PD/tree depth.
FDdistM	(required only when diversity = "FD"), a species pairwise distance matrix for all species in the pooled assemblage.
FDtype	(required only when diversity = "FD"), select FD type: FDtype = "tau_values" for FD under specified threshold values, or FDtype = "AUC" (area under the curve of tau-profile) for an overall FD which integrates all threshold values between zero and one. Default is "AUC".
FDtau	(required only when diversity = "FD" and FDtype = "tau_values"), a numerical vector between 0 and 1 specifying tau values (threshold levels). If NULL (default), then threshold is set to be the mean distance between any two individuals randomly selected from the pooled assemblage (i.e., quadratic entropy).

Value

a data.frame of species diversity table including the sample size, sample coverage, method (rarefaction or extrapolation), and diversity estimates with q = 0, 1, and 2 for the user-specified sample size or sample coverage.

Examples

# diversity = 'TD'
data(spider)
out1 <- estimate3D(spider, diversity = 'TD', q = c(0,1,2), datatype = "abundance", base = "size")
out1

# diversity = 'PD'
data(data.abu)
data <- data.abu$data
tree <- data.abu$tree
out2 <- estimate3D(data, diversity = 'PD', datatype = "abundance", base = "coverage", PDtree = tree)
out2

# diversity = 'FD' & FDtype = 'tau_values'
data(FunDdata.abu)
data <- FunDdata.abu$data
distM <-  FunDdata.abu$dij
out3 <- estimate3D(data, diversity = 'FD', datatype = "abundance", base = "size", FDdistM = distM, FDtype = 'tau_values')
out3

# diversity = 'FD' & FDtype = 'AUC'
data(FunDdata.abu)
data <- FunDdata.abu$data
distM <-  FunDdata.abu$dij
out4 <- estimate3D(data = data[,2], diversity = 'FD', datatype = "abundance", base = "coverage", nboot = 0, FDdistM = distM)
out4

## example for incidence-based data
# diversity = 'TD'
data(ant)
out5 <- estimate3D(ant, diversity = 'TD', q = c(0,1,2), datatype = "incidence_freq", base = "coverage", level=0.985)
out5

# diversity = 'PD'
data(data.inc)
data <- data.inc$data
tree <- data.inc$tree
nT <- data.inc$nT
out6 <- estimate3D(data, diversity = 'PD', datatype = "incidence_raw", base = "size", nT = nT, PDtree = tree)
out6

# diversity = 'FD' & FDtype = 'tau_values'
data(FunDdata.inc)
data <- FunDdata.inc$data
distM <-  FunDdata.inc$dij
out7 <- estimate3D(data, diversity = 'FD', datatype = "incidence_freq", base = "coverage", FDdistM = distM, FDtype = 'tau_values')
out7

# diversity = 'FD' & FDtype = 'AUC'
data(FunDdata.inc)
data <- FunDdata.inc$data
distM <-  FunDdata.inc$dij
out8 <- estimate3D(data, diversity = 'FD', datatype = "incidence_freq", base = "size", nboot = 20, FDdistM = distM)
out8

KaiHsiangHu/iNEXT3D documentation built on July 18, 2021, 8:11 p.m.