iNEXT3D: iNterpolation and EXTrapolation of Hill number

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

Description

iNEXT3D: Interpolation and extrapolation of Hill number with order q

Usage

iNEXT3D(
  data,
  diversity = "TD",
  q = c(0, 1, 2),
  datatype = "abundance",
  size = NULL,
  endpoint = NULL,
  knots = 40,
  nboot = 50,
  conf = 0.95,
  nT = NULL,
  PDtree = NULL,
  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)
size	an integer vector of sample sizes (number of individuals or sampling units) for which diversity estimates will be computed. If NULL, then diversity estimates will be computed for those sample sizes determined by the specified/default endpoint and knots .
endpoint	an integer specifying the sample size that is the endpoint for rarefaction/extrapolation. If NULL, then endpoint = double reference sample size.
knots	an integer specifying the number of equally-spaced knots (say K, default is 40) between size 1 and the endpoint; each knot represents a particular sample size for which diversity estimate will be calculated. If the endpoint is smaller than the reference sample size, then iNEXT3D() computes only the rarefaction esimates for approximately K evenly spaced knots. If the endpoint is larger than the reference sample size, then iNEXT3D() computes rarefaction estimates for approximately K/2 evenly spaced knots between sample size 1 and the reference sample size, and computes extrapolation estimates for approximately K/2 evenly spaced knots between the reference sample size and the endpoint.
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 list of three objects: $DataInfo for summarizing data information; $iNextEst for showing diversity estimates for rarefied and extrapolated samples along with related statistics; and $AsyEst for showing asymptotic diversity estimates along with related statistics.

Examples

## example for abundance based data (list of vector)
# diversity = 'TD'
data(spider)
out1 <- iNEXT3D(spider, diversity = 'TD', q = c(0,1,2), datatype = "abundance")
out1$DataInfo # showing basic data information.
out1$AsyEst # showing asymptotic diversity estimates.
out1$iNextEst # showing diversity estimates with rarefied and extrapolated.

# diversity = 'PD'
data(data.abu)
data <- data.abu$data
tree <- data.abu$tree
out2 <- iNEXT3D(data, diversity = 'PD', q = c(0, 1, 2), datatype = "abundance", nboot = 30, PDtree = tree)
out2

# diversity = 'FD' & FDtype = 'tau_values'
data(FunDdata.abu)
data <- FunDdata.abu$data
distM <-  FunDdata.abu$dij
out3 <- iNEXT3D(data[,1], diversity = 'FD', datatype = "abundance", nboot = 0, FDdistM = distM, FDtype = 'tau_values')
out3

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

## example for incidence-based data
# diversity = 'TD'
data(ant)
t <- round(seq(10, 500, length.out = 20))
out5 <- iNEXT3D(ant$h500m, diversity = 'TD', q = 1, datatype = "incidence_freq", size = t)
out5

# diversity = 'PD'
data(data.inc)
data <- data.inc$data
tree <- data.inc$tree
nT <- data.inc$nT
out6 <- iNEXT3D(data, diversity = 'PD', q = c(0, 1, 2), datatype = "incidence_raw", nT = nT, PDtree = tree)
out6

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

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

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