iNEXTbeta3D {iNEXT.beta3D}

iNterpolation and EXTrapolation with beta diversity for TD, PD and FD

Description

iNEXTbeta3D computes standardized 3D estimates with a common sample size (for alpha and gamma diversity) or sample coverage (for alpha, beta, gamma diversity as well as dissimilarity indices) for default sizes or coverage values. This function also computes standardized 3D estimates with a particular vector of user-specified sample sizes or coverage values. See Chao et al. (2023) for the theory.

Usage

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

Arguments

data

(a) For datatype = "abundance", species abundance data for a single dataset can be input as a matrix/data.frame (species-by-assemblage); data for multiple datasets can be input as a list of matrices/data.frames, with each matrix representing a species-by-assemblage abundance matrix for one of the datasets.
(b) For datatype = "incidence_raw", data for a single dataset with N assemblages can be input as a list of matrices/data.frames, with each matrix representing a species-by-sampling-unit incidence matrix for one of the assemblages; data for multiple datasets can be input as multiple lists.

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

standardization base: coverage-based rarefaction and extrapolation for gamma, alpha, beta diversity, and four classes of dissimilarity indices (base = "coverage"), or sized-based rarefaction and extrapolation for gamma and alpha diversity (base = "size"). Default is base = "coverage".

level

a numerical vector specifying the particular values of sample coverage (between 0 and 1 when base = "coverage") or sample sizes (base = "size") that will be used to compute standardized diversity/dissimilarity. Asymptotic diversity estimator can be obtained by setting level = 1 ( i.e., complete coverage for base = "coverage").
By default (with base = "coverage"), this function computes the standardized 3D gamma, alpha, beta diversity, and four dissimilarity indices for coverage up to one (for q = 1, 2) or up to the coverage of double the reference sample size (for q = 0), in increments of 0.025. The extrapolation limit for beta diversity is defined as that for alpha diversity.
If users set base = "size", this function computes the size-based standardized 3D gamma and alpha diversity estimates based on 40 equally-spaced sample sizes/knots from sample size 1 up to double the reference sample size.

nboot

a positive integer specifying the number of bootstrap replications when assessing sampling uncertainty and constructing confidence intervals. Bootstrap replications are generally time consuming. Set nboot = 0 to skip the bootstrap procedures. Default is nboot = 10. If more accurate results are required, set nboot = 100 (or nboot = 200).

conf

a positive number < 1 specifying the level of confidence interval. Default is 0.95.

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 numerical value specifying reference time for PD. Default is PDreftime = 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 PDtype = "meanPD", where meanPD = PD/tree depth.

FDdistM

(required argument for diversity = "FD"), a species pairwise distance matrix for all species in the pooled dataset.

FDtype

(argument only for diversity = "FD"), select FD type: FDtype = "tau_value" for FD under a specified threshold value, 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 FDtype = "AUC".

FDtau

(argument only for diversity = "FD" and FDtype = "tau_value"), a numerical value between 0 and 1 specifying the tau value (threshold level) that will be used to compute FD. If FDtype = NULL (default), then threshold level is set to be the mean distance between any two individuals randomly selected from the pooled dataset (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 = 30. A larger value can be set to obtain more accurate AUC value.

Value

For base = "coverage", return a list of seven data frames with three diversity (gamma, alpha, and beta diversity) and four dissimilarity measures. For base = "size", return a list of two matrices with two diversity (gamma and alpha diversity).

For base = "coverage", the output in each data frame includes:

Dataset

the name of dataset.

Order.q

the diversity order of q.

SC

the target standardized coverage value.

Size/mT

the corresponding sample size.

Alpha/Beta/Gamma/Dissimilarity

the estimated diversity/dissimilarity estimate.

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 standardized estimate.

LCL, UCL

the bootstrap lower and upper confidence limits for the diversity/dissimilarity with a default significance level of 0.95.

Diversity

'TD' = 'Taxonomic diversity', 'PD' = 'Phylogenetic diversity', 'meanPD' = 'Mean phylogenetic diversity', 'FD_tau' = 'Functional diversity (given tau)', 'FD_AUC' = 'Functional diversity (AUC)'

Reftime

the reference time for PD.

Tau

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

Similar output is obtained for base = "size".

References

Chao, A., Thorn, S., Chiu, C.-H., Moyes, F., Hu, K.-H., Chazdon, R. L., Wu, J., Magnago, L. F. S., Dornelas, M., Zeleny, D., Colwell, R. K., and Magurran, A. E. (2023). Rarefaction and extrapolation with beta diversity under a framework of Hill numbers: the iNEXT.beta3D standardization. Ecological Monographs e1588.

Examples

## (R/E Analysis) Taxonomic diversity for abundance data
# Coverage-based standardized TD estimates and related statistics
data(Brazil_rainforests)
output_TDc_abun = iNEXTbeta3D(data = Brazil_rainforests, diversity = 'TD', 
                              datatype = 'abundance', base = "coverage", nboot = 10)
output_TDc_abun


# Coverage-based standardized TD estimates and related statistics by 
# user-specified coverage values
data(Brazil_rainforests)
output_TDc_abun_byuser = iNEXTbeta3D(data = Brazil_rainforests, diversity = 'TD', 
                                     datatype = 'abundance', base = "coverage", nboot = 10,
                                     level = c(0.85, 0.9))
output_TDc_abun_byuser


# Size-based standardized TD estimates and related statistics
data(Brazil_rainforests)
output_TDs_abun = iNEXTbeta3D(data = Brazil_rainforests, diversity = 'TD', 
                              datatype = 'abundance', base = "size", nboot = 10)
output_TDs_abun


# Size-based standardized TD estimates and related statistics by user-specified sample sizes
data(Brazil_rainforests)
output_TDs_abun_byuser = iNEXTbeta3D(data = Brazil_rainforests, diversity = 'TD', 
                                     datatype = 'abundance', base = "size", nboot = 10,
                                     level = c(300, 500))
output_TDs_abun_byuser


## (R/E Analysis) Taxonomic diversity for incidence data
# Coverage-based standardized TD estimates and related statistics
data(Second_growth_forests)
output_TDc_inci = iNEXTbeta3D(data = Second_growth_forests, diversity = 'TD', 
                              datatype = 'incidence_raw', base = "coverage", nboot = 10)
output_TDc_inci


# Coverage-based standardized TD estimates and related statistics by 
# user-specified coverage values
data(Second_growth_forests)
output_TDc_inci_byuser = iNEXTbeta3D(data = Second_growth_forests, diversity = 'TD', 
                                     datatype = 'incidence_raw', base = "coverage", 
                                     nboot = 10, level = c(0.9, 0.95))
output_TDc_inci_byuser


# Size-based standardized TD estimates and related statistics
data(Second_growth_forests)
output_TDs_inci = iNEXTbeta3D(data = Second_growth_forests, diversity = 'TD', 
                              datatype = 'incidence_raw', base = "size", nboot = 10)
output_TDs_inci


# Size-based standardized TD estimates and related statistics by user-specified sample sizes
data(Second_growth_forests)
output_TDs_inci_byuser = iNEXTbeta3D(data = Second_growth_forests, diversity = 'TD', 
                                     datatype = 'incidence_raw', base = "size", 
                                     nboot = 10, level = c(100, 200))
output_TDs_inci_byuser


## (R/E Analysis) Phylogenetic diversity for abundance data
# Coverage-based standardized PD estimates and related statistics
data(Brazil_rainforests)
data(Brazil_tree)
output_PDc_abun = iNEXTbeta3D(data = Brazil_rainforests, diversity = 'PD', 
                              datatype = 'abundance', base = "coverage", nboot = 10, 
                              PDtree = Brazil_tree, PDreftime = NULL, PDtype = 'meanPD')
output_PDc_abun


# Size-based standardized PD estimates and related statistics
data(Brazil_rainforests)
data(Brazil_tree)
output_PDs_abun = iNEXTbeta3D(data = Brazil_rainforests, diversity = 'PD', 
                              datatype = 'abundance', base = "size", nboot = 10, 
                              PDtree = Brazil_tree, PDreftime = NULL, PDtype = 'meanPD')
output_PDs_abun


## (R/E Analysis) Functional diversity for abundance data when all thresholds from 0 to 1 
## are considered
# Coverage-based standardized FD estimates and related statistics
data(Brazil_rainforests)
data(Brazil_distM)
output_FDc_abun = iNEXTbeta3D(data = Brazil_rainforests, diversity = 'FD', 
                              datatype = 'abundance', base = "coverage", nboot = 10, 
                              FDdistM = Brazil_distM, FDtype = 'AUC', FDcut_number = 30)
output_FDc_abun


# Size-based standardized FD estimates and related statistics
data(Brazil_rainforests)
data(Brazil_distM)
output_FDs_abun = iNEXTbeta3D(data = Brazil_rainforests, diversity = 'FD', 
                              datatype = 'abundance', base = "size", nboot = 10, 
                              FDdistM = Brazil_distM, FDtype = 'AUC', FDcut_number = 30)
output_FDs_abun