iNEXT3D {iNEXT.3D}

iNterpolation and EXTrapolation with three dimensions of biodiversity

Description

iNEXT3D mainly computes standardized 3D estimates with a common sample size or sample coverage for orders q = 0, 1 and 2. It also computes relevant information/statistics.

For diversity = "TD", relevant data information is summarized in the output $TDInfo. Diversity estimates for rarefied and extrapolated samples are provided in the output $TDiNextEst, which includes two data frames ("$size_based" and "$coverage_based") based on two different standardizations; in the size-based standardization, all samples are standardized to a common target sample size, whereas the in the latter standardization, all samples are standardized to a common target level of sample coverage. The asymptotic diversity estimates for q = 0, 1 and 2 are provided in the list $TDAsyEst.

For diversity = "PD", the corresponding three lists are $PDInfo, $PDiNextEst and $PDAsyEst.
For diversity = "FD", the corresponding three lists are $FDInfo, $FDiNextEst and $FDAsyEst.

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,
  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).

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 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 list of three objects:

(1) $TDInfo ($PDInfo, or $FDInfo) for summarizing data information for q = 0, 1 and 2. Refer to the output of DataInfo3D for details.

(2) $TDiNextEst ($PDiNextEst, or $FDiNextEst) for showing diversity estimates for rarefied and extrapolated samples along with related statistics. There are two data frames: "$size_based" and "$coverage_based".

In "$size_based", the output includes:

Assemblage

the name of assemblage.

Order.q

the diversity order of q.

m, mT

the target sample size (or number of sampling units for incidence data).

Method

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

qTD, qPD, qFD

the estimated 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).

SC

the standardized coverage value.

SC.LCL, SC.UCL

the bootstrap lower and upper confidence limits for coverage 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 "$coverage_based".

(3) $TDAsyEst ($PDAsyEst, or $FDAsyEst) for showing asymptotic diversity estimates along with related statistics:

Assemblage

the name of assemblage.

qTD, qPD, qFD

the diversity order of q.

TD_obs, PD_obs, FD_obs

the observed diversity.

TD_asy, PD_asy, FD_asy

the asymptotic diversity estimate.

s.e.

standard error of asymptotic diversity.

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

the bootstrap lower and upper confidence limits for asymptotic diversity 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).

Examples

# Compute standardized estimates of taxonomic diversity for abundance data with order q = 0, 1, 2
data(Brazil_rainforest_abun_data)
output_TD_abun <- iNEXT3D(Brazil_rainforest_abun_data, diversity = 'TD', q = c(0, 1, 2), 
                          datatype = "abundance")
output_TD_abun


# Compute standardized estimates of phylogenetic diversity for abundance data with order q = 0, 1, 2
data(Brazil_rainforest_abun_data)
data(Brazil_rainforest_phylo_tree)
data <- Brazil_rainforest_abun_data
tree <- Brazil_rainforest_phylo_tree
output_PD_abun <- iNEXT3D(data, diversity = 'PD', q = c(0, 1, 2), datatype = "abundance", 
                          nboot = 20, PDtree = tree)
output_PD_abun


# Compute standardized estimates of functional diversity for abundance data
data(Brazil_rainforest_abun_data)
data(Brazil_rainforest_distance_matrix)
data <- Brazil_rainforest_abun_data
distM <- Brazil_rainforest_distance_matrix
output_FD_abun <- iNEXT3D(data, diversity = 'FD', datatype = "abundance", nboot = 0, 
                          FDdistM = distM, FDtype = 'AUC')
output_FD_abun


# Compute standardized estimates of taxonomic diversity for incidence data with order q = 0, 1, 2
data(Fish_incidence_data)
output_TD_inci <- iNEXT3D(Fish_incidence_data, diversity = 'TD', q = c(0, 1, 2), 
                          datatype = "incidence_raw")
output_TD_inci


# Compute standardized estimates of phylogenetic diversity for incidence data with order q = 0, 1, 2
data(Fish_incidence_data)
data(Fish_phylo_tree)
data <- Fish_incidence_data
tree <- Fish_phylo_tree
output_PD_inci <- iNEXT3D(data, diversity = 'PD', q = c(0, 1, 2), 
                          datatype = "incidence_raw", nboot = 20, PDtree = tree)
output_PD_inci


# Compute estimates of functional diversity for incidence data
data(Fish_incidence_data)
data(Fish_distance_matrix)
data <- Fish_incidence_data
distM <- Fish_distance_matrix
output_FD_inci <- iNEXT3D(data, diversity = 'FD', datatype = "incidence_raw", nboot = 20, 
                          FDdistM = distM, FDtype = 'AUC')
output_FD_inci