Package 'iNEXT.beta3D'

Interpolation and extrapolation with beta diversity for three dimensions of biodiversity

Description

This package iNEXT.beta3D (iNterpolation and EXTrapolation with beta diversity for three dimensions of biodiversity) is a sequel to iNEXT. Here the three dimensions (3D) of diversity includes taxonomic diversity (TD), phylogenetic diversity (PD) and functional diversity (FD). An online version "iNEXT.beta3D Online" (https://chao.shinyapps.io/iNEXT_beta3D/) is also available for users without an R background.

A unified framework based on Hill numbers (for TD) and their generalizations (Hill-Chao numbers, for PD and FD) is adopted to quantify 3D. In this framework, TD quantifies the effective number of species, PD quantifies the effective total branch length or total evolutionary history, mean-PD (PD divided by tree depth) quantifies the effective number of lineages, and FD quantifies the effective number of virtual functional groups (or functional "species"). Thus, TD, mean-PD, and FD are all in the same units of species/lineage equivalents and can be meaningfully compared; see Chao et al. (2021) for a review of the unified framework.

For each of the three dimensions, iNEXT.beta3D focuses on the multiplicative diversity decomposition (gamma = alpha x beta) of orders q = 0, 1 and 2 based on sampling data. Beta diversity quantifies the extent of among-assemblage differentiation, or the changes in species/lineages/functional-groups composition and their abundance among assemblages. iNEXT.beta3D features standardized 3D estimates with a common sample size (for alpha and gamma diversity) or sample coverage (for alpha, beta and gamma diversity). iNEXT.beta3D also features standardized estimates of four classes of coverage-based dissimilarity measures. Based on the rarefaction and extrapolation (R/E) method for Hill numbers (TD) for q = 0, 1 and 2, Chao et al. (2023b) developed the pertinent R/E theory for taxonomic beta diversity with applications to real-world spatial, temporal and spatio-temporal data. An application to Gentry's global forest data along with a concise description of the theory is provided in Chao et al. (2023a). The extension to phylogenetic and functional beta diversity is generally parallel.

iNEXT.beta3D also features two types of R/E sampling curves:

* Sample-size-based (or size-based) R/E curves: This type of sampling curve plots standardized 3D gamma and alpha diversity with respect to sample size. Note that the size-based beta diversity is not a statistically valid measure (Chao et al. 2023b) and thus the corresponding sampling curve is not provided.

* Coverage-based R/E sampling curves: This type of sampling curve plots standardized 3D gamma, alpha, and beta diversity as well as four classes of dissimilarity measures with respect to sample coverage (an objective measure of sample completeness).

Sufficient data are needed to run iNEXT.beta3D. If your data comprise only a few species and their abundances/phylogenies/traits, it is probable that the data lack sufficient information to run iNEXT.beta3D.

This package contains three main functions:

1. iNEXTbeta3D computes standardized 3D estimates with a common sample size (for alpha and gamma diversity) or sample coverage (for alpha, beta and gamma diversity) for default sample sizes or coverage values. This function also computes coverage-based standardized 3D estimates of four classes of dissimilarity measures for default coverage values. In addition, this function also computes standardized 3D estimates with a particular vector of user-specified sample sizes or coverage values.

2. ggiNEXTbeta3D visualizes the output from the function iNEXTbeta3D.

3. DataInfobeta3D provides basic data information for (1) the reference sample in each assemblage, (2) the gamma reference sample in the pooled assemblage, and (3) the alpha reference sample in the joint assemblage.

Author(s)

Anne Chao, K.H. Hu

Maintainer: Anne Chao <[email protected]>

References

Chao, A., Chiu, C.-H., Hu, K.-H., and Zeleny, D. (2023a). Revisiting Alwyn H. Gentry's forest transect data: a statistical sampling-model-based approach. Japanese Journal of Statistics and Data Science, 6, 861-884. https://doi.org/10.1007/s42081-023-00214-1

Chao, A., Henderson, P. A., Chiu, C.-H., Moyes, F., Hu, K.-H., Dornelas, M. and Magurran, A. E. (2021). Measuring temporal change in alpha diversity: a framework integrating taxonomic, phylogenetic and functional diversity and the iNEXT.3D standardization. Methods in Ecology and Evolution, 12, 1926-1940.

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

---

Species pairwise distance matrix for species in the dataset Brazil_rainforests

Description

This dataset includes a tree species pairwise symmetric distance matrix for 243 species listed in the Brazil_rainforests dataset. Each element in the matrix represents a Gower distance between two species computed from species traits.

Usage

data(Brazil_distM)

Format

Brazil_distM is a 243 x 243 (species by species) symmetric data.frame. Each element of the data.frame is between zero (for species pairs with identical traits) and one.
$ Carpotroche_brasiliensis : num 0 0.522 0.522 0.253 0.396 ...
$ Astronium_concinnum : num 0.522 0 0 0.525 0.625 ...
$ Astronium_graveolens : num 0.522 0 0 0.525 0.625 ...
.......

---

Brazil rainforests data (datatype = "abundance" for TD, PD, and FD)

Description

This dataset includes tree species abundace counts in three rainforests (Marium, Rebio2, and Rochedo) collected from rainforests in Brazil by Magnago et al. (2014, 2015, 2017). Within each forest, there are two assemblages/habitats (Edge and Interior). The data are slightly different from those used in Chao et al. (2023) because some species are excluded due to lack of phylogeny information.

Usage

data(Brazil_rainforests)

Format

Brazil_rainforests is a list with three species-by-assemblage data.frames/matrices. The two columns represents the Edge and Interior habitats.
A list of 3 matrices:
$ Marim is a matrix with 243 species(rows) and 2 columns ("Edge" and "Interior").
$ Rebio2 is a matrix with 243 species(rows) and 2 columns ("Edge" and "Interior").
$ Rochedo is a matrix with 243 species(rows) and 2 columns ("Edge" and "Interior").

References

Chao, A., Henderson, P. A., Chiu, C.-H., Moyes, F., Hu, K.-H., Dornelas, M. and Magurran, A. E. (2021). Measuring temporal change in alpha diversity: a framework integrating taxonomic, phylogenetic and functional diversity and the iNEXT.3D standardization. Methods in Ecology and Evolution, 12, 1926-1940.

Magnago, L. F. S., Edwards, D. P., Edwards, F. A., Magrach, A., Martins, S. V., & Laurance, W. F. (2014). Functional attributes change but functional richness is unchanged after fragmentation of Brazilian Atlantic forests. Journal of Ecology, 102, 475-485.

Magnago, L. F. S., Magrach, A., Barlow, J., Schaefer, C. E. G. R., Laurance, W. F., Martins, S. V., & Edwards, D. P. (2017). Do fragment size and edge effects predict carbon stocks in trees and lianas in tropical forests? Functional Ecology, 31, 542-552.

Magnago, L. F. S., Rocha, M. F., Meyer, L., Martins, S. V., & Meira-Neto, J. A. A. (2015). Microclimatic conditions at forest edges have significant impacts on vegetation structure in large Atlantic forest fragments. Biodiversity and Conservation, 24, 2305-2318.

---

Phylogenetic tree for Brazil abundance data

Description

This dataset includes a phylogenetic tree spanned by 243 species listed in the Brazil_rainforests dataset.

Usage

data(Brazil_tree)

Format

Brazil_tree is a list (phylo tree) with the following phylogenetic information:
A list of 5:
$ edge : int [1:382, 1:2] 244 245 246 247 248 249 250 251 251 252 ...
$ edge.length: num [1:382] 75 146 8 6 18 10 10 127 6 23 ...
$ Nnode : int 140
$ node.label : chr [1:140] "magnoliales_to_asterales" "poales_to_asterales" ...
$ tip.label : chr [1:243] "Carpotroche_brasiliensis" "Casearia_ulmifolia" "Casearia_sp4" ...

---

Data information for reference samples

Description

DataInfobeta3D provides basic data information for (1) the reference sample in each assemblage, (2) the gamma reference sample in the pooled assemblage, and (3) the alpha reference sample in the joint assemblage for TD, PD and FD.

Usage

DataInfobeta3D(
  data,
  diversity = "TD",
  datatype = "abundance",
  PDtree = NULL,
  PDreftime = NULL,
  FDdistM = NULL,
  FDtype = "AUC",
  FDtau = NULL,
  by_pair = FALSE
)

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.
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).
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).
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_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).
by_pair	a logical variable specifying whether to perform diversity decomposition for all pairs of assemblages or not. If by_pair = TRUE, alpha/beta/gamma diversity will be computed for all pairs of assemblages in the input data; if by_pair = FALSE, alpha/beta/gamma diversity will be computed for multiple assemblages (i.e, more than two assemblages) in the input data. Default is FALSE.

Value

a data.frame including basic data information.

For abundance data, basic information shared by TD, mean-PD and FD includes dataset name (Dataset), combinations of assemblage pairs (Pair, if calculating not by pairs, then there is no such column), individual/pooled/joint assemblage (Assemblage), sample size (n), observed species richness (S.obs), sample coverage estimates of the reference sample (SC(n)), sample coverage estimate for twice the reference sample size (SC(2n)). Other additional information is given below.

(1) TD: the first five species abundance frequency counts in the reference sample (f1–f5).

(2) Mean-PD: the the observed total branch length in the phylogenetic tree (PD.obs), the number of singletons (f1*) and doubletons (f2*) in the node/branch abundance set, as well as the total branch length of those singletons (g1) and of those doubletons (g2), and the reference time (Reftime).

(3) FD (FDtype = "AUC"): the minimum distance (dmin) and the maximum distance (dmax) among all non-diagonal elements in the distance matrix, and the mean distance between any two individuals randomly selected from the dataset (dmean).

(4) FD (FDtype = "tau_value"): the number of singletons (a1*) and of doubletons (a2*) among the functionally indistinct set at the specified threshold level 'Tau', as well as the total contribution of singletons (h1) and of doubletons (h2) at the specified threshold level 'Tau'.

For incidence data, the basic information for TD includes dataset name (Dataset), combinations of assemblage pairs (Pair, if calculating not by pairs, then there is no such column), individual/pooled/joint assemblage (Assemblage), number of sampling units (T), total number of incidences (U), observed species richness (S.obs), sample coverage estimates of the reference sample (SC(T)), sample coverage estimate for twice the reference sample size (SC(2T)), as well as the first five species incidence frequency counts (Q1–Q5) in the reference sample. For mean-PD and FD, output is similar to that for abundance data.

Examples

## (Data Information) Taxonomic diversity for abundance data (not by pairs)
data(Brazil_rainforests)
info_TD_abun = DataInfobeta3D(data = Brazil_rainforests[1:2], diversity = 'TD', 
                              datatype = 'abundance')
info_TD_abun


## (Data Information) Taxonomic diversity for abundance data for all pairs of assemblages
data = list("Edge"     = sapply(Brazil_rainforests, function(x) x[,1]),
            "Interior" = sapply(Brazil_rainforests, function(x) x[,2]))
info_TD_abun_pair = DataInfobeta3D(data = data, diversity = 'TD', datatype = 'abundance',
                                   by_pair = TRUE)
info_TD_abun_pair


## (Data Information) Taxonomic diversity for incidence data (not by pairs)
data(Second_growth_forests)
data = list("CR 2005 vs. 2017" = Second_growth_forests[[1]][c(1,3)],
            "JE 2005 vs. 2017" = Second_growth_forests[[2]][c(1,3)])
info_TD_inci = DataInfobeta3D(data = data, diversity = 'TD',
                              datatype = 'incidence_raw')
info_TD_inci


## (Data Information) Taxonomic diversity for incidence data for all pairs of assemblages
data(Second_growth_forests)
info_TD_inci_pair = DataInfobeta3D(data = Second_growth_forests, diversity = 'TD',
                                   datatype = 'incidence_raw', by_pair = TRUE)
info_TD_inci_pair


## (Data Information) Mean phylogenetic diversity for abundance data (not by pairs)
data(Brazil_rainforests)
data(Brazil_tree)
info_PD_abun = DataInfobeta3D(data = Brazil_rainforests[1:2], diversity = 'PD', 
                              datatype = 'abundance', PDtree = Brazil_tree, PDreftime = NULL)
info_PD_abun


## (Data Information) Functional diversity for abundance data under a specified threshold level
## (not by pairs)
data(Brazil_rainforests)
data(Brazil_distM)
info_FDtau_abun = DataInfobeta3D(data = Brazil_rainforests[1:2], diversity = 'FD', 
                                 datatype = 'abundance', FDdistM = Brazil_distM, 
                                 FDtype = 'tau_value', FDtau = NULL)
info_FDtau_abun


## (Data Information) Functional diversity for abundance data when all threshold levels
## from 0 to 1 are considered (not by pairs)
data(Brazil_rainforests)
data(Brazil_distM)
info_FDAUC_abun = DataInfobeta3D(data = Brazil_rainforests[1:2], diversity = 'FD', 
                                 datatype = 'abundance', FDdistM = Brazil_distM, FDtype = 'AUC')
info_FDAUC_abun

---

ggplot2 extension for the iNEXTbeta3D object

Description

ggiNEXTbeta3D is an ggplot2 extension for the iNEXTbeta3D object to plot sample-size- and coverage-based rarefaction/extrapolation curves. (only accept the outcome from iNEXTbeta3D under by_pair = FALSE)

Usage

ggiNEXTbeta3D(output, type = "B")

Arguments

output	output from the function iNEXTbeta3D.
type	(argument only for base = "coverage"), type = 'B' for plotting the rarefaction and extrapolation sampling curves for gamma, alpha, and beta diversity; type = 'D' for plotting the rarefaction and extrapolation sampling curves for four dissimilarity indices. Skip the argument for plotting size-based rarefaction and extrapolation sampling curves for gamma and alpha diversity.

Value

a figure for gamma, alpha, and beta diversity, or a figure for four dissimilarity indices for base = "coverage"; or a figure for gamma and alpha diversity when base = "size".

Examples

## (Graphic Display) Taxonomic diversity for abundance data
# Coverage-based rarefaction and extrapolation sampling curves 
data(Brazil_rainforests)
output_TDc_abun = iNEXTbeta3D(data = Brazil_rainforests[1:2], diversity = 'TD', 
                              datatype = 'abundance', base = "coverage", nboot = 10)

ggiNEXTbeta3D(output_TDc_abun, type = 'B')
ggiNEXTbeta3D(output_TDc_abun, type = 'D')


# Size-based rarefaction and extrapolation sampling curves 
data(Brazil_rainforests)
output_TDs_abun = iNEXTbeta3D(data = Brazil_rainforests[1:2], diversity = 'TD', 
                              datatype = 'abundance', base = "size", nboot = 10)

ggiNEXTbeta3D(output_TDs_abun)


## (Graphic Display) Taxonomic diversity for incidence data
# Coverage-based rarefaction and extrapolation sampling curves 
data(Second_growth_forests)
data = list("CR 2005 vs. 2017" = Second_growth_forests[[1]][c(1,3)],
            "JE 2005 vs. 2017" = Second_growth_forests[[2]][c(1,3)])
output_TDc_inci = iNEXTbeta3D(data = data, diversity = 'TD', 
                              datatype = 'incidence_raw', base = "coverage", nboot = 10)

ggiNEXTbeta3D(output_TDc_inci, type = 'B')
ggiNEXTbeta3D(output_TDc_inci, type = 'D')


# Size-based rarefaction and extrapolation sampling curves 
data(Second_growth_forests)
data = list("CR 2005 vs. 2017" = Second_growth_forests[[1]][c(1,3)],
            "JE 2005 vs. 2017" = Second_growth_forests[[2]][c(1,3)])
output_TDs_inci = iNEXTbeta3D(data = data, diversity = 'TD', 
                              datatype = 'incidence_raw', base = "size", nboot = 10)

ggiNEXTbeta3D(output_TDs_inci)


## (Graphic Display) Phylogenetic diversity for abundance data
# Coverage-based rarefaction and extrapolation sampling curves 
data(Brazil_rainforests)
data(Brazil_tree)
output_PDc_abun = iNEXTbeta3D(data = Brazil_rainforests[1:2], diversity = 'PD', 
                              datatype = 'abundance', base = "coverage", nboot = 10, 
                              PDtree = Brazil_tree, PDreftime = NULL, PDtype = 'meanPD')

ggiNEXTbeta3D(output_PDc_abun, type = 'B')
ggiNEXTbeta3D(output_PDc_abun, type = 'D')


# Size-based rarefaction and extrapolation sampling curves 
data(Brazil_rainforests)
data(Brazil_tree)
output_PDs_abun = iNEXTbeta3D(data = Brazil_rainforests[1:2], diversity = 'PD', 
                              datatype = 'abundance', base = "size", nboot = 10, 
                              PDtree = Brazil_tree, PDreftime = NULL, PDtype = 'meanPD')

ggiNEXTbeta3D(output_PDs_abun)


## (Graphic Display) Functional diversity for abundance data when all threshold levels 
## from 0 to 1 are considered
# Coverage-based rarefaction and extrapolation sampling curves 
data(Brazil_rainforests)
data(Brazil_distM)
output_FDc_abun = iNEXTbeta3D(data = Brazil_rainforests[1:2], diversity = 'FD', 
                              datatype = 'abundance', base = "coverage", nboot = 10, 
                              FDdistM = Brazil_distM, FDtype = 'AUC', FDcut_number = 30)

ggiNEXTbeta3D(output_FDc_abun, type = 'B')
ggiNEXTbeta3D(output_FDc_abun, type = 'D')


# Size-based rarefaction and extrapolation sampling curves 
data(Brazil_rainforests)
data(Brazil_distM)
output_FDs_abun = iNEXTbeta3D(data = Brazil_rainforests[1:2], diversity = 'FD', 
                              datatype = 'abundance', base = "size", nboot = 10, 
                              FDdistM = Brazil_distM, FDtype = 'AUC', FDcut_number = 30)

ggiNEXTbeta3D(output_FDs_abun)

---

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,
  by_pair = FALSE
)

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.
by_pair	a logical variable specifying whether to perform diversity decomposition for all pairs of assemblages or not. If by_pair = TRUE, alpha/beta/gamma diversity will be computed for all pairs of assemblages in the input data; if by_pair = FALSE, alpha/beta/gamma diversity will be computed for multiple assemblages (i.e, more than two assemblages) in the input data. Default is FALSE.

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.
Pair	combinations of assemblage pairs; if calculating not by pairs, then there is no such column
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 (not by pairs)
data(Brazil_rainforests)
output_TDc_abun = iNEXTbeta3D(data = Brazil_rainforests[1:2], diversity = 'TD', 
                              datatype = 'abundance', base = "coverage", nboot = 10)
output_TDc_abun


# Coverage-based standardized TD estimates and related statistics for all pairs of 
# assemblages by user-specified coverage values
data(Brazil_rainforests)
data = list("Edge"     = sapply(Brazil_rainforests, function(x) x[,1]),
            "Interior" = sapply(Brazil_rainforests, function(x) x[,2]))
output_TDc_abun_byuser = iNEXTbeta3D(data = data, diversity = 'TD', 
                                     datatype = 'abundance', base = "coverage", nboot = 10,
                                     level = c(0.85, 0.9), by_pair = TRUE)
output_TDc_abun_byuser


# Size-based standardized TD estimates and related statistics (not by pairs)
data(Brazil_rainforests)
output_TDs_abun = iNEXTbeta3D(data = Brazil_rainforests[1:2], diversity = 'TD', 
                              datatype = 'abundance', base = "size", nboot = 10)
output_TDs_abun


# Size-based standardized TD estimates and related statistics for all pairs of 
# assemblages by user-specified sample sizes
data(Brazil_rainforests)
data = list("Edge"     = sapply(Brazil_rainforests, function(x) x[,1]),
            "Interior" = sapply(Brazil_rainforests, function(x) x[,2]))
output_TDs_abun_byuser = iNEXTbeta3D(data = data, diversity = 'TD', 
                                     datatype = 'abundance', base = "size", nboot = 10,
                                     level = c(300, 500), by_pair = TRUE)
output_TDs_abun_byuser


## (R/E Analysis) Taxonomic diversity for incidence data
# Coverage-based standardized TD estimates and related statistics (not by pairs)
data(Second_growth_forests)
data = list("CR 2005 vs. 2017" = Second_growth_forests[[1]][c(1,3)],
            "JE 2005 vs. 2017" = Second_growth_forests[[2]][c(1,3)])
output_TDc_inci = iNEXTbeta3D(data = data, diversity = 'TD', 
                              datatype = 'incidence_raw', base = "coverage", nboot = 10)
output_TDc_inci


# Coverage-based standardized TD estimates and related statistics for all pairs of 
# assemblages 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), by_pair = TRUE)
output_TDc_inci_byuser


# Size-based standardized TD estimates and related statistics (not by pairs)
data(Second_growth_forests)
data = list("CR 2005 vs. 2017" = Second_growth_forests[[1]][c(1,3)],
            "JE 2005 vs. 2017" = Second_growth_forests[[2]][c(1,3)])
output_TDs_inci = iNEXTbeta3D(data = data, diversity = 'TD', 
                              datatype = 'incidence_raw', base = "size", nboot = 10)
output_TDs_inci


# Size-based standardized TD estimates and related statistics for all pairs of 
# assemblages 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), by_pair = TRUE)
output_TDs_inci_byuser


## (R/E Analysis) Phylogenetic diversity for abundance data
# Coverage-based standardized PD estimates and related statistics (not by pairs)
data(Brazil_rainforests)
data(Brazil_tree)
output_PDc_abun = iNEXTbeta3D(data = Brazil_rainforests[1:2], 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 (not by pairs)
data(Brazil_rainforests)
data(Brazil_tree)
output_PDs_abun = iNEXTbeta3D(data = Brazil_rainforests[1:2], 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 (not by pairs)
data(Brazil_rainforests)
data(Brazil_distM)
output_FDc_abun = iNEXTbeta3D(data = Brazil_rainforests[1:2], 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 (not by pairs)
data(Brazil_rainforests)
data(Brazil_distM)
output_FDs_abun = iNEXTbeta3D(data = Brazil_rainforests[1:2], diversity = 'FD', 
                              datatype = 'abundance', base = "size", nboot = 10, 
                              FDdistM = Brazil_distM, FDtype = 'AUC', FDcut_number = 30)
output_FDs_abun

---

Printing iNEXTbeta3D object

Description

print.iNEXTbeta3D: Print method for objects inheriting from class "iNEXTbeta3D"

Usage

## S3 method for class 'iNEXTbeta3D'
print(x, ...)

Arguments

x	an iNEXTbeta3D object computed by iNEXTbeta3D.
...	additional arguments.

Value

a list of multiple objects (see iNEXTbeta3D for more details) with simplified outputs.

---

Second-growth forests data (datatype = "incidence_raw" for taxonomic diversity)

Description

This dataset includes tree incidence data in 100 subplots (each with 0.01 ha) collected from two second-growth forests, namely Cuatro Rios (CR) and Juan Enriquez (JE) in Costa Rica. Each 1-ha forest was divided into 100 subplots (each with 0.01 ha) and only species' incidence records in each subplot were used to compute the incidence frequency for a species (i.e., the number of subplots in which that species occurred); see Chazdon et al. (2021, 2022) for sampling details and pertinent analyses. The original time series data covers 2005 to 2017; here only three-year data (2005, 2011, and 2017) are used for assessing temporal beta diversity between the three years within each forest.

Usage

data(Second_growth_forests)

Format

Second_growth_forests is a list with three forests. The input format for each forests is a list with three species-by-sampling-units matrices ("Year_2005", "Year_2011", and "Year_2017"). Each matrix record the species as 0 (undetect) or 1 (detect) in each sampling units.
A list of 2
$ CR 2005 vs. 2011 vs. 2017: A list of 3
.. ..$ Year_2005 (152 (species) x 100 (quadrats))
.. ..$ Year_2011 (152 (species) x 100 (quadrats))
.. ..$ Year_2017 (152 (species) x 100 (quadrats))
$ JE 2005 vs. 2011 vs. 2017: A list of 3
.. ..$ Year_2005 (108 (species) x 100 (quadrats))
.. ..$ Year_2011 (108 (species) x 100 (quadrats))
.. ..$ Year_2017 (108 (species) x 100 (quadrats))

References

Chazdon, R. (2021). Tree abundance in eight 1-ha tropical forest plots in northeastern Costa Rica from 1997-2017, https://doi.org/10.5061/dryad.ncjsxksvr

Chazdon, R. L., N. Norden, R. K. Colwell, and A. Chao. (2022). Monitoring recovery of tree diversity during tropical forest restoration: lessons from long-term trajectories of natural regeneration. Philosophical Transactions of the Royal Society B, 378: 20210069.

---