matrix/data.frame. Users can input several datasets which may represent data collected from various localities, regions, plots, time periods, ..., etc. Input data for multiple datasets then consist of a list of matrices; each matrix represents a species-by-assemblage abundance matrix for one of the datasets. Different datasets can have different numbers of assemblages. `iNEXTbeta3D` computes beta diversity and dissimilarity among assemblages within each dataset.
2. Sampling-unit-based incidence raw data (`datatype = "incidence_raw"`):
Input data for a dataset with N assemblages consist of a list of matrices/data.frames, with each matrix representing a species-by-sampling-unit incidence raw matrix for one of the N assemblages; each element in the incidence raw matrix is 1 for a detection, and 0 for a non-detection. Users can input several datasets. Input data then consist of multiple lists with each list comprising a list of species-by-sampling-unit incidence matrices; see an example below. The number of sampling units can vary with datasets (but within a dataset, the number of sampling units in each assemblage must be the same). `iNEXTbeta3D` computes beta diversity and dissimilarity among assemblages within each dataset based on incidence-based frequency counts obtained from all sampling units.
#### Species abundance data format
We use the tree species abundance data collected from two rainforest fragments/localities in Brazil to assess beta diversity between Edge and Interior assemblages/habitats within each fragment; see Chao et al. (2023b) for analysis details. The data (named `"Brazil_rainforests"`) consist of a list of two matrices (for two fragments named "Marim" and "Rebio2", respectively); each matrix represents a species-by-assemblage abundance matrix, and there are two assemblages ("Edge" and "Interior") in each fragment. The demo data are slightly different from those analyzed in Chao et al. (2023b) because seven species are removed from the original pooled data due to lack of phylogenetic information. Run the following code to view the data: (Here we only show the first 15 rows for each matrix.)
```{r eval=FALSE}
data(Brazil_rainforests)
Brazil_rainforests
```
```{r echo=FALSE}
data(Brazil_rainforests)
lapply(Brazil_rainforests, function(x) x[1:15,])
```
#### Species incidence raw data format
We use tree species data collected from two second-growth rainforests, namely Cuatro Rios (CR) and Juan Enriquez (JE) in Costa Rica, as demo data to assess temporal beta diversity among three years (2005, 2011, and 2017) within each forest. Each year is designated as an assemblage. The data in each forest were collected from a 1-ha (50 m x 200 m) forest plot. Because individual trees of some species may exhibit intra-specific aggregation within a 1 ha area, they may not be suitable for modelling as independent sampling units. In this case, it is statistically preferable to first convert species abundance records in each forest to occurrence or incidence (detection/non-detection) data in subplots/quadrats; see Chao et al. (2023b) for analysis details.
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). By treating the incidence frequency of each species among subplots as a "proxy" for its abundance, the `iNEXT.beta3D` standardization can be adapted to deal with spatially aggregated data and to avoid the effect of intra-specific aggregation.
The data (named `"Second_growth_forests"`) consist of two lists (for two forests named `"CR_2005_2011_2017"` and `"JE_2005_2011_2017"`, respectively). Each list consists of three matrices; the first matrix represents the species-by-subplot incidence data in 2005, the second matrix represents the species-by-subplot incidence data in 2011, and the third matrix represents the species-by-subplot incidence data in 2017. Run the following code to view the incidence raw data: (Here we only show the first ten rows and six columns for each matrix; there are 100 columns/subplots in each forest and each year.)
```{r eval=FALSE}
data(Second_growth_forests)
Second_growth_forests
```
```{r echo=FALSE}
data(Second_growth_forests)
lapply(Second_growth_forests, function(x) lapply(x, function(y) y[1:10,1:6]))
```
#### Phylogenetic tree format for PD
To perform PD analysis, the phylogenetic tree (in Newick format) spanned by species observed in all datasets must be stored in a data file. For example, the phylogenetic tree for all observed species (including species in both "Marim" and "Rebio2" fragments) is stored in a data file named `"Brazil_tree"` for demonstration purpose. A partial list of the tip labels and node labels are shown below.
```{r}
data(Brazil_tree)
Brazil_tree
```
#### Species pairwise distance matrix format for FD
To perform FD analysis, the species-pairwise distance matrix (Gower distance computed from species traits) for species observed in all datasets must be stored in a matrix/data.frame format. Typically, the distance between any two species is computed from species traits using the Gower distance. In our demo data, the distance matrix for all species (including species in both "Marim" and "Rebio2" fragments) is stored in a data file named `"Brazil_distM"` for demonstration purpose. Here we only show the first three rows and three columns of the distance matrix.
```{r eval=FALSE}
data(Brazil_distM)
Brazil_distM
```
```{r echo=FALSE}
data(Brazil_distM)
round(Brazil_distM[1:3,1:3], 4)
```
## MAIN FUNCTION: iNEXTbeta3D()
We first describe the main function `iNEXTbeta3D()` with default arguments:
```{r eval=FALSE}
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 = 'AUC', PDcut_number = 30,
FDdistM = NULL, FDtype = "AUC", FDtau = NULL, FDcut_number = 30,
by_pair = FALSE)
```
The arguments of this function are briefly described below, and will be explained in more detail through illustrative examples in later text. By default (with the standardization base = "coverage"), this function computes coverage-based 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). If users set the standardization base to base="size", this function computes size-based standardized 3D gamma and alpha diversity estimates up to double the reference sample size in each dataset. In addition, this function also computes standardized 3D estimates
with a particular vector of user-specified sample sizes or coverage values.
| Argument | Description |
|---|---|
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: diversity = "TD" = Taxonomic diversity, diversity = "PD" = Phylogenetic diversity, and diversity = "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-unit incidence 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 size-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 coverage-based standardized 3D gamma, alpha, beta diversity, and four dissimilarity indices for coverage from 0.5 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 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 conf = 0.95. |
PDtree |
(required argument for diversity = "PD"), a phylogenetic tree in Newick format spanned by all observed species across the input datasets. |
PDreftime |
(argument only for diversity = "PD" and PDtype = "PD" or PDtype = "meanPD"), a numerical value specifying a fixed time reference point for phylogenetic diversity. Default is PDreftime = NULL, in which case the age of the root of the phylogenetic tree spanned by the pooled observed species is used.
|
PDtype |
(argument only for diversity = "PD"), select PD type: PDtype = "PD" for effective total branch length, PDtype = "meanPD" for effective number of equally divergent lineages, or PDtype = "AUC" for an overall measure that integrates mean phylogenetic diversity over all time reference points from zero to the age of the root. Default is PDtype = "AUC".
|
PDcut_number |
(argument only for diversity = "PD" and PDtype = "AUC"), a positive integer greater than one specifying the number of equally spaced time reference points between zero and the age of the root used to numerically approximate the AUC. Default is PDcut_number = 30. A larger value can be used to obtain a more accurate AUC approximation.
|
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 FDtau = NULL (default), then the 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 positive integer specifying the number of equally spaced sub-intervals used to partition the [0, 1] interval for numerical approximation of the AUC 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 used to obtain a more accurate AUC approximation. |
by_pair |
a logical variable specifying whether diversity decomposition is performed for all assemblages as a whole or for every pair of assemblages. If by_pair = FALSE, alpha/beta/gamma diversity and dissimilarity are computed for all assemblages within each dataset as a whole; if by_pair = TRUE, the corresponding output is computed for every pair of assemblages. Default is FALSE.
|
| Argument | Description |
|---|---|
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. |
type.
## TAXONOMIC DIVERSITY (TD): RAREFACTION/EXTRAPOLATION VIA EXAMPLES
### EXAMPLE 1: Abundance data with default sample sizes or coverage values
First, we run the `iNEXTbeta3D()` function with `Brazil_rainforests` abundance data to compute coverage-based taxonomic gamma, alpha, beta diversity, and four dissimilarity indices under `base = 'coverage'` by running the following code:
```{r eval=FALSE}
## Coverage-based R/E Analysis with taxonomic diversity for abundance data
data(Brazil_rainforests)
output_TDc_abun = iNEXTbeta3D(data = Brazil_rainforests, diversity = 'TD',
datatype = 'abundance', base = "coverage", nboot = 10)
output_TDc_abun
```
The output contains seven data frames: `gamma`, `alpha`, `beta`, `1-C`, `1-U`, `1-V`, `1-S`. Each data frame includes the dataset name (`Dataset`), combinations of assemblage pairs (`Pair`, if the calculation is not performed by pairs, this column is absent), the diversity order of q (`Order.q`), the target standardized coverage value (`SC`), the corresponding sample size (`Size`), the estimated diversity/dissimilarity value (`Alpha/Beta/Gamma/Dissimilarity`), `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), standard error of standardized estimate (`s.e.`), the bootstrap lower and upper confidence limits for the diversity/dissimilarity with a default significance level of 0.95 (`LCL`, `UCL`). These estimates and confidence intervals are then used to plot the rarefaction and extrapolation curves.
Our diversity/dissimilarity estimates and related statistics in the default output are displayed for the standardized coverage value from 0.5 to the coverage value of twice the reference sample size (for q = 0), or from 0.5 to 1.0 (for q = 1 and 2), in increments of 0.025. In addition, the results for the following four coverage value are also added: `SC(n, alpha)`, `SC(2n, alpha)`, `SC(n, gamma)` and `SC(2n, gamma)` if these values are in the above-specified range. Here `SC(n, alpha)` and `SC(2n, alpha)` represent, respectively, the coverage estimate for the alpha reference sample size n and the extrapolated sample with size 2n in the joint assemblage. These values can be found as `SC(n)` and `SC(2n)` for `"Joint assemblage (for alpha)"` in the column "Assemblage" from the output of the function `DataInfobeta3D`; see later text. Similar definitions pertain to `SC(n, gamma)` and `SC(2n, gamma)` for the gamma reference sample; these two values can also be found as `SC(n)` and `SC(2n)` for `"Pooled assemblage (for gamma)"` in the column "Assemblage" from the output of the function `DataInfobeta3D`. For beta diversity and dissimilarity, the observed sample coverage and extrapolation limit are defined the same as the alpha diversity. The corresponding coverage values for incidence data are denoted as, respectively, `SC(T, alpha)`, `SC(2T, alpha)`, `SC(T, gamma)` and `SC(2T, gamma)` in the output.
Because all the diversity/dissimilarity estimates are computed for the standardized coverage range values starting from 0.5, the default setting with `level = NULL` does not work if the observed sample coverage in the alpha/gamma reference sample is less than 50%. In this case, readers should specify sample coverage values using the argument `level`, instead of using `level = NULL`. The suggested maximum coverage value that readers can specify is `SC(2n, alpha)`. Beyond the limit, beta diversity and dissimilarity estimates may be subject to some bias. Below we show the output for taxonomic beta diversity between the "Edge" and "Interior" habitats in the "Marim" fragment.
```{r echo=FALSE}
output_TDc_abun = iNEXTbeta3D(data = Brazil_rainforests, diversity = 'TD',
datatype = 'abundance', base = "coverage", nboot = 10)
tmp = output_TDc_abun$Marim$beta
tmp[,c(3:5, 7:9)] = round(tmp[,c(3:5, 7:9)], 3)
tmp = tmp[,-ncol(tmp)]
tmp
```
Run the following code to display the two types of curves:
```{r, fig.align='center', fig.height=6, fig.width=6}
## Coverage-based R/E curves for taxonomic gamma, alpha and beta diversity
ggiNEXTbeta3D(output_TDc_abun, type = 'B')
```
```{r, fig.align='center', fig.height=8, fig.width=6}
## Coverage-based R/E curves for four taxonomic dissimilarity indices
ggiNEXTbeta3D(output_TDc_abun, type = 'D')
```
The following commands return the size-based R/E sampling curves for gamma and alpha taxonomic diversity:
```{r, fig.align='center', fig.height=5, fig.width=6}
## Size-based R/E curves with taxonomic gamma and alpha diversity
data(Brazil_rainforests)
output_TDs_abun = iNEXTbeta3D(data = Brazil_rainforests, diversity = 'TD',
datatype = 'abundance', base = "size", nboot = 10)
ggiNEXTbeta3D(output_TDs_abun)
```
### EXAMPLE 2: Incidence data with default sample sizes or coverage values (all assemblages as a whole)
We can also use incidence raw data (`Second_growth_forests`) to compute coverage-based standardized gamma, alpha, beta diversity, and four dissimilarities under `base = 'coverage'`, and also size-based standardized gamma and alpha diversity. Run the following code to perform incidence data analysis. The output data frame is similar to that based on abundance data and thus is omitted.
```{r eval=FALSE}
## Coverage-based R/E Analysis with taxonomic diversity for incidence raw data (all assemblages as a whole)
data(Second_growth_forests)
output_TDc_inci = iNEXTbeta3D(data = Second_growth_forests, diversity = 'TD',
datatype = 'incidence_raw', base = "coverage", nboot = 10)
output_TDc_inci
```
```{r echo=FALSE}
output_TDc_inci = iNEXTbeta3D(data = Second_growth_forests, diversity = 'TD',
datatype = 'incidence_raw', base = "coverage", nboot = 10)
# lapply(output_TDc_inci, function(x)
#
# lapply(x[1:3], function(y) {
#
# index1 = which(y$SC == min(y$SC))
# index2 = which( (y$Order.q != 0 & y$SC == max(y$SC)) | (y$Order.q == 0 & y$SC == max(y[y$Order.q == 0, "SC"])) )
# index3 = which(y$Method %in% c("Observed", "Observed_C(n, alpha)"))
#
# index = sort(unique(c(index1, index1 + 1, index2, index2 - 1, index3 - 1, index3, index3 + 1)))
#
# tmp = y[index,]
# tmp[,c(3:5, 7:9)] = round(tmp[,c(3:5, 7:9)], 3)
# tmp
# })
# )
```
The same procedures can be applied to incidence data. Based on the demo dataset, we display below the coverage-based R/E curves for temporal beta diversity among the three years (2005, 2011, and 2017)
in the two second-growth forests (CR and JE) by running the following code:
```{r, fig.align='center', fig.height=6, fig.width=6}
## Coverage-based R/E curves with taxonomic gamma, alpha and beta diversity
ggiNEXTbeta3D(output_TDc_inci, type = 'B')
```
The following commands return the size-based R/E sampling curves for gamma and alpha taxonomic diversity:
```{r, fig.align='center', fig.height=5, fig.width=6}
## Size-based R/E curves with taxonomic gamma and alpha diversity (all assemblages as a whole)
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)
```
### EXAMPLE 3: Incidence data for every pair of assemblages with user-specified sample sizes or coverage values
As with abundance data, user can also specify sample sizes (i.e. number of sampling units) or coverage values to obtain the pertinent output for every pair of assemblages. The code for examples is given below with two user-specified levels of sample coverage values (e.g., 90% and 95%), but the output is omitted.
```{r eval=FALSE}
## Coverage-based R/E Analysis for every pair of assemblages with taxonomic diversity for incidence data
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
```
The following commands return the TD estimates for every pair of assemblages with two user-specified levels of sample sizes (e.g., 100 and 200).
```{r eval=FALSE}
## Size-based R/E for every pair of assemblages with taxonomic gamma and alpha diversity
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
```
## PHYLOGENETIC DIVERSITY (PD): RAREFACTION/EXTRAPOLATION VIA EXAMPLES
### EXAMPLE 4: Abundance data with default sample sizes or coverage values
As with taxonomic diversity, `iNEXT.beta3D` computes coverage-based standardized phylogenetic gamma, alpha, beta diversity as well as four classes of phylogenetic dissimilarity indices; it also computes size-based standardized phylogenetic gamma and alpha diversity. The species names (or identification codes) in the phylogenetic tree must exactly match with those in the corresponding species abundance/incidence data. Two types of phylogenetic rarefaction and extrapolation curves (coverage- and size-based sampling curves) are also provided.
The required argument for performing PD analysis is `PDtree`. For example, the phylogenetic tree for all observed species (including species in both "Marim" and "Rebio2" fragments) is stored in a data file named `"Brazil_tree"`. Then we enter the argument `PDtree = Brazil_tree`. Three optional arguments are `PDtype`, `PDreftime`, and `PDcut_number`. There are three options for `PDtype`: `"PD"` (effective total branch length), `"meanPD"` (effective number of equally divergent lineages, meanPD = PD/tree depth), or `"AUC"` (an overall measure that integrates mean phylogenetic diversity over all time reference points from zero to the age of the root). Default is `PDtype = "AUC"`.
For `PDtype = "PD"` and `PDtype = "meanPD"`, `PDreftime` specifies a fixed time reference point for phylogenetic diversity. If `PDreftime = NULL`, the age of the root of the phylogenetic tree spanned by the pooled observed species is used.
For `PDtype = "AUC"`, mean phylogenetic diversity is integrated over all time reference points from zero to the age of the root. `PDcut_number` specifies the number of equally spaced time reference points used to numerically approximate the AUC.
Default is `PDcut_number = 30`. A larger value can be used to obtain a more accurate AUC approximation. Run the following code to perform PD analysis. The output data frame is similar to that based on abundance data and thus is omitted.
```{r eval=FALSE}
## Coverage-based R/E Analysis with phylogenetic diversity for abundance data
data(Brazil_rainforests)
data(Brazil_tree)
output_PDc_abun = iNEXTbeta3D(data = Brazil_rainforests, diversity = 'PD',
datatype = 'abundance', base = "coverage", nboot = 10,
PDtree = Brazil_tree, PDtype = 'AUC', PDcut_number = 30)
output_PDc_abun
```
```{r echo=FALSE}
data(Brazil_rainforests)
data(Brazil_tree)
output_PDc_abun = iNEXTbeta3D(data = Brazil_rainforests, diversity = 'PD',
datatype = 'abundance', base = "coverage", nboot = 10,
PDtree = Brazil_tree, PDtype = 'AUC', PDcut_number = 30)
```
Run the following code to display the R/E curves for phylogenetic gamma, alpha, and beta diversity:
```{r, fig.align='center', fig.height=6, fig.width=6}
## Coverage-based R/E sampling curves for phylogenetic gamma, alpha and beta diversity
ggiNEXTbeta3D(output_PDc_abun, type = 'B')
```
The following commands return the size-based R/E sampling curves for gamma and alpha phylogenetic diversity:
```{r, fig.align='center', fig.height=5, fig.width=6}
## Size-based R/E curves for phylogenetic gamma and alpha diversity
data(Brazil_rainforests)
data(Brazil_tree)
output_PDs_abun = iNEXTbeta3D(data = Brazil_rainforests, diversity = 'PD',
datatype = 'abundance', base = "size", nboot = 10,
PDtree = Brazil_tree, PDtype = 'AUC', PDcut_number = 30)
ggiNEXTbeta3D(output_PDs_abun)
```
## FUNCTIONAL DIVERSITY (FD): RAREFACTION/EXTRAPOLATION VIA EXAMPLES
### EXAMPLE 5: Abundance data with default sample sizes or coverage values
As with taxonomic and phylogenetic diversity, `iNEXT.beta3D` computes coverage-based standardized functional gamma, alpha, beta diversity as well as four classes of functional dissimilarity indices; it also computes size-based standardized functional gamma and alpha diversity. The species names (or identification codes) in the distance matrix must exactly match with those in the corresponding species abundance/incidence data. Two types of functional rarefaction and extrapolation curves (coverage- and size-based sampling curves) are also provided.
The required argument for performing FD analysis is `FDdistM`. For example, the distance matrix for all species (including species in both "Marim" and "Rebio2" fragments) is stored in a data file named `"Brazil_distM"`. Then we enter the argument `FDdistM = Brazil_distM`. Three optional arguments are (1) `FDtype`: `FDtype = "AUC"` means FD is computed from the area under the curve of a tau-profile by integrating all plausible threshold values between zero and one; `FDtype = "tau_value"` means FD is computed under a specific threshold value to be specified in the argument `FDtau`. (2) `FDtau`: a numerical value specifying the tau value (threshold level) that will be used to compute FD. If `FDtype = "tau_value"` and `FDtau = NULL`, then the threshold level is set to be the mean distance between any two individuals randomly selected from the pooled data over all datasets (i.e., quadratic entropy). (3) `FDcut_number` is a positive integer specifying the number of equally spaced sub-intervals used to partition the [0, 1] interval for numerical approximation of the AUC. Default is `FDcut_number = 30`. If more accurate integration is desired, then use a larger integer. Run the following code to perform FD analysis. The output data frame is similar to that based on abundance data and thus is omitted; see later graphical display of the output.
```{r eval=FALSE}
## Coverage-based R/E Analysis with functional diversity for abundance data - FDtype = 'AUC' (area
## under curve) by considering all threshold values between zero and one
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
```
```{r echo=FALSE}
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)
```
Run the following code to display the R/E curves for functional gamma, alpha, and beta diversity:
```{r, fig.align='center', fig.height=6, fig.width=6}
## Coverage-based R/E sampling curves for functional gamma, alpha and beta diversity
ggiNEXTbeta3D(output_FDc_abun, type = 'B')
```
The following commands return the size-based R/E sampling curves for gamma and alpha functional diversity:
```{r, fig.align='center', fig.height=5, fig.width=6}
## Size-based R/E curves for functional gamma and alpha diversity
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)
```
## DATA INFORMATION: FUNCTION DataInfobeta3D()
The function `DataInfobeta3D()` provides basic data information for (1) the reference sample in each individual assemblage, (2) the gamma reference sample in the pooled assemblage, and (3) the alpha reference sample in the joint assemblage.
The function `DataInfobeta3D()` with default arguments is shown below:
```{r eval=FALSE}
DataInfobeta3D(data, diversity = "TD", datatype = "abundance",
PDtree = NULL, PDreftime = NULL, PDtype = "meanPD",
FDdistM = NULL, FDtype = "AUC", FDtau = NULL, by_pair = FALSE)
```
Arguments shared by `DataInfobeta3D()` and `iNEXTbeta3D()` have the same definitions as described above. Running the `DataInfobeta3D()` function returns basic data information including sample size, observed species richness, two sample coverage estimates (`SC(n)` and `SC(2n)`) as well as other relevant information in each of the three dimensions of diversity. We use `Brazil_rainforests` data to demonstrate the function for each dimension.
```{r eval=FALSE}
## Data information for taxonomic diversity
data(Brazil_rainforests)
DataInfobeta3D(data = Brazil_rainforests, diversity = 'TD', datatype = 'abundance')
```
```{r echo=FALSE}
## Data information for taxonomic diversity
data(Brazil_rainforests)
tmp = DataInfobeta3D(data = Brazil_rainforests, diversity = 'TD', datatype = 'abundance')
tmp[,c("SC(n)","SC(2n)")] = round(tmp[,c("SC(n)","SC(2n)")], 3)
tmp
```
Output description:
- `Dataset` = the input datasets.
- `Pair` = combinations of assemblage pairs; this column is included only when the analysis is performed for every pair of assemblages.
- `Assemblage` = Individual assemblages, `'Pooled assemblage'` (for gamma) or `'Joint assemblage'` (for alpha).
- `n` = number of observed individuals in the reference sample (sample size).
- `S.obs` = number of observed species in the reference sample.
- `SC(n)` = sample coverage estimate of the reference sample.
- `SC(2n)` = sample coverage estimate of twice the reference sample size.
- `f1`-`f5` = the first five species abundance frequency counts in the reference sample.
```{r eval=FALSE}
## Data information for mean phylogenetic diversity
data(Brazil_rainforests)
data(Brazil_tree)
DataInfobeta3D(data = Brazil_rainforests, diversity = 'PD', datatype = 'abundance',
PDtype = 'meanPD', PDtree = Brazil_tree, PDreftime = NULL)
```
```{r echo=FALSE}
## Data information for mean phylogenetic diversity
data(Brazil_rainforests)
data(Brazil_tree)
tmp = DataInfobeta3D(data = Brazil_rainforests, diversity = 'PD', datatype = 'abundance',
PDtype = 'meanPD', PDtree = Brazil_tree, PDreftime = NULL)
tmp[,c("SC(n)","SC(2n)")] = round(tmp[,c("SC(n)","SC(2n)")], 3)
tmp
```
For both `PDtype = "PD"` and `PDtype = "meanPD"`, the output information is described as follows:
- `Dataset`, `Pair`, `Assemblage`, `n`, `S.obs`, `SC(n)` and `SC(2n)`: definitions are the same as in the TD output.
- `PD.obs` = the observed total branch length in the phylogenetic tree spanned by all observed species.
- `f1*`,`f2*` = the number of singletons and doubletons in the node/branch abundance set.
- `g1`,`g2` = the total branch length of those singletons/doubletons in the node/branch abundance set.
- `Reftime` = the fixed time reference point for phylogenetic diversity. If `PDreftime = NULL`, the age of the root of the phylogenetic tree spanned by the pooled observed species is used.
```{r eval=FALSE}
## Data information for phylogenetic diversity when all time reference points are considered
data(Brazil_rainforests)
data(Brazil_tree)
DataInfobeta3D(data = Brazil_rainforests, diversity = 'PD',
datatype = 'abundance', PDtype = 'AUC',
PDtree = Brazil_tree)
```
```{r echo=FALSE}
## Data information for phylogenetic diversity when all time reference points are considered
data(Brazil_rainforests)
data(Brazil_tree)
tmp = DataInfobeta3D(data = Brazil_rainforests, diversity = 'PD',
datatype = 'abundance', PDtype = 'AUC',
PDtree = Brazil_tree)
tmp[,c("SC(n)","SC(2n)")] = round(tmp[,c("SC(n)","SC(2n)")], 3)
tmp
```
For `PDtype = "AUC"` the output information is described as follows:
- `Dataset`, `Pair`, `Assemblage`, `n`, `S.obs`, `SC(n)` and `SC(2n)`: definitions are the same as in the TD output.
- `Tree.depth.min` = the minimum time reference point used for calculating the integrated mean phylogenetic diversity; this value is zero.
- `Tree.depth.max` = the maximum time reference point used for calculating the integrated mean phylogenetic diversity; this value is the age of the root of the phylogenetic tree spanned by the pooled observed species.
```{r eval=FALSE}
## Data information for functional diversity (under a specified threshold level, FDtype = 'tau_value')
data(Brazil_rainforests)
data(Brazil_distM)
DataInfobeta3D(data = Brazil_rainforests, diversity = 'FD', datatype = 'abundance',
FDdistM = Brazil_distM, FDtype = 'tau_value', FDtau = NULL)
```
```{r echo=FALSE}
## Data information for functional diversity (under a specified threshold level, FDtype = 'tau_value')
data(Brazil_rainforests)
data(Brazil_distM)
tmp = DataInfobeta3D(data = Brazil_rainforests, diversity = 'FD', datatype = 'abundance',
FDdistM = Brazil_distM, FDtype = 'tau_value', FDtau = NULL)
tmp[,c("SC(n)","SC(2n)","Tau")] = round(tmp[,c("SC(n)","SC(2n)","Tau")], 3)
tmp
```
For `FDtype = "tau_value"` the output information is described as follows:
- `Dataset`, `Pair`, `Assemblage`, `n`, `S.obs`, `SC(n)` and `SC(2n)`: definitions are the same as in the TD output.
- `a1*`,`a2*` = the number of singletons (`a1*`) and of doubletons (`a2*`) among the functionally indistinct set at the specified threshold level `'Tau'`.
- `h1`,`h2` = the total contribution of singletons (`h1`) and of doubletons (`h2`) at the specified threshold level `'Tau'`.
- `Tau` = the specified threshold level of distinctiveness. Default is dmean (the mean distance between any two individuals randomly selected from the pooled data over all datasets).
```{r eval=FALSE}
## Data information for functional diversity (FDtype = 'AUC')
data(Brazil_rainforests)
data(Brazil_distM)
DataInfobeta3D(data = Brazil_rainforests, diversity = 'FD', datatype = 'abundance',
FDdistM = Brazil_distM, FDtype = 'AUC')
```
```{r echo=FALSE}
## Data information for functional diversity (FDtype = 'AUC')
data(Brazil_rainforests)
data(Brazil_distM)
tmp = DataInfobeta3D(data = Brazil_rainforests, diversity = 'FD', datatype = 'abundance',
FDdistM = Brazil_distM, FDtype = 'AUC')
tmp[,c("SC(n)","SC(2n)","dmean","dmax")] = round(tmp[,c("SC(n)","SC(2n)","dmean","dmax")], 3)
tmp
```
For `FDtype = "AUC"` the output information is described as follows:
- `Dataset`, `Pair`, `Assemblage`, `n`, `S.obs`, `SC(n)` and `SC(2n)`: definitions are the same as in TD and thus are omitted.
- `dmin` = the minimum distance among all non-diagonal elements in the distance matrix.
- `dmean` = the mean distance between any two individuals randomly selected from each assemblage.
- `dmax` = the maximum distance among all elements in the distance matrix.
Below we use the demo dataset (`Second-growth forests`) to show the output of the function `DataInfobeta3D` for incidence data:
```{r eval=FALSE}
## Data information for taxonomic diversity with incidence data
data(Second_growth_forests)
DataInfobeta3D(data = Second_growth_forests, diversity = 'TD', datatype = 'incidence_raw',
by_pair = FALSE)
```
```{r echo=FALSE}
## Data information for taxonomic diversity with incidence data
data(Second_growth_forests)
tmp = DataInfobeta3D(data = Second_growth_forests, diversity = 'TD', datatype = 'incidence_raw',
by_pair = FALSE)
tmp[,c("SC(T)","SC(2T)")] = round(tmp[,c("SC(T)","SC(2T)")], 3)
tmp
```
Information description:
- `Dataset` = the input datasets.
- `Pair` = combinations of assemblage pairs; this column is included only when the analysis is performed for every pair of assemblages.
- `Assemblage` = Individual assemblages, `'Pooled assemblage'` (for gamma) or `'Joint assemblage'` (for alpha).
- `T` = number of sampling units in the reference sample (sample size for incidence data).
- `U` = total number of incidences in the reference sample.
- `S.obs` = number of observed species in the reference sample.
- `SC(T)` = sample coverage estimate of the reference sample.
- `SC(2T)` = sample coverage estimate of twice the reference sample size.
- `Q1`-`Q5` = the first five species incidence frequency counts in the reference sample.
```{r eval=FALSE}
## Data information for taxonomic diversity for every pair of assemblages (incidence data)
data(Second_growth_forests)
DataInfobeta3D(data = Second_growth_forests, diversity = 'TD', datatype = 'incidence_raw',
by_pair = TRUE)
```
```{r echo=FALSE}
## Data information for taxonomic diversity for every pair of assemblages (incidence data)
data(Second_growth_forests)
tmp = DataInfobeta3D(data = Second_growth_forests, diversity = 'TD', datatype = 'incidence_raw',
by_pair = TRUE)
tmp[,c("SC(T)","SC(2T)")] = round(tmp[,c("SC(T)","SC(2T)")], 3)
tmp
```
Output description: definitions are the same as before and thus are omitted.
## License and feedback
The `iNEXT.beta3D` package is licensed under the GPLv3. To help refine `iNEXT.beta3D`, users' comments or feedback would be welcome (please send them to Anne Chao or report an issue on the `iNEXT.beta3D` GitHub [iNEXT.beta3D_github](https://github.com/AnneChao/iNEXT.beta3D)).
## 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., Magnago, L. F. S., 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.