Type: Package
Title: Interpolation and Extrapolation with Beta Diversity for Three Dimensions of Biodiversity
Version: 1.0.2
Author: Anne Chao [aut, cre], KaiHsiang Hu [ctb]
Maintainer: Anne Chao <chao@stat.nthu.edu.tw>
URL: https://sites.google.com/view/chao-lab-website/software/inext-beta3d
Description: As a sequel to 'iNEXT', the 'iNEXT.beta3D' package provides functions to compute standardized taxonomic, phylogenetic, and functional diversity (3D) estimates with a common sample size (for alpha and gamma diversity) or sample coverage (for alpha, beta, gamma diversity as well as dissimilarity or turnover indices). Hill numbers and their generalizations are used to quantify 3D and to make multiplicative decomposition (gamma = alpha x beta). The package also features size- and coverage-based rarefaction and extrapolation sampling curves to facilitate rigorous comparison of beta diversity across datasets. See Chao et al. (2023) <doi:10.1002/ecm.1588> for more details.
License: GPL (≥ 3)
Depends: R (≥ 4.0)
Imports: stats, magrittr, ggplot2, abind, iNEXT.3D, future.apply, tibble, dplyr, tidytree, tidyr, phyclust, ape
Suggests: testthat, knitr, rmarkdown, ggthemes
Encoding: UTF-8
BugReports: https://github.com/AnneChao/iNEXT.beta3D/issues
LazyData: yes
RoxygenNote: 7.2.3
VignetteBuilder: knitr
ByteCompile: true
Packaged: 2024-04-17 15:03:43 UTC; stat-pc
Repository: CRAN
NeedsCompilation: no
Date/Publication: 2024-04-17 19:40:11 UTC

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 <chao@stat.nthu.edu.tw>

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 185 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 185 x 185 (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.0.396 ...
$ Astronium_concinnum : num 0.522 0 0 0.525 0.0.625 ...
$ Astronium_graveolens : num 0.522 0 0 0.525 0.0.625 ...
.......

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

Description

This dataset includes tree species abundace counts in two rainforests (Marium and Rebio2) 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 two species-by-assemblage data.frames/matrices. The two columns represents the Edge and Interior habitats.
A list of 2 matrices:
$ Marim is a matrix with 119 species(rows) and 2 columns ("Edge" and "Interior").
$ Rebio2 is a matrix with 118 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 185 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:301, 1:2] 186 187 188 189 190 191 192 193 193 194 ...
$ edge.length: num [1:301] 75 146 8 6 18 10 10 127 6 23 ...
$ Nnode : int 117
$ node.label : chr [1:117] "magnoliales_to_asterales" "poales_to_asterales" ...
$ tip.label : chr [1:185] "Carpotroche_brasiliensis" "Casearia_ulmifolia" "Casearia_sp2" ...

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
)

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

Value

a data.frame including basic data information.

For abundance data, basic information shared by TD, mean-PD and FD includes dataset name (Dataset), 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), 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
data(Brazil_rainforests)
info_TD_abun = DataInfobeta3D(data = Brazil_rainforests, diversity = 'TD', datatype = 'abundance')
info_TD_abun


## (Data Information) Taxonomic diversity for incidence data
data(Second_growth_forests)
info_TD_inci = DataInfobeta3D(data = Second_growth_forests, diversity = 'TD',
                              datatype = 'incidence_raw')
info_TD_inci


## (Data Information) Mean phylogenetic diversity for abundance data
data(Brazil_rainforests)
data(Brazil_tree)
info_PD_abun = DataInfobeta3D(data = Brazil_rainforests, diversity = 'PD', 
                              datatype = 'abundance', PDtree = Brazil_tree, PDreftime = NULL)
info_PD_abun


## (Data Information) Functional diversity for abundance data under a specified threshold level
data(Brazil_rainforests)
data(Brazil_distM)
info_FDtau_abun = DataInfobeta3D(data = Brazil_rainforests, 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
data(Brazil_rainforests)
data(Brazil_distM)
info_FDAUC_abun = DataInfobeta3D(data = Brazil_rainforests, diversity = 'FD', 
                                 datatype = 'abundance', FDdistM = Brazil_distM, FDtype = 'AUC')
info_FDAUC_abun

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 two-year data (2005 and 2017) are used for assessing temporal beta diversity between the two years within each forest.

Usage

data(Second_growth_forests)

Format

Second_growth_forests is a list with two forests. The input format for each forests is a list with two species-by-sampling-units matrices ("Year_2005" 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. 2017: A list of 2
.. ..$ Year_2005 (151 (species) x 100 (quadrats))
.. ..$ Year_2017 (151 (species) x 100 (quadrats))
$ JE 2005 vs. 2017: A list of 2
.. ..$ Year_2005 (107 (species) x 100 (quadrats))
.. ..$ Year_2017 (107 (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.

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.

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, 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, 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)
output_TDc_inci = iNEXTbeta3D(data = Second_growth_forests, 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)
output_TDs_inci = iNEXTbeta3D(data = Second_growth_forests, 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, 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, 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, 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, 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
)

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

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.