Interpolation and Extrapolation for three dimensions of biodiversity

Description

iNEXT.3D (iNterpolation and EXTrapolation for three dimensions of biodiversity) is a sequel to iNEXT (Hsieh et al., 2016). Here the three dimensions (3D) of diversity refer to taxonomic diversity (TD), phylogenetic diversity (PD) and functional diversity (FD). An online version "iNEXT.3D Online" (https://chao.shinyapps.io/iNEXT_3D/) 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, 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. (2014) for the basic standardization theory for TD, and Chao et al. (2021) for a review of the unified theory for 3D.

For each of the three dimensions of biodiversity, iNEXT.3D features two statistical analyses (non-asymptotic and asymptotic):

(1) A non-asymptotic approach based on interpolation and extrapolation for 3D diversity (i.e., Hill-Chao numbers)

iNEXT.3D computes the estimated 3D diversity for standardized samples with a common sample size or sample completeness. This approach aims to compare diversity estimates for equally-large (with a common sample size) or equally-complete (with a common sample coverage) samples; it is based on the seamless rarefaction and extrapolation (R/E) sampling curves of Hill-Chao numbers for q = 0, 1 and 2. For each dimension of biodiversity, iNEXT.3D offers three types of R/E sampling curves:

* Sample-size-based (or size-based) R/E sampling curves: This type of sampling curve plots the diversity estimates with respect to sample size.

* Coverage-based R/E sampling curves: This type of sampling curve plots the diversity estimates with respect to sample coverage.

* Sample completeness curve: This curve depicts how sample coverage varies with sample size. The sample completeness curve provides a bridge between the size- and coverage-based R/E sampling curves.

(2) An asymptotic approach to infer asymptotic 3D diversity (i.e., Hill-Chao numbers)

iNEXT.3D computes the estimated asymptotic 3D diversity and also plots 3D diversity profiles (q-profiles) for q between 0 and 2, in comparison with the observed diversity. Typically, the asymptotic estimates for q \geq 1 are reliable, but for q < 1 (especially for q = 0, species richness), the asymptotic estimates represent only lower bounds. iNEXT.3D also features a time-profile (which depicts the observed and asymptotic estimate of PD or mean PD with respect to reference times), and a tau-profile (which depicts the observed and asymptotic estimate of FD with respect to threshold level tau).

There are six main functions in this package:

1. iNEXT3D computes standardized 3D diversity of order q = 0, 1 and 2 for rarefied and extrapolated samples at specified sample coverage values and sample sizes.

2. ggiNEXT3D visualizes the output from the function iNEXT3D.

3. ObsAsy3D computes observed and asymptotic diversity of order q between 0 and 2 (in increments of 0.2) for 3D diversity; it also computes observed and asymptotic PD for specified reference times, and observed and asymptotic FD for specified threshold levels.

4. ggObsAsy3D visualizes the output from the function ObsAsy3D.

5. estimate3D computes 3D diversity of order q = 0, 1 and 2 with a particular set of user-specified level of sample sizes or sample coverage values.

6. DataInfo3D provides basic data information based on the observed data.

Author(s)

Anne Chao, Kai-Hsiang Hu

Maintainer: Anne Chao <chao@stat.nthu.edu.tw>

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.

Hsieh, T. C., Ma, K. H. and Chao, A. (2016). iNEXT: An R package for rarefaction and extrapolation of species diversity (Hill numbers). Methods in Ecology and Evolution, 7, 1451-1456.

Abundance data (datatype = "abundance")

Description

This dataset includes tree species abundances in two assemblages/habitats (Edge and Interior) collected from rainforests in Brazil by Magnago et al. (2014, 2015, 2017).

Usage

data(Brazil_rainforest_abun_data)

Format

Brazil_rainforest_abun_data is a species-by-assemblages data.frame (in addition to species names and assemblage names) with 425 tree species and two assemblages (Edge and Interior).
$ Edge: int 11 110 36 12 2 7 11 1 1 0 ...
$ Interior: int 21 11 7 1 0 1 11 13 1 2 ...

References

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.

Species pairwise distance matrix for species in the dataset Brazil_rainforest_abun_data

Description

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

Usage

data(Brazil_rainforest_distance_matrix)

Format

Brazil_rainforest_distance_matrix is a 425 x 425 (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.263 ...
$ Astronium_concinnum: num 0.522 0 0 0.525 0.509 ...
$ Astronium_graveolens: num 0.522 0 0 0.525 0.509 ...
.......

Phylogenetic tree for Brazil_rainforest_abun_data

Description

This dataset includes a phylogenetic tree spanned by 425 species listed in the dataset Brazil_rainforest_abun_data.

Usage

data(Brazil_rainforest_phylo_tree)

Format

Brazil_rainforest_phylo_tree is a list with the following phylogenetic information:
A list of 5:
$ edge: int [1:629, 1:2] 426 427 428 429 430 431 427 428 429 430 ...
$ edge.length: num [1:629] 75 146 8 6 4 14 10 10 127 6 ...
$ Nnode: int 205
$ node.label: chr [1:205] "magnoliales_to_asterales" "poales_to_asterales" ...
$ tip.label: chr [1:425] "Carpotroche_brasiliensis" "Casearia_ulmifolia" "Casearia_sp4" ...

Data information for reference samples

Description

DataInfo3D provides basic data information for 3D diversity based on a reference sample.

Usage

DataInfo3D(
  data,
  diversity = "TD",
  datatype = "abundance",
  nT = NULL,
  PDtree,
  PDreftime = NULL,
  FDdistM,
  FDtype = "AUC",
  FDtau = NULL
)

Arguments

Value

a data.frame including basic data information.

For abundance data, basic information shared by TD, mean-PD and FD includes assemblage name (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 counts (f1–f5).

(2) Mean-PD: 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 among all non-diagonal elements in the distance matrix (dmin), the mean distance (dmean), and the maximum distance (dmax) in the distance matrix.

(4) FD (FDtype = "tau_values"): 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 attribute contribution of singletons (h1) and of doubletons (h2) at the specified threshold level 'Tau'.

For incidence data, the basic information for TD includes assemblage name (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). For mean-PD and FD, output is similar to that for abundance data.

Examples

# Taxonomic diversity for abundance data
data(Brazil_rainforest_abun_data)
DataInfo3D(Brazil_rainforest_abun_data, diversity = 'TD', datatype = "abundance")


# Phylogenetic diversity for abundance data
data(Brazil_rainforest_abun_data)
data(Brazil_rainforest_phylo_tree)
data <- Brazil_rainforest_abun_data
tree <- Brazil_rainforest_phylo_tree
DataInfo3D(data, diversity = 'PD', datatype = "abundance", PDtree = tree)


# Functional diversity for abundance data with FDtype = 'AUC'
data(Brazil_rainforest_abun_data)
data(Brazil_rainforest_distance_matrix)
data <- Brazil_rainforest_abun_data
distM <- Brazil_rainforest_distance_matrix
DataInfo3D(data, diversity = 'FD', datatype = "abundance", 
           FDdistM = distM, FDtype = 'AUC')
           
# Functional diversity for abundance data with FDtype = 'tau_values'
data(Brazil_rainforest_abun_data)
data(Brazil_rainforest_distance_matrix)
data <- Brazil_rainforest_abun_data
distM <- Brazil_rainforest_distance_matrix
DataInfo3D(data, diversity = 'FD', datatype = "abundance", 
           FDdistM = distM, FDtype = 'tau_values')


# Taxonomic diversity for incidence data
data(Fish_incidence_data)
DataInfo3D(Fish_incidence_data, diversity = 'TD', datatype = "incidence_raw")


# Phylogenetic diversity for incidence data
data(Fish_incidence_data)
data(Fish_phylo_tree)
data <- Fish_incidence_data
tree <- Fish_phylo_tree
DataInfo3D(data, diversity = 'PD', datatype = "incidence_raw", PDtree = tree)


# Functional diversity for incidence data with FDtype = 'AUC'
data(Fish_incidence_data)
data(Fish_distance_matrix)
data <- Fish_incidence_data
distM <- Fish_distance_matrix
DataInfo3D(data, diversity = 'FD', datatype = "incidence_raw", 
           FDdistM = distM, FDtype = 'AUC')
           
# Functional diversity for incidence data with FDtype = 'tau_values'
data(Fish_incidence_data)
data(Fish_distance_matrix)
data <- Fish_incidence_data
distM <- Fish_distance_matrix
DataInfo3D(data, diversity = 'FD', datatype = "incidence_raw", 
           FDdistM = distM, FDtype = 'tau_values')

Species pairwise distance matrix for species in the dataset Fish_incidence_data

Description

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

Usage

data(Fish_distance_matrix)

Format

Fish_distance_matrix is a 88 x 88 (species by species) symmetric data.frame. Each element of the data.frame is between zero (for species pairs with identical traits) and one.
$ Agonus_cataphractus: num 0 0.326 0.280 0.055 0.093 ...
$ Alosa_fallax: num 0.326 0 0.380 0.336 0.311 ...
$ Ammodytes_marinus: num 0.280 0.380 0 0.243 0.364 ...
.......

Incidence data (datatype = "incidence_raw")

Description

This dataset includes incidence-based occurrence records of estuarine fishes collected at Bridgwater Bay in UK's Bristol Channel (Chao et al. 2021). There are two time periods ("2013-2015" and "2016-2018"). Each time period is designated as an assemblage. The purpose was to compare 3D diversity of the two time periods. In each time period, species incidence was recorded in 36 sampling units in each assemblage; each sampling unit represents a sampling date. This dataset is a list of two data frames with each representing species-by-sampling-unit raw incidence (detection/non-detection) matrix.

Usage

data(Fish_incidence_data)

Format

Fish_incidence_data is a list of two species-by-sampling-unit data frames for 88 species and 36 sampling units. Each element in the data frame is 1 for a detection, and 0 for a non-detection.
A list of 2:
$ 2013-2015: int [1:88, 1:36] 0 0 0 0 0 0 0 0 0 0 ...
$ 2016-2018: int [1:88, 1:36] 1 0 0 0 0 0 0 0 0 0 ...

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.

Phylogenetic tree for Fish_incidence_data

Description

This dataset includes a phylogenetic tree spanned by 88 species listed in the Fish_incidence_data dataset.

Usage

data(Fish_phylo_tree)

Format

Fish_phylo_tree is a list with the following phylogenetic information:
A list of 5:
$ edge: int [1:172, 1:2] 89 90 91 92 93 94 95 95 94 96 ...
$ edge.length: num [1:172] 0.023 0.057 0.023 0.851 0.011 0.023 0.011 0.011 0.023 0.011 ...
$ Nnode: int 85
$ node.label: chr [1:85] "Vertebrata_-subphylum_in_Deuterostomia" ...
$ tip.label: chr [1:88] "Alosa_fallax" "Sardina_pilchardus" "Clupea_harengus" ...

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

Value

a data frame including the following information/statistics:

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

Compute 3D diversity estimates with a particular set of sample sizes/coverages

Description

estimate3D computes 3D diversity (Hill-Chao number with q = 0, 1 and 2) with a particular set of user-specified levels of sample sizes or sample coverages. If no sample sizes or coverages are specified, this function by default computes 3D diversity estimates for the minimum sample coverage or minimum sample size among all samples extrapolated to double reference sizes.

Usage

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

Arguments

Value

a data.frame of diversity table including the following arguments: (when base = "coverage")

Similar output is obtained for base = "size".

Examples

# Taxonomic diversity for abundance data with two target coverages (93% and 97%)
data(Brazil_rainforest_abun_data)
output_est_TD_abun <- estimate3D(Brazil_rainforest_abun_data, diversity = 'TD', q = c(0, 1, 2), 
                                 datatype = "abundance", base = "coverage", level = c(0.93, 0.97))
output_est_TD_abun


# Phylogenetic diversity for abundance data with two target sizes (1500 and 3500)
data(Brazil_rainforest_abun_data)
data(Brazil_rainforest_phylo_tree)
data <- Brazil_rainforest_abun_data
tree <- Brazil_rainforest_phylo_tree
output_est_PD_abun <- estimate3D(data, diversity = 'PD', datatype = "abundance", 
                                 base = "size", level = c(1500, 3500), PDtree = tree)
output_est_PD_abun


# Functional diversity for abundance data with two target coverages (93% and 97%)
data(Brazil_rainforest_abun_data)
data(Brazil_rainforest_distance_matrix)
data <- Brazil_rainforest_abun_data
distM <- Brazil_rainforest_distance_matrix
output_est_FD_abun <- estimate3D(data, diversity = 'FD', datatype = "abundance", 
                                 base = "coverage", level = c(0.93, 0.97), nboot = 10, 
                                 FDdistM = distM, FDtype = 'AUC')
output_est_FD_abun


# Taxonomic diversity for incidence data with two target coverages (97.5% and 99%)
data(Fish_incidence_data)
output_est_TD_inci <- estimate3D(Fish_incidence_data, diversity = 'TD', q = c(0, 1, 2), 
                                 datatype = "incidence_raw", base = "coverage", 
                                 level = c(0.975, 0.99))
output_est_TD_inci


# Phylogenetic diversity for incidence data with two target coverages (97.5% and 99%)
data(Fish_incidence_data)
data(Fish_phylo_tree)
data <- Fish_incidence_data
tree <- Fish_phylo_tree
output_est_PD_inci <- estimate3D(data, diversity = 'PD', datatype = "incidence_raw", 
                                 base = "coverage", level = c(0.975, 0.99), PDtree = tree)
output_est_PD_inci


# Functional diversity for incidence data with two target number of sampling units (30 and 70)
data(Fish_incidence_data)
data(Fish_distance_matrix)
data <- Fish_incidence_data
distM <- Fish_distance_matrix
output_est_FD_inci <- estimate3D(data, diversity = 'FD', datatype = "incidence_raw", 
                                 base = "size", level = c(30, 70), nboot = 10, 
                                 FDdistM = distM, FDtype = 'AUC')
output_est_FD_inci

ggplot2 extension for plotting q-profile, time-profile, and tau-profile

Description

ggObsAsy3D is a ggplot2 extension for an ObsAsy3D object to plot 3D q-profile (which depicts the observed diversity and asymptotic diversity estimate with respect to order q) for q between 0 and 2 (in increments of 0.2).

It also plots time-profile (which depicts the observed and asymptotic estimate of PD or mean PD with respect to reference times when diversity = "PD" specified in the ObsAsy3D function), and tau-profile (which depicts the observed and asymptotic estimate of FD with respect to threshold level tau when diversity = "FD" and FDtype = "tau_values" specified in the ObsAsy3D function) based on the output of ObsAsy3D.

In the plot of profiles, only confidence intervals of the asymptotic diversity will be shown when both the observed and asymptotic diversity estimates are computed.

Usage

ggObsAsy3D(output, profile = "q")

Arguments

Value

a q-profile, time-profile, or tau-profile based on the observed diversity and the asymptotic diversity estimate.

Examples

# Plot q-profile of 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")
ggObsAsy3D(output_ObsAsy_TD_abun)


# Plot time-profile of 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)
ggObsAsy3D(output_ObsAsy_PD_abun, profile = "time")


# Plot tau-profile of 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))
ggObsAsy3D(output_ObsAsy_FD_abun_tau, profile = "tau")


# Plot q-profile of 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')
ggObsAsy3D(output_ObsAsy_FD_abun, profile = "q")


# Plot q-profile of 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")
ggObsAsy3D(output_ObsAsy_TD_inci)


# Plot q-profile of 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)
ggObsAsy3D(output_ObsAsy_PD_inci, profile = "q")


# Plot q-profile of 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')
ggObsAsy3D(output_ObsAsy_FD_inci, profile = "q")

ggplot2 extension for an iNEXT3D object

Description

ggiNEXT3D is a ggplot extension for an iNEXT3D object to plot sample-size- and coverage-based rarefaction/extrapolation sampling curves along with a bridging sample completeness curve.

Usage

ggiNEXT3D(output, type = 1:3, facet.var = "Assemblage", color.var = "Order.q")

Arguments

Value

a ggplot2 object for sample-size-based rarefaction/extrapolation curve (type = 1), sample completeness curve (type = 2), and coverage-based rarefaction/extrapolation curve (type = 3).

Examples

# Plot three types of curves of taxonomic diversity with facet.var = "Assemblage"
# 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")
ggiNEXT3D(output_TD_abun, facet.var = "Assemblage")


# Plot two types (1 and 3) of curves 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)
ggiNEXT3D(output_PD_abun, type = c(1, 3))


# Plot three types of curves 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')
ggiNEXT3D(output_FD_abun)


# Plot three types of curves 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")
ggiNEXT3D(output_TD_inci)


# Plot three types of curves of phylogenetic diversity with facet.var = "Order.q"
#  and color.var = "Assemblage" 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)
ggiNEXT3D(output_PD_inci, facet.var = "Order.q", color.var = "Assemblage")


# Plot three types of curves 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')
ggiNEXT3D(output_FD_inci)

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

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:

Similar output is obtained for "$coverage_based".

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

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

Printing iNEXT3D object

Description

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

Usage

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

Arguments

Value

a list of three objects (see iNEXT3D for more details) with simplified outputs and notes.