estimate3D {iNEXT.3D}

Compute 3D diversity estimates with a particular set of sample sizes/coverages

Description

estimate3D computes 3D diversity (Hill-Chao number with q = 0, 1 and 2) with a particular set of user-specified levels of sample sizes or sample coverages. If no sample sizes or coverages are specified, this function by default computes 3D diversity estimates for the minimum sample coverage or minimum sample size among all samples extrapolated to double reference sizes.

Usage

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

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_raw", data can be input as a list of matrices/data.frames (species by sampling units); data can also be input as a single 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 specified.

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 c(0, 1, 2).

datatype

data type of input data: individual-based abundance data (datatype = "abundance") or species by sampling-units incidence/occurrence 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) for which 3D diversity estimates (q =0, 1 and 2) will be computed.
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 in a single matrix/data.frame) a vector of positive integers specifying the number of sampling units in each assemblage. If assemblage names are not specified (i.e., names(nT) = NULL), then assemblages are automatically named as "assemblage1", "assemblage2",..., etc.

PDtree

(required argument for diversity = "PD"), a phylogenetic tree in Newick format for all observed species in the pooled assemblage.

PDreftime

(argument only for 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

(argument only for 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 argument for diversity = "FD"), a species pairwise distance matrix for all species in the pooled assemblage.

FDtype

(argument only for 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

(argument only for 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).

FDcut_number

(argument only for diversity = "FD" and FDtype = "AUC"), a numeric number to cut [0, 1] interval into equal-spaced sub-intervals to obtain the AUC value by integrating the tau-profile. Equivalently, the number of tau values that will be considered to compute the integrated AUC value. Default is FDcut_number = 50. A larger value can be set to obtain more accurate AUC value.

Value

a data.frame of diversity table including the following arguments: (when base = "coverage")

Assemblage

the name of assemblage.

Order.q

the diversity order of q.

SC

the target standardized coverage value.

m, mT

the corresponding sample size (or number of sampling units) for the standardized coverage value.

qTD, qPD, qFD

the estimated diversity of order q for the target coverage value. The estimate for complete coverage (when base = "coverage" and level = 1, or base = "size" and level = Inf) represents the estimated asymptotic diversity.

Method

Rarefaction, Observed, or Extrapolation, depending on whether the target coverage is less than, equal to, or greater than the coverage of the reference sample.

s.e.

standard error of diversity estimate.

qTD.LCL, qPD.LCL, qFD.LCL and qTD.UCL, qPD.UCL, qFD.UCL

the bootstrap lower and upper confidence limits for the diversity of order q at the specified level (with a default value of 0.95).

Reftime

the reference times for PD.

Type

"PD" (effective total branch length) or "meanPD" (effective number of equally divergent lineages) for PD.

Tau

the threshold of functional distinctiveness between any two species for FD (under FDtype = tau_values).

Similar output is obtained for base = "size".

Examples

# Taxonomic diversity for abundance data with two target coverages (93% and 97%)
data(Brazil_rainforest_abun_data)
output_est_TD_abun <- estimate3D(Brazil_rainforest_abun_data, diversity = 'TD', q = c(0, 1, 2), 
                                 datatype = "abundance", base = "coverage", level = c(0.93, 0.97))
output_est_TD_abun


# Phylogenetic diversity for abundance data with two target sizes (1500 and 3500)
data(Brazil_rainforest_abun_data)
data(Brazil_rainforest_phylo_tree)
data <- Brazil_rainforest_abun_data
tree <- Brazil_rainforest_phylo_tree
output_est_PD_abun <- estimate3D(data, diversity = 'PD', datatype = "abundance", 
                                 base = "size", level = c(1500, 3500), PDtree = tree)
output_est_PD_abun


# Functional diversity for abundance data with two target coverages (93% and 97%)
data(Brazil_rainforest_abun_data)
data(Brazil_rainforest_distance_matrix)
data <- Brazil_rainforest_abun_data
distM <- Brazil_rainforest_distance_matrix
output_est_FD_abun <- estimate3D(data, diversity = 'FD', datatype = "abundance", 
                                 base = "coverage", level = c(0.93, 0.97), nboot = 10, 
                                 FDdistM = distM, FDtype = 'AUC')
output_est_FD_abun


# Taxonomic diversity for incidence data with two target coverages (97.5% and 99%)
data(Fish_incidence_data)
output_est_TD_inci <- estimate3D(Fish_incidence_data, diversity = 'TD', q = c(0, 1, 2), 
                                 datatype = "incidence_raw", base = "coverage", 
                                 level = c(0.975, 0.99))
output_est_TD_inci


# Phylogenetic diversity for incidence data with two target coverages (97.5% and 99%)
data(Fish_incidence_data)
data(Fish_phylo_tree)
data <- Fish_incidence_data
tree <- Fish_phylo_tree
output_est_PD_inci <- estimate3D(data, diversity = 'PD', datatype = "incidence_raw", 
                                 base = "coverage", level = c(0.975, 0.99), PDtree = tree)
output_est_PD_inci


# Functional diversity for incidence data with two target number of sampling units (30 and 70)
data(Fish_incidence_data)
data(Fish_distance_matrix)
data <- Fish_incidence_data
distM <- Fish_distance_matrix
output_est_FD_inci <- estimate3D(data, diversity = 'FD', datatype = "incidence_raw", 
                                 base = "size", level = c(30, 70), nboot = 10, 
                                 FDdistM = distM, FDtype = 'AUC')
output_est_FD_inci