ObsAsy3D {iNEXT.3D}

Asymptotic diversity and observed diversity of order q

Description

ObsAsy3D computes observed and asymptotic diversity of order q between 0 and 2 (in increments of 0.2) for 3D diversity; these 3D values with different order q can be used to depict a q-profile in the ggObsAsy3D function.

It also computes observed and asymptotic PD for various reference times by specifying the argument PDreftime; these PD values with different reference times can be used to depict a time-profile in the ggObsAsy3D function.

It also computes observed and asymptotic FD for various threshold tau levels by specifying the argument FDtau; these FD values with different threshold levels can be used to depict a tau-profile in the ggObsAsy3D function.

For each dimension, by default, both the observed and asymptotic diversity estimates will be computed.

Usage

ObsAsy3D(
  data,
  diversity = "TD",
  q = seq(0, 2, 0.2),
  datatype = "abundance",
  nboot = 50,
  conf = 0.95,
  nT = NULL,
  method = c("Asymptotic", "Observed"),
  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 seq(0, 2, by = 0.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).

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.

method

Select 'Asymptotic' or 'Observed'.

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 including the following information/statistics:

Assemblage

the name of assemblage.

Order.q

the diversity order of q.

qTD, qPD, qFD

the estimated asymptotic diversity or observed diversity of order q.

s.e.

standard error of diversity.

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

Method

"Asymptotic" means asymptotic diversity and "Observed" means observed diversity.

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 the observed and asymptotic taxonomic diversity for abundance data
# with order q between 0 and 2 (in increments of 0.2 by default)
data(Brazil_rainforest_abun_data)
output_ObsAsy_TD_abun <- ObsAsy3D(Brazil_rainforest_abun_data, diversity = 'TD', 
                                  datatype = "abundance")
output_ObsAsy_TD_abun


# Compute the observed and asymptotic phylogenetic diversity for abundance data
# with order q = 0, 1, 2 under reference times from 0.01 to 400 (tree height).
data(Brazil_rainforest_abun_data)
data(Brazil_rainforest_phylo_tree)
data <- Brazil_rainforest_abun_data
tree <- Brazil_rainforest_phylo_tree
output_ObsAsy_PD_abun <- ObsAsy3D(data, diversity = 'PD', q = c(0, 1, 2), 
                                  PDreftime = seq(0.01, 400, length.out = 20),
                                  datatype = "abundance", nboot = 20, PDtree = tree)
output_ObsAsy_PD_abun


# Compute the observed and asymptotic functional diversity for abundance data
# with order q = 0, 1, 2 under tau values from 0 to 1.
data(Brazil_rainforest_abun_data)
data(Brazil_rainforest_distance_matrix)
data <- Brazil_rainforest_abun_data
distM <- Brazil_rainforest_distance_matrix
output_ObsAsy_FD_abun_tau <- ObsAsy3D(data, diversity = 'FD', q = c(0, 1, 2), 
                                      datatype = "abundance", nboot = 10, FDdistM = distM, 
                                      FDtype = 'tau_values', FDtau = seq(0, 1, 0.05))
output_ObsAsy_FD_abun_tau


# Compute the observed and asymptotic functional diversity for abundance data
# with order q between 0 and 2 (in increments of 0.5).
data(Brazil_rainforest_abun_data)
data(Brazil_rainforest_distance_matrix)
data <- Brazil_rainforest_abun_data
distM <- Brazil_rainforest_distance_matrix
output_ObsAsy_FD_abun <- ObsAsy3D(data, diversity = 'FD', q = seq(0, 2, 0.5), 
                                  datatype = "abundance", nboot = 10, 
                                  FDdistM = distM, FDtype = 'AUC')
output_ObsAsy_FD_abun


# Compute the observed and asymptotic taxonomic diversity for incidence data
# with order q between 0 and 2 (in increments of 0.2 by default).
data(Fish_incidence_data)
output_ObsAsy_TD_inci <- ObsAsy3D(Fish_incidence_data, diversity = 'TD', 
                                  datatype = "incidence_raw")
output_ObsAsy_TD_inci


# Compute the observed and asymptotic phylogenetic diversity for incidence data
# with order q between 0 and 2 (in increments of 0.2 by default), 
# for the default reference time = 0.977 (the tree depth).
data(Fish_incidence_data)
data(Fish_phylo_tree)
data <- Fish_incidence_data
tree <- Fish_phylo_tree
output_ObsAsy_PD_inci <- ObsAsy3D(data, diversity = 'PD', q = seq(0, 2, 0.2), 
                                  datatype = "incidence_raw", nboot = 20, PDtree = tree, 
                                  PDreftime = NULL)
output_ObsAsy_PD_inci


# Compute the observed and asymptotic functional diversity for incidence data
# with order q between 0 and 2 (in increments of 0.2 by default).
data(Fish_incidence_data)
data(Fish_distance_matrix)
data <- Fish_incidence_data
distM <- Fish_distance_matrix
output_ObsAsy_FD_inci <- ObsAsy3D(data, diversity = 'FD', datatype = "incidence_raw", 
                                  nboot = 20, FDdistM = distM, FDtype = 'AUC')
output_ObsAsy_FD_inci