In Chunger-Lo/iNEXT.link: Network diversity iNterpolation/Extrapolation Estimation
knitr::opts_chunk$set(
collapse = TRUE,
warning = FALSE, message = FALSE,
comment = ""
)
#devtools::load_all(".")
library(ggplot2)
#library(kableExtra)
library(knitr)
library(tibble)
library(iNEXT)
library(sets)
Shelfanger <- read.table("F://Chao//Network diversity//shinyapp//heir.entropy//data//Shelfanger.txt")
Hickling <- read.table("F://Chao//Network diversity//shinyapp//heir.entropy//data/Hickling.txt")
Norfolk <- list(Shelfanger = Shelfanger,Hickling = Hickling)
# usethis::use_data(Norfolk, overwrite = T)
Caguana <- read.table("F://Chao//Network diversity//shinyapp//heir.entropy//data/Caguana.txt")
Cialitos <- read.table("F://Chao//Network diversity//shinyapp//heir.entropy//data/Cialitos.txt")
Cordillera <- read.table("F://Chao//Network diversity//shinyapp//heir.entropy//data/Cordillera.txt")
Fronton <- read.table("F://Chao//Network diversity//shinyapp//heir.entropy//data/Fronton.txt")
data <- list(Cordillera = Cordillera,Caguana = Caguana,Fronton = Fronton,Cialitos = Cialitos)
library(phytools)
rowtree <- read.newick("F://Chao//Network diversity//shinyapp//heir.entropy//tree/rowtree.txt")
coltree <- read.newick("F://Chao//Network diversity//shinyapp//heir.entropy//tree/coltree.txt")
puerto.rico = list()
puerto.rico[["data"]] = data
puerto.rico[["col.tree"]] = coltree
puerto.rico[["row.tree"]] = rowtree
# usethis::use_data(puerto.rico, overwrite = T)
iNEXT.link is a R package providing the rarefaction/extrapolation and asymptotic estimation to achieve fair comparison of network diversity among multiple interaction network. In this document, we provide a quick introduction demonstrating how to run iNEXT.link. The Detailed information about iNEXT.link functions is described in the iNEXT.link Manual, also available in CRAN. An online version of iNEXT.link.Online (https://r717r717.shinyapps.io/iNEXT.link.Online/) is developed for users without R background. The theoretical derivation of network diversity measurements will be proposed soon. iNEXT.link is an extension for iNext3D, which computes diversity estimates and its confidence intervals for the two types of rarefaction and extrapolation (R/E) based on two different sampling data sets, individual-based abundance data and quadrat-based incidence data.
Based on the , for single network, we have a 4-steps procedure to analyze comprehensively, which are
- Assessment of sample completeness
- The asymptotic approach
- Non-asymptotic coverage-based rarefaction and extrapolation analysis
4: Assement of network specialization
Moreover, to assess the dissimilarity between interaction networks, we have an extra step
(*) beta diversity and dissimilarity indices.
For these analyzing steps, we have corresponding computation functions, and we will go through these functions by steps.
Taxonomic
Step1: Assessment of sample completeness
NetSC: Compute the sample completeness over order.q, and returns a dataframe.
ggNetSC: Visualize the result obtained from NetSC with a ggplot2 object.
Step2: The asymptotic approach
ObsND: Compute the sample empirical network diveristy, and returns a dataframe.
ggObsND: Visualize the result obtained from ObsND with a ggplot2 object.
Step3: Non-asymptotic coverage-based rarefaction and extrapolation analysis
iNEXT_ND: Compute the sized-based/ coverage-based R/E network diversity, and returns a iNEXT object.
ggiNEXT_ND: Visualize the result obtained from iNEXT_ND with a ggplot2 object.
Step4: Assement of network specialization
NetSpec: Compute the interaction specialization over specified Evenness class (E1,E2,E3,E4,E5), and returns a list by class.
ggNetSpec: Visualize the result obtained from iNEXT_ND with a ggplot2 object.
Extra Step: Beta diversity and dissimilarity
iNEXT_beta_link: Compute the coverage-based/ size-based alpha, beta, gamma diversity and dissimilarity indices, and returns a list by index.
ggiNEXT_beta_link: Visualize the result obtained from iNEXT_ND with a ggplot2 object.
Phylogenetic
Step1: Assessment of sample completeness
NetSC: Compute the sample completeness over order.q, and returns a dataframe.
ggNetSC: Visualize the result obtained from NetSC with a ggplot2 object.
Step2: The asymptotic approach
ObsPND: Compute the sample empirical network diveristy, and returns a dataframe.
ggObsPND: Visualize the result obtained from ObsND with a ggplot2 object.
Step3: Non-asymptotic coverage-based rarefaction and extrapolation analysis
iNEXT_PND: Compute the sized-based/ coverage-based R/E network diversity, and returns a iNEXT object.
ggiNEXT_PND: Visualize the result obtained from iNEXT_ND with a ggplot2 object.
Step4: Assement of network specialization
NetSpec: Compute the interaction specialization over specified Evenness class (E1,E2,E3,E4,E5), and returns a list by class.
ggNetSpec: Visualize the result obtained from iNEXT_ND with a ggplot2 object.
Extra Step: Beta diversity and dissimilarity
iNEXT_beta_link: Compute the coverage-based/ size-based alpha, beta, gamma diversity and dissimilarity indices, and returns a list by index.
ggiNEXT_beta_link: Visualize the result obtained from iNEXT_ND with a ggplot2 object.
The framework can be summarized as follows.
knitr::include_graphics("pic/framework.png")
SOFTWARE NEEDED TO RUN iNEXT.link IN R:
- Required: R
- Suggested: RStudio IDE
HOW TO RUN iNEXT.link:
The iNEXT.link package is available on CRAN and can be downloaded with a standard R installation procedure using the following commands. Before installation, the additional visualization and computation extension packages (chaoUtility,ape, dplyr, ggplot2, phyclust, Rcpp) must be loaded. Please note that currently, package chaoUtility can only be available via github instead of CRAN and thus the installation procedure slightly differs from the one of standard R installation.
## install chaoUtility package from github
install.packages("devtools")
library(devtools)
install_github("chaolab2019/chaoUtility")
## install iNEXT.links package from CRAN
install.packages("iNEXT.link")
## Or instead, install the latest version from github
install_github("Chunger-Lo/iNEXT.link")
## import packages
library(chaoUtility)
library(phytools)
library(iNEXT)
library(iNEXT.link)
# library(iNEXT)
# source("..//R//iNEXTlink.R")
# source("..//R//subfunction.R")
# source("..//R//myfunc.R")
# library(chaoUtility)
library(tidyr)
library(magrittr)
library(miNEXT.beta)
library(chaoUtility)
library(phytools)
library(iNEXT3D)
library(iNEXT.link)
library(miNEXT.beta)
library(tidyverse)
# include abundance data
# data(data.abu)
library(phytools)
Shelfanger <- read.table("F://Chao//Network diversity//shinyapp//heir.entropy//data//Shelfanger.txt")
Hickling <- read.table("F://Chao//Network diversity//shinyapp//heir.entropy//data/Hickling.txt")
Norfolk <- list(Shelfanger = Shelfanger,Hickling = Hickling)
Caguana <- read.table("F://Chao//Network diversity//shinyapp//heir.entropy//data/Caguana.txt")
Cialitos <- read.table("F://Chao//Network diversity//shinyapp//heir.entropy//data/Cialitos.txt")
Cordillera <- read.table("F://Chao//Network diversity//shinyapp//heir.entropy//data/Cordillera.txt")
Fronton <- read.table("F://Chao//Network diversity//shinyapp//heir.entropy//data/Fronton.txt")
data <- list(Cordillera = Cordillera,Caguana = Caguana,Fronton = Fronton,Cialitos = Cialitos)
puerto.rico <- list(Cordillera = Cordillera,Caguana = Caguana,Fronton = Fronton,Cialitos = Cialitos)
library(phytools)
rowtree <- read.newick("F://Chao//Network diversity//shinyapp//heir.entropy//tree/rowtree.txt")
coltree <- read.newick("F://Chao//Network diversity//shinyapp//heir.entropy//tree/coltree.txt")
puerto.rico = list()
puerto.rico[["data"]] = data
puerto.rico[["col.tree"]] = coltree
puerto.rico[["row.tree"]] = rowtree
MAIN FUNCTIONS:
We describe the four main functions with default arguments below :
a. Taxonomic
- iNEXT_ND():
iNEXT_ND(Norfolk, datatype = "abundance", q = c(0,1,2),
endpoint = NULL, knots = 40, size = NULL, nboot = 30, conf = 0.95)
The arguments of this function are described below.
Argument
Description
data a matrix/data.frame of species abundances or incidence matrix. See the DATA FORMAT/INFORMATION section above for detailed required format.
datatype data type of input data: individual-based abundance data (`datatype = "abundance"`), or species-by-site raw incidence matrix (`datatype = "incidence_raw"`). Default is `"abundance"`
q a nonnegative value or sequence specifying the diversity order. There are three measures: Faith's PD (`q = 0`), a simple transformation of phylogenetic entropy (`q = 1`) and a simple transformation of Rao's quadratic entropy (`q = 2`). Default is `c(0,1,2)`.
type desired diversity type: `type = "PD"` for Chao et al. (2010) phylogenetic diversity and `type = "meanPD"` for mean phylogenetic diversity (i.e., phylogenetic Hill number). Default is `"PD"`.
endpoints a positive integer specifying the endpoint for rarefaction and extrapolation range. If `NULL`, then `endpoint =` double of the reference sample sizes. It is ignored if `size` is given.
knots a positive integer specifying the number of equally-spaced knots between 1 and the `endpoint`. Default is 40.
size a sequence of positive integers specifying the sample sizes for which PD or meanPD estimates will be calculated. If `NULL`, then estimates will be calculated for those sample sizes determined by the specified/default `endpoint` and `knots`.
nboot a positive integer specifying the number of bootstrap replications in assessing sampling uncertainty and constructing confidence intervals. Enter 0 to skip the bootstrap procedures. Default is 50.
conf a positive number < 1 specifying the level of confidence interval. Default is 0.95.
The sequence of sample sizes for which PD/meanPD R/E curve will be estimated is determined by endpoint, knots and size.
If size is specified by users, then PD/meanPD will be estimated for these sizes plus the reference sample size(total species abundances for abundance data; total sampling units for incidence data).
If knots=K, then the sequece would be K/2 evenly‐spaced knots (sample sizes) before reference sample size and K/2 from reference sample size to endpoint, where the endpoint is default to double reference sample size. By default, knots=40.
If endpoint specified by users is smaller than the reference sample size, iNEXTPD only computes rarefaction estimates for approximately knots evenly spaced knots before the endpoint.
- AsyND():
asy = AsyND(Norfolk, q = c(0,1,2), datatype = "abundance", nboot = 30)
The arguments of this function are described below.
Argument
Description
data a matrix/data.frame of species abundances (for abundance data) or species-by-site raw incidence matrix (for incidence data). See the DATA FORMAT/INFORMATION section above for detailed required format.
datatype data type of input data: individual-based abundance data (`datatype = "abundance"`), or species-by-site raw incidence matrix (`datatype = "incidence_raw"`). Default is `"abundance"`
tree a phylo object describing the phylogenetic tree in Newick format for all observed species in the pooled assemblage.
q a nonnegative value or sequence specifying the diversity order. Default is `seq(0, 2, by = 0.25)`.
type desired diversity type: `type = "PD"` for Chao et al. (2010) phylogenetic diversity and `type = "meanPD"` for mean phylogenetic diversity (i.e., phylogenetic Hill number). Default is `"PD"`.
nboot a positive integer specifying the number of bootstrap replications in assessing sampling uncertainty and constructing confidence intervals. Enter 0 to skip the bootstrap procedures. Default is 50.
conf a positive number < 1 specifying the level of confidence interval. Default is 0.95.
- ObsND():
obs = ObsND(Norfolk, q = c(0,1,2), datatype = "abundance", nboot = 30)
The arguments of this function are described below.
Argument
Description
data a matrix/data.frame of species abundances (for abundance data) or species-by-site raw incidence matrix (for incidence data). See the DATA FORMAT/INFORMATION section above for detailed required format.
datatype data type of input data: individual-based abundance data (`datatype = "abundance"`), or species-by-site raw incidence matrix (`datatype = "incidence_raw"`). Default is `"abundance"`
q a nonnegative value or sequence specifying the diversity order. Default is `seq(0, 2, by = 0.25)`.
type desired diversity type: `type = "PD"` for Chao et al. (2010) phylogenetic diversity and `type = "meanPD"` for mean phylogenetic diversity (i.e., phylogenetic Hill number). Default is `"PD"`.
nboot a positive integer specifying the number of bootstrap replications in assessing sampling uncertainty and constructing confidence intervals. Enter 0 to skip the bootstrap procedures. Default is 50.
conf a positive number < 1 specifying the level of confidence interval. Default is 0.95.
- estimateND():
estimateND(Norfolk, datatype="abundance", base="coverage",level=0.7, nboot = 30,conf=0.95)
The arguments of this function are described below.
Argument
Description
data a matrix/data.frame of species abundances (for abundance data) or species-by-site raw incidence matrix (for incidence data). See the DATA FORMAT/INFORMATION section above for detailed required format.
nT needed only when `datatype = "incidence_raw"`, a sequence of named nonnegative integers specifying the number of sampling units in each assemblage. If `names(nT) = NULL`, automatically assigns "site1", "site2",..., as assemblage names. Ignored if `datatype = "abundance"`.
datatype data type of input data: individual-based abundance data (`datatype = "abundance"`), or species-by-site raw incidence matrix (`datatype = "incidence_raw"`). Default is `"abundance"`.
tree a phylo object describing the phylogenetic tree in Newick format for all observed species in the pooled assemblage.
q a nonnegative value or sequence specifying the diversity order. Default is `c(0,1,2)`.
reftime a positive value or sequence specifying the reference time for computing diversity. If `NULL`, `reftime` is set to be the tree depth of the phylogenetic tree spanned by the observed species in the pooled assemblage. Default is `NULL`.
type desired diversity type: `type = "PD"` for Chao et al. (2010) phylogenetic diversity and `type = "meanPD"` for mean phylogenetic diversity (i.e., phylogenetic Hill number). Default is `"PD"`.
level a positive value or sequence < 1 specifying a particular value of sample coverage. If `NULL`,then `level` will be chosen as the minimum coverage of all sites after extrapolating each site to its double sample sizes. Default is `NULL`.
nboot a positive integer specifying the number of bootstrap replications in assessing sampling uncertainty and constructing confidence intervals. Enter 0 to skip the bootstrap procedures. Default is 50.
conf a positive number < 1 specifying the level of confidence interval. Default is 0.95.
- NetSpec():
NetSpec(Norfolk, q = seq(0,2,1), datatype = "abundance", nboot =30)
The arguments of this function are described below.
Argument
Description
data a matrix/data.frame of species abundances (for abundance data) or species-by-site raw incidence matrix (for incidence data). See the DATA FORMAT/INFORMATION section above for detailed required format.
nT needed only when `datatype = "incidence_raw"`, a sequence of named nonnegative integers specifying the number of sampling units in each assemblage. If `names(nT) = NULL`, automatically assigns "site1", "site2",..., as assemblage names. Ignored if `datatype = "abundance"`.
datatype data type of input data: individual-based abundance data (`datatype = "abundance"`), or species-by-site raw incidence matrix (`datatype = "incidence_raw"`). Default is `"abundance"`.
tree a phylo object describing the phylogenetic tree in Newick format for all observed species in the pooled assemblage.
q a nonnegative value or sequence specifying the diversity order. Default is `c(0,1,2)`.
type desired diversity type: `type = "PD"` for Chao et al. (2010) phylogenetic diversity and `type = "meanPD"` for mean phylogenetic diversity (i.e., phylogenetic Hill number). Default is `"PD"`.
level a positive value or sequence < 1 specifying a particular value of sample coverage. If `NULL`,then `level` will be chosen as the minimum coverage of all sites after extrapolating each site to its double sample sizes. Default is `NULL`.
nboot a positive integer specifying the number of bootstrap replications in assessing sampling uncertainty and constructing confidence intervals. Enter 0 to skip the bootstrap procedures. Default is 50.
b. Phylogenetic
- iNEXT_PND():
iNEXT_PND(x = puerto.rico$data, row.tree = puerto.rico$row.tree, col.tree = puerto.rico$col.tree, q = c(0,1,2),
datatype = "abundance", endpoint = NULL, knots = 40,
size = NULL, conf = 0.95, nboot = 10)
The arguments of this function are described below.
Argument
Description
data a matrix/data.frame of species abundances or incidence matrix. See the DATA FORMAT/INFORMATION section above for detailed required format.
datatype data type of input data: individual-based abundance data (`datatype = "abundance"`), or species-by-site raw incidence matrix (`datatype = "incidence_raw"`). Default is `"abundance"`
q a nonnegative value or sequence specifying the diversity order. There are three measures: Faith's PD (`q = 0`), a simple transformation of phylogenetic entropy (`q = 1`) and a simple transformation of Rao's quadratic entropy (`q = 2`). Default is `c(0,1,2)`.
type desired diversity type: `type = "PD"` for Chao et al. (2010) phylogenetic diversity and `type = "meanPD"` for mean phylogenetic diversity (i.e., phylogenetic Hill number). Default is `"PD"`.
endpoints a positive integer specifying the endpoint for rarefaction and extrapolation range. If `NULL`, then `endpoint =` double of the reference sample sizes. It is ignored if `size` is given.
knots a positive integer specifying the number of equally-spaced knots between 1 and the `endpoint`. Default is 40.
size a sequence of positive integers specifying the sample sizes for which PD or meanPD estimates will be calculated. If `NULL`, then estimates will be calculated for those sample sizes determined by the specified/default `endpoint` and `knots`.
nboot a positive integer specifying the number of bootstrap replications in assessing sampling uncertainty and constructing confidence intervals. Enter 0 to skip the bootstrap procedures. Default is 50.
conf a positive number < 1 specifying the level of confidence interval. Default is 0.95.
The sequence of sample sizes for which PD/meanPD R/E curve will be estimated is determined by endpoint, knots and size.
If size is specified by users, then PD/meanPD will be estimated for these sizes plus the reference sample size(total species abundances for abundance data; total sampling units for incidence data).
If knots=K, then the sequece would be K/2 evenly‐spaced knots (sample sizes) before reference sample size and K/2 from reference sample size to endpoint, where the endpoint is default to double reference sample size. By default, knots=40.
If endpoint specified by users is smaller than the reference sample size, iNEXTPD only computes rarefaction estimates for approximately knots evenly spaced knots before the endpoint.
- AsyND():
AsyPND(puerto.rico$data, q = c(0,1,2), datatype = "abundance", nboot = 30)
The arguments of this function are described below.
Argument
Description
data a matrix/data.frame of species abundances (for abundance data) or species-by-site raw incidence matrix (for incidence data). See the DATA FORMAT/INFORMATION section above for detailed required format.
nT needed only when `datatype = "incidence_raw"`, a sequence of named nonnegative integers specifying the number of sampling units in each assemblage. If `names(nT) = NULL`, automatically assigns "site1", "site2",..., as assemblage names. Ignored if `datatype = "abundance"`.
datatype data type of input data: individual-based abundance data (`datatype = "abundance"`), or species-by-site raw incidence matrix (`datatype = "incidence_raw"`). Default is `"abundance"`
tree a phylo object describing the phylogenetic tree in Newick format for all observed species in the pooled assemblage.
q a nonnegative value or sequence specifying the diversity order. Default is `seq(0, 2, by = 0.25)`.
reftime a positive value or sequence specifying the reference time for computing diversity. If `NULL`, `reftime` is set to be the tree depth of the phylogenetic tree spanned by the observed species in the pooled assemblage. Default is `NULL`.
type desired diversity type: `type = "PD"` for Chao et al. (2010) phylogenetic diversity and `type = "meanPD"` for mean phylogenetic diversity (i.e., phylogenetic Hill number). Default is `"PD"`.
nboot a positive integer specifying the number of bootstrap replications in assessing sampling uncertainty and constructing confidence intervals. Enter 0 to skip the bootstrap procedures. Default is 50.
conf a positive number < 1 specifying the level of confidence interval. Default is 0.95.
- ObsPND():
ObsPND(data.abu, datatype = "abundance", tree, q = c(0,1,2), datatype = "abundance", nboot = 30)
The arguments of this function are described below.
Argument
Description
data a matrix/data.frame of species abundances (for abundance data) or species-by-site raw incidence matrix (for incidence data). See the DATA FORMAT/INFORMATION section above for detailed required format.
nT needed only when `datatype = "incidence_raw"`, a sequence of named nonnegative integers specifying the number of sampling units in each assemblage. If `names(nT) = NULL`, automatically assigns "site1", "site2",..., as assemblage names. Ignored if `datatype = "abundance"`.
datatype data type of input data: individual-based abundance data (`datatype = "abundance"`), or species-by-site raw incidence matrix (`datatype = "incidence_raw"`). Default is `"abundance"`
tree a phylo object describing the phylogenetic tree in Newick format for all observed species in the pooled assemblage.
q a nonnegative value or sequence specifying the diversity order. Default is `seq(0, 2, by = 0.25)`.
reftime a positive value or sequence specifying the reference time for computing diversity. If `NULL`, `reftime` is set to be the tree depth of the phylogenetic tree spanned by the observed species in the pooled assemblage. Default is `NULL`.
type desired diversity type: `type = "PD"` for Chao et al. (2010) phylogenetic diversity and `type = "meanPD"` for mean phylogenetic diversity (i.e., phylogenetic Hill number). Default is `"PD"`.
nboot a positive integer specifying the number of bootstrap replications in assessing sampling uncertainty and constructing confidence intervals. Enter 0 to skip the bootstrap procedures. Default is 50.
conf a positive number < 1 specifying the level of confidence interval. Default is 0.95.
- estimatePND():
estimatePND <- function(data, datatype = "abundance", tree, q = c(0,1,2), reftime=NULL,
level = NULL, nboot = 50, conf = 0.95)
The arguments of this function are described below.
Argument
Description
data a matrix/data.frame of species abundances (for abundance data) or species-by-site raw incidence matrix (for incidence data). See the DATA FORMAT/INFORMATION section above for detailed required format.
nT needed only when `datatype = "incidence_raw"`, a sequence of named nonnegative integers specifying the number of sampling units in each assemblage. If `names(nT) = NULL`, automatically assigns "site1", "site2",..., as assemblage names. Ignored if `datatype = "abundance"`.
datatype data type of input data: individual-based abundance data (`datatype = "abundance"`), or species-by-site raw incidence matrix (`datatype = "incidence_raw"`). Default is `"abundance"`.
tree a phylo object describing the phylogenetic tree in Newick format for all observed species in the pooled assemblage.
q a nonnegative value or sequence specifying the diversity order. Default is `c(0,1,2)`.
reftime a positive value or sequence specifying the reference time for computing diversity. If `NULL`, `reftime` is set to be the tree depth of the phylogenetic tree spanned by the observed species in the pooled assemblage. Default is `NULL`.
type desired diversity type: `type = "PD"` for Chao et al. (2010) phylogenetic diversity and `type = "meanPD"` for mean phylogenetic diversity (i.e., phylogenetic Hill number). Default is `"PD"`.
level a positive value or sequence < 1 specifying a particular value of sample coverage. If `NULL`,then `level` will be chosen as the minimum coverage of all sites after extrapolating each site to its double sample sizes. Default is `NULL`.
nboot a positive integer specifying the number of bootstrap replications in assessing sampling uncertainty and constructing confidence intervals. Enter 0 to skip the bootstrap procedures. Default is 50.
conf a positive number < 1 specifying the level of confidence interval. Default is 0.95.
- NetSpec():
NetSpec(Norfolk, q = seq(0,2,1), datatype = "abundance", nboot =30)
The arguments of this function are described below.
Argument
Description
data a matrix/data.frame of species abundances (for abundance data) or species-by-site raw incidence matrix (for incidence data). See the DATA FORMAT/INFORMATION section above for detailed required format.
nT needed only when `datatype = "incidence_raw"`, a sequence of named nonnegative integers specifying the number of sampling units in each assemblage. If `names(nT) = NULL`, automatically assigns "site1", "site2",..., as assemblage names. Ignored if `datatype = "abundance"`.
datatype data type of input data: individual-based abundance data (`datatype = "abundance"`), or species-by-site raw incidence matrix (`datatype = "incidence_raw"`). Default is `"abundance"`.
tree a phylo object describing the phylogenetic tree in Newick format for all observed species in the pooled assemblage.
q a nonnegative value or sequence specifying the diversity order. Default is `c(0,1,2)`.
type desired diversity type: `type = "PD"` for Chao et al. (2010) phylogenetic diversity and `type = "meanPD"` for mean phylogenetic diversity (i.e., phylogenetic Hill number). Default is `"PD"`.
level a positive value or sequence < 1 specifying a particular value of sample coverage. If `NULL`,then `level` will be chosen as the minimum coverage of all sites after extrapolating each site to its double sample sizes. Default is `NULL`.
nboot a positive integer specifying the number of bootstrap replications in assessing sampling uncertainty and constructing confidence intervals. Enter 0 to skip the bootstrap procedures. Default is 50.
iNEXT.link VIA EXAMPLES: Network diversity analysis (taxonomic)
library(ade4)
library(tidyverse)
library(ape)
library(dplyr)
Main function:
1.NetSC():
sc1 <- NetSC(x = Norfolk, datatype = "abundance", nboot = 10)
ggNetSC(sc1)
2.iNEXT_ND():
sample1 <- iNEXT_ND(x = Norfolk, datatype = "abundance", nboot = 30)
iNEXT_ND() returns a list containing three objects:
$DataInfo: The same table from function NDInfo(), which summarizes some network statistics for each assemblage, including reference sample size (n), number of observed species (S.obs), Connectance, the first two rare species frequency counts.
kable(sample1$DataInfo)
$iNextEst: Size-based / coverage-based diversity estimates along with confidence intervals and related statistics.
size-based
kable(head(sample1$iNextEst$size_based,5))
coverage-based
kable(head(sample1$iNextEst$coverage_based,5))
$AsyEst: Asymptotic/ Empirical diversity estimates along with confidence intervals and related statistics.
kable(head(sample1$AsyEst,9))
# only show part of the table, call View(dunes_iNEXT$size_based) to see full table.
# sample_iNEXT$DataInfo
# sample_iNEXT$iNextEst
# sample_iNEXT$AsyEst
3. ggiNEXT_ND
To visualize the curves, use ggiNEXT_ND to obtain plots based on ggplot2 package. This function provides three types of curves, which can be specified in the argument plot.type:
- Sample-size-based rarefaction and extrapolation curve (
plot.type = 1): sampling curve depicting phylogenetic diversity estimates as a function of sample size.
- Sample completeness curve (
plot.type = 2): the curve of sample coverage as a function of sample size.
- Coverage-based R/E curve (
plot.type = 3): sampling curve depicting Network diversity estimates as a function of sample coverage.
ggiNEXT_ND(sample1, type = 1,facet = "Order.q" )
ggiNEXT_ND(sample1, type = 3, facet = "Assemblage")
4. Empirical / Asymptotic diversity
asy1 = AsyND(Norfolk,q = c(0,1,2),nboot = 10)
head(asy1,5)
obs1 = ObsND(Norfolk,q = c(0,1,2),nboot = 10)
head(obs1,5)
ggAsyND(rbind(obs1, asy1))
5. estimateND()
kable(estimateND(Norfolk, datatype="abundance", base="coverage",level=0.7, conf=0.95))
The estimateND() function returns a table of the computed diversity for specified/default diversity orders q and reference times for the user-specified values of sample coverage. The corresponding sample sizes and sample coverage values are also provided.
6. Specialization
spec1 = NetSpec(Norfolk, q = seq(0,2,1), datatype = "abundance", nboot =10)
ggSpec(spec1)
7. Dissimilarity
dissimilarity1 = iNEXT_beta_link(x = Norfolk, coverage_expected = seq(0.5,1,0.05),
data_type='abundance',
q = c(0, 1, 2),level='taxonomic',
nboot = 0, conf = 0.95, max_alpha_coverage=F, by='coverage')
ggiNEXT_beta_link(dissimilarity1, type = 'B')
ggiNEXT_beta_link(dissimilarity1, type = 'D')
kable(head(dissimilarity1$Region_1$gamma, 10))
kable(head(dissimilarity1$Region_1$alpha, 10))
kable(head(dissimilarity1$Region_1$beta, 10))
EXAMPLES2: Network diversity analysis (phylogenetic)
Main function:
1.NetSC():
sc2 <- NetSC(x = Norfolk, datatype = "abundance", nboot = 10)
2.iNEXT_PND():
sample2 <- iNEXT_PND(x = puerto.rico$data, datatype = "abundance",
row.tree = rowtree, col.tree = coltree, nboot = 10)
iNEXT_PND() returns a list containing three objects:
$DataInfo: The same table from function PNDInfo(), which summarizes some network statistics for each assemblage, including reference sample size (n), number of observed species (S.obs), Connectance, the first two rare species frequency counts.
kable(sample2$DataInfo)
$iNextEst: Size-based / coverage-based diversity estimates along with confidence intervals and related statistics.
size-based
kable(head(sample2$iNextEst, 5)%>%rbind(tail(sample2$iNextEst, 5)))
$AsyEst: Asymptotic/ Empirical diversity estimates along with confidence intervals and related statistics.
kable(head(sample2$AsyEst,9))
3. ggiNEXT_PND
To visualize the curves, use ggiNEXT_PND to obtain plots based on ggplot2 package. This function provides three types of curves, which can be specified in the argument plot.type:
- Sample-size-based rarefaction and extrapolation curve (
plot.type = 1): sampling curve depicting phylogenetic diversity estimates as a function of sample size.
- Sample completeness curve (
plot.type = 2): the curve of sample coverage as a function of sample size.
- Coverage-based R/E curve (
plot.type = 3): sampling curve depicting Network diversity estimates as a function of sample coverage.
ggiNEXT_PND(sample2, type = 1)
ggiNEXT_PND(sample2, type = 3)
4. estimatePND()
kable(estimatePND(puerto.rico$data, col.tree = coltree, row.tree = rowtree, nboot = 10,datatype="abundance",level=0.7, conf=0.95))
5. Specialization
spec2 = phySpec(puerto.rico$data, q= seq(0,2,1), datatype = "abundance", nboot = 30, E = 1:5, method = "Estimated", C = 0.9)
ggSpec(spec2)
6. Dissimilarity
taxonomic
dissimilarity2 = iNEXT_beta_link(puerto.rico$data, coverage_expected = seq(0.5,1,0.025), data_type='abundance',
q = c(0, 1, 2),level='taxonomic',
row.tree = rowtree,col.tree = coltree,
nboot = 0, conf = 0.95, max_alpha_coverage=F,
by='coverage')
ggiNEXT_beta_link(dissimilarity2, type = 'B')
ggiNEXT_beta_link(dissimilarity2, type = 'D')
kable(head(dissimilarity2$Region_1$gamma, 10))
kable(head(dissimilarity2$Region_1$alpha, 10))
kable(head(dissimilarity2$Region_1$beta, 10))
phylogenetic
dissimilarity3 = iNEXT_beta_link(x = puerto.rico$data, coverage_expected = seq(0.5,0.99,0.025), data_type='abundance',
q = c(0, 1, 2),level='phylogenetic',
row.tree = rowtree, col.tree = coltree,
nboot = 0, conf = 0.95, max_alpha_coverage=F,
by='coverage')
ggiNEXT_beta_link(dissimilarity3, type = 'B')
ggiNEXT_beta_link(dissimilarity3, type = 'D')
kable(head(dissimilarity3$Region_1$gamma, 10))
kable(head(dissimilarity3$Region_1$alpha, 10))
kable(head(dissimilarity3$Region_1$beta, 10))
License
The iNEXT.link package is licensed under the GPLv3. To help refine iNEXT.link, your comments or feedbacks would be welcome (please send them to Anne Chao).
How to cite
If you publish your work based on results from iNEXT.link (R package), please make reference to Chao et al. given in the following list.
Reference
- Chao, A., Chiu C.-H. and Jost, L. (2010). Phylogenetic diversity measures based on Hill numbers. Philosophical Transactions of the Royal Society B., 365, 3599-3609.
- Chao, A., Chiu, C.-H., Hsieh, T. C., Davis, T., Nipperess, D., and Faith, D. (2015) Rarefaction and extrapolation of phylogenetic diversity. Methods in Ecology and Evolution, 6, 380-388.
- Hsieh, T. C. and Chao, A. (2017). Rarefaction and extrapolation: making fair comparison of abundance-sensitive phylogenetic diversity among multiple assemblages. Systematic Biology 66, 100-111.
Chunger-Lo/iNEXT.link documentation built on Dec. 17, 2021, 2:05 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
knitr::opts_chunk$set( collapse = TRUE, warning = FALSE, message = FALSE, comment = "" ) #devtools::load_all(".") library(ggplot2) #library(kableExtra) library(knitr) library(tibble) library(iNEXT) library(sets) Shelfanger <- read.table("F://Chao//Network diversity//shinyapp//heir.entropy//data//Shelfanger.txt") Hickling <- read.table("F://Chao//Network diversity//shinyapp//heir.entropy//data/Hickling.txt") Norfolk <- list(Shelfanger = Shelfanger,Hickling = Hickling) # usethis::use_data(Norfolk, overwrite = T) Caguana <- read.table("F://Chao//Network diversity//shinyapp//heir.entropy//data/Caguana.txt") Cialitos <- read.table("F://Chao//Network diversity//shinyapp//heir.entropy//data/Cialitos.txt") Cordillera <- read.table("F://Chao//Network diversity//shinyapp//heir.entropy//data/Cordillera.txt") Fronton <- read.table("F://Chao//Network diversity//shinyapp//heir.entropy//data/Fronton.txt") data <- list(Cordillera = Cordillera,Caguana = Caguana,Fronton = Fronton,Cialitos = Cialitos) library(phytools) rowtree <- read.newick("F://Chao//Network diversity//shinyapp//heir.entropy//tree/rowtree.txt") coltree <- read.newick("F://Chao//Network diversity//shinyapp//heir.entropy//tree/coltree.txt") puerto.rico = list() puerto.rico[["data"]] = data puerto.rico[["col.tree"]] = coltree puerto.rico[["row.tree"]] = rowtree # usethis::use_data(puerto.rico, overwrite = T)
iNEXT.link is a R package providing the rarefaction/extrapolation and asymptotic estimation to achieve fair comparison of network diversity among multiple interaction network. In this document, we provide a quick introduction demonstrating how to run iNEXT.link. The Detailed information about iNEXT.link functions is described in the iNEXT.link Manual, also available in CRAN. An online version of iNEXT.link.Online (https://r717r717.shinyapps.io/iNEXT.link.Online/) is developed for users without R background. The theoretical derivation of network diversity measurements will be proposed soon. iNEXT.link is an extension for iNext3D, which computes diversity estimates and its confidence intervals for the two types of rarefaction and extrapolation (R/E) based on two different sampling data sets, individual-based abundance data and quadrat-based incidence data.
Based on the
- Assessment of sample completeness
- The asymptotic approach
- Non-asymptotic coverage-based rarefaction and extrapolation analysis
4: Assement of network specialization
Moreover, to assess the dissimilarity between interaction networks, we have an extra step
(*) beta diversity and dissimilarity indices.
For these analyzing steps, we have corresponding computation functions, and we will go through these functions by steps.
Taxonomic
Step1: Assessment of sample completeness
NetSC: Compute the sample completeness over order.q, and returns a dataframe.
ggNetSC: Visualize the result obtained from NetSC with a ggplot2 object.
Step2: The asymptotic approach
ObsND: Compute the sample empirical network diveristy, and returns a dataframe.
ggObsND: Visualize the result obtained from ObsND with a ggplot2 object.
Step3: Non-asymptotic coverage-based rarefaction and extrapolation analysis
iNEXT_ND: Compute the sized-based/ coverage-based R/E network diversity, and returns a iNEXT object.
ggiNEXT_ND: Visualize the result obtained from iNEXT_ND with a ggplot2 object.
Step4: Assement of network specialization
NetSpec: Compute the interaction specialization over specified Evenness class (E1,E2,E3,E4,E5), and returns a list by class.
ggNetSpec: Visualize the result obtained from iNEXT_ND with a ggplot2 object.
Extra Step: Beta diversity and dissimilarity
iNEXT_beta_link: Compute the coverage-based/ size-based alpha, beta, gamma diversity and dissimilarity indices, and returns a list by index.
ggiNEXT_beta_link: Visualize the result obtained from iNEXT_ND with a ggplot2 object.
Phylogenetic
Step1: Assessment of sample completeness
NetSC: Compute the sample completeness over order.q, and returns a dataframe.
ggNetSC: Visualize the result obtained from NetSC with a ggplot2 object.
Step2: The asymptotic approach
ObsPND: Compute the sample empirical network diveristy, and returns a dataframe.
ggObsPND: Visualize the result obtained from ObsND with a ggplot2 object.
Step3: Non-asymptotic coverage-based rarefaction and extrapolation analysis
iNEXT_PND: Compute the sized-based/ coverage-based R/E network diversity, and returns a iNEXT object.
ggiNEXT_PND: Visualize the result obtained from iNEXT_ND with a ggplot2 object.
Step4: Assement of network specialization
NetSpec: Compute the interaction specialization over specified Evenness class (E1,E2,E3,E4,E5), and returns a list by class.
ggNetSpec: Visualize the result obtained from iNEXT_ND with a ggplot2 object.
Extra Step: Beta diversity and dissimilarity
iNEXT_beta_link: Compute the coverage-based/ size-based alpha, beta, gamma diversity and dissimilarity indices, and returns a list by index.
ggiNEXT_beta_link: Visualize the result obtained from iNEXT_ND with a ggplot2 object.
The framework can be summarized as follows.
knitr::include_graphics("pic/framework.png")
SOFTWARE NEEDED TO RUN iNEXT.link IN R:
- Required: R
- Suggested: RStudio IDE
HOW TO RUN iNEXT.link:
The iNEXT.link package is available on CRAN and can be downloaded with a standard R installation procedure using the following commands. Before installation, the additional visualization and computation extension packages (chaoUtility,ape, dplyr, ggplot2, phyclust, Rcpp) must be loaded. Please note that currently, package chaoUtility can only be available via github instead of CRAN and thus the installation procedure slightly differs from the one of standard R installation.
## install chaoUtility package from github install.packages("devtools") library(devtools) install_github("chaolab2019/chaoUtility") ## install iNEXT.links package from CRAN install.packages("iNEXT.link") ## Or instead, install the latest version from github install_github("Chunger-Lo/iNEXT.link") ## import packages library(chaoUtility) library(phytools) library(iNEXT) library(iNEXT.link)
# library(iNEXT) # source("..//R//iNEXTlink.R") # source("..//R//subfunction.R") # source("..//R//myfunc.R") # library(chaoUtility) library(tidyr) library(magrittr) library(miNEXT.beta) library(chaoUtility) library(phytools) library(iNEXT3D) library(iNEXT.link) library(miNEXT.beta) library(tidyverse)
# include abundance data # data(data.abu)
library(phytools) Shelfanger <- read.table("F://Chao//Network diversity//shinyapp//heir.entropy//data//Shelfanger.txt") Hickling <- read.table("F://Chao//Network diversity//shinyapp//heir.entropy//data/Hickling.txt") Norfolk <- list(Shelfanger = Shelfanger,Hickling = Hickling) Caguana <- read.table("F://Chao//Network diversity//shinyapp//heir.entropy//data/Caguana.txt") Cialitos <- read.table("F://Chao//Network diversity//shinyapp//heir.entropy//data/Cialitos.txt") Cordillera <- read.table("F://Chao//Network diversity//shinyapp//heir.entropy//data/Cordillera.txt") Fronton <- read.table("F://Chao//Network diversity//shinyapp//heir.entropy//data/Fronton.txt") data <- list(Cordillera = Cordillera,Caguana = Caguana,Fronton = Fronton,Cialitos = Cialitos) puerto.rico <- list(Cordillera = Cordillera,Caguana = Caguana,Fronton = Fronton,Cialitos = Cialitos) library(phytools) rowtree <- read.newick("F://Chao//Network diversity//shinyapp//heir.entropy//tree/rowtree.txt") coltree <- read.newick("F://Chao//Network diversity//shinyapp//heir.entropy//tree/coltree.txt") puerto.rico = list() puerto.rico[["data"]] = data puerto.rico[["col.tree"]] = coltree puerto.rico[["row.tree"]] = rowtree
MAIN FUNCTIONS:
We describe the four main functions with default arguments below :
a. Taxonomic
- iNEXT_ND():
iNEXT_ND(Norfolk, datatype = "abundance", q = c(0,1,2), endpoint = NULL, knots = 40, size = NULL, nboot = 30, conf = 0.95)
The arguments of this function are described below.
| Argument | Description |
|---|---|
data |
a matrix/data.frame of species abundances or incidence matrix. See the DATA FORMAT/INFORMATION section above for detailed required format. |
datatype |
data type of input data: individual-based abundance data (`datatype = "abundance"`), or species-by-site raw incidence matrix (`datatype = "incidence_raw"`). Default is `"abundance"` |
q |
a nonnegative value or sequence specifying the diversity order. There are three measures: Faith's PD (`q = 0`), a simple transformation of phylogenetic entropy (`q = 1`) and a simple transformation of Rao's quadratic entropy (`q = 2`). Default is `c(0,1,2)`. |
type |
desired diversity type: `type = "PD"` for Chao et al. (2010) phylogenetic diversity and `type = "meanPD"` for mean phylogenetic diversity (i.e., phylogenetic Hill number). Default is `"PD"`. |
endpoints |
a positive integer specifying the endpoint for rarefaction and extrapolation range. If `NULL`, then `endpoint =` double of the reference sample sizes. It is ignored if `size` is given. |
knots |
a positive integer specifying the number of equally-spaced knots between 1 and the `endpoint`. Default is 40. |
size |
a sequence of positive integers specifying the sample sizes for which PD or meanPD estimates will be calculated. If `NULL`, then estimates will be calculated for those sample sizes determined by the specified/default `endpoint` and `knots`. |
nboot |
a positive integer specifying the number of bootstrap replications in assessing sampling uncertainty and constructing confidence intervals. Enter 0 to skip the bootstrap procedures. Default is 50. |
conf |
a positive number < 1 specifying the level of confidence interval. Default is 0.95. |
The sequence of sample sizes for which PD/meanPD R/E curve will be estimated is determined by endpoint, knots and size.
If size is specified by users, then PD/meanPD will be estimated for these sizes plus the reference sample size(total species abundances for abundance data; total sampling units for incidence data).
If knots=K, then the sequece would be K/2 evenly‐spaced knots (sample sizes) before reference sample size and K/2 from reference sample size to endpoint, where the endpoint is default to double reference sample size. By default, knots=40.
If endpoint specified by users is smaller than the reference sample size, iNEXTPD only computes rarefaction estimates for approximately knots evenly spaced knots before the endpoint.
- AsyND():
asy = AsyND(Norfolk, q = c(0,1,2), datatype = "abundance", nboot = 30)
The arguments of this function are described below.
| Argument | Description |
|---|---|
data |
a matrix/data.frame of species abundances (for abundance data) or species-by-site raw incidence matrix (for incidence data). See the DATA FORMAT/INFORMATION section above for detailed required format. |
datatype |
data type of input data: individual-based abundance data (`datatype = "abundance"`), or species-by-site raw incidence matrix (`datatype = "incidence_raw"`). Default is `"abundance"` |
tree |
a phylo object describing the phylogenetic tree in Newick format for all observed species in the pooled assemblage. |
q |
a nonnegative value or sequence specifying the diversity order. Default is `seq(0, 2, by = 0.25)`. |
type |
desired diversity type: `type = "PD"` for Chao et al. (2010) phylogenetic diversity and `type = "meanPD"` for mean phylogenetic diversity (i.e., phylogenetic Hill number). Default is `"PD"`. |
nboot |
a positive integer specifying the number of bootstrap replications in assessing sampling uncertainty and constructing confidence intervals. Enter 0 to skip the bootstrap procedures. Default is 50. |
conf |
a positive number < 1 specifying the level of confidence interval. Default is 0.95. |
- ObsND():
obs = ObsND(Norfolk, q = c(0,1,2), datatype = "abundance", nboot = 30)
The arguments of this function are described below.
| Argument | Description |
|---|---|
data |
a matrix/data.frame of species abundances (for abundance data) or species-by-site raw incidence matrix (for incidence data). See the DATA FORMAT/INFORMATION section above for detailed required format. |
datatype |
data type of input data: individual-based abundance data (`datatype = "abundance"`), or species-by-site raw incidence matrix (`datatype = "incidence_raw"`). Default is `"abundance"` |
q |
a nonnegative value or sequence specifying the diversity order. Default is `seq(0, 2, by = 0.25)`. |
type |
desired diversity type: `type = "PD"` for Chao et al. (2010) phylogenetic diversity and `type = "meanPD"` for mean phylogenetic diversity (i.e., phylogenetic Hill number). Default is `"PD"`. |
nboot |
a positive integer specifying the number of bootstrap replications in assessing sampling uncertainty and constructing confidence intervals. Enter 0 to skip the bootstrap procedures. Default is 50. |
conf |
a positive number < 1 specifying the level of confidence interval. Default is 0.95. |
- estimateND():
estimateND(Norfolk, datatype="abundance", base="coverage",level=0.7, nboot = 30,conf=0.95)
The arguments of this function are described below.
| Argument | Description |
|---|---|
data |
a matrix/data.frame of species abundances (for abundance data) or species-by-site raw incidence matrix (for incidence data). See the DATA FORMAT/INFORMATION section above for detailed required format. |
nT |
needed only when `datatype = "incidence_raw"`, a sequence of named nonnegative integers specifying the number of sampling units in each assemblage. If `names(nT) = NULL`, automatically assigns "site1", "site2",..., as assemblage names. Ignored if `datatype = "abundance"`. |
datatype |
data type of input data: individual-based abundance data (`datatype = "abundance"`), or species-by-site raw incidence matrix (`datatype = "incidence_raw"`). Default is `"abundance"`. |
tree |
a phylo object describing the phylogenetic tree in Newick format for all observed species in the pooled assemblage. |
q |
a nonnegative value or sequence specifying the diversity order. Default is `c(0,1,2)`. |
reftime |
a positive value or sequence specifying the reference time for computing diversity. If `NULL`, `reftime` is set to be the tree depth of the phylogenetic tree spanned by the observed species in the pooled assemblage. Default is `NULL`. |
type |
desired diversity type: `type = "PD"` for Chao et al. (2010) phylogenetic diversity and `type = "meanPD"` for mean phylogenetic diversity (i.e., phylogenetic Hill number). Default is `"PD"`. |
level |
a positive value or sequence < 1 specifying a particular value of sample coverage. If `NULL`,then `level` will be chosen as the minimum coverage of all sites after extrapolating each site to its double sample sizes. Default is `NULL`. |
nboot |
a positive integer specifying the number of bootstrap replications in assessing sampling uncertainty and constructing confidence intervals. Enter 0 to skip the bootstrap procedures. Default is 50. |
conf |
a positive number < 1 specifying the level of confidence interval. Default is 0.95. |
- NetSpec():
NetSpec(Norfolk, q = seq(0,2,1), datatype = "abundance", nboot =30)
The arguments of this function are described below.
| Argument | Description |
|---|---|
data |
a matrix/data.frame of species abundances (for abundance data) or species-by-site raw incidence matrix (for incidence data). See the DATA FORMAT/INFORMATION section above for detailed required format. |
nT |
needed only when `datatype = "incidence_raw"`, a sequence of named nonnegative integers specifying the number of sampling units in each assemblage. If `names(nT) = NULL`, automatically assigns "site1", "site2",..., as assemblage names. Ignored if `datatype = "abundance"`. |
datatype |
data type of input data: individual-based abundance data (`datatype = "abundance"`), or species-by-site raw incidence matrix (`datatype = "incidence_raw"`). Default is `"abundance"`. |
tree |
a phylo object describing the phylogenetic tree in Newick format for all observed species in the pooled assemblage. |
q |
a nonnegative value or sequence specifying the diversity order. Default is `c(0,1,2)`. |
type |
desired diversity type: `type = "PD"` for Chao et al. (2010) phylogenetic diversity and `type = "meanPD"` for mean phylogenetic diversity (i.e., phylogenetic Hill number). Default is `"PD"`. |
level |
a positive value or sequence < 1 specifying a particular value of sample coverage. If `NULL`,then `level` will be chosen as the minimum coverage of all sites after extrapolating each site to its double sample sizes. Default is `NULL`. |
nboot |
a positive integer specifying the number of bootstrap replications in assessing sampling uncertainty and constructing confidence intervals. Enter 0 to skip the bootstrap procedures. Default is 50. |
b. Phylogenetic
- iNEXT_PND():
iNEXT_PND(x = puerto.rico$data, row.tree = puerto.rico$row.tree, col.tree = puerto.rico$col.tree, q = c(0,1,2), datatype = "abundance", endpoint = NULL, knots = 40, size = NULL, conf = 0.95, nboot = 10)
The arguments of this function are described below.
| Argument | Description |
|---|---|
data |
a matrix/data.frame of species abundances or incidence matrix. See the DATA FORMAT/INFORMATION section above for detailed required format. |
datatype |
data type of input data: individual-based abundance data (`datatype = "abundance"`), or species-by-site raw incidence matrix (`datatype = "incidence_raw"`). Default is `"abundance"` |
q |
a nonnegative value or sequence specifying the diversity order. There are three measures: Faith's PD (`q = 0`), a simple transformation of phylogenetic entropy (`q = 1`) and a simple transformation of Rao's quadratic entropy (`q = 2`). Default is `c(0,1,2)`. |
type |
desired diversity type: `type = "PD"` for Chao et al. (2010) phylogenetic diversity and `type = "meanPD"` for mean phylogenetic diversity (i.e., phylogenetic Hill number). Default is `"PD"`. |
endpoints |
a positive integer specifying the endpoint for rarefaction and extrapolation range. If `NULL`, then `endpoint =` double of the reference sample sizes. It is ignored if `size` is given. |
knots |
a positive integer specifying the number of equally-spaced knots between 1 and the `endpoint`. Default is 40. |
size |
a sequence of positive integers specifying the sample sizes for which PD or meanPD estimates will be calculated. If `NULL`, then estimates will be calculated for those sample sizes determined by the specified/default `endpoint` and `knots`. |
nboot |
a positive integer specifying the number of bootstrap replications in assessing sampling uncertainty and constructing confidence intervals. Enter 0 to skip the bootstrap procedures. Default is 50. |
conf |
a positive number < 1 specifying the level of confidence interval. Default is 0.95. |
The sequence of sample sizes for which PD/meanPD R/E curve will be estimated is determined by endpoint, knots and size.
If size is specified by users, then PD/meanPD will be estimated for these sizes plus the reference sample size(total species abundances for abundance data; total sampling units for incidence data).
If knots=K, then the sequece would be K/2 evenly‐spaced knots (sample sizes) before reference sample size and K/2 from reference sample size to endpoint, where the endpoint is default to double reference sample size. By default, knots=40.
If endpoint specified by users is smaller than the reference sample size, iNEXTPD only computes rarefaction estimates for approximately knots evenly spaced knots before the endpoint.
- AsyND():
AsyPND(puerto.rico$data, q = c(0,1,2), datatype = "abundance", nboot = 30)
The arguments of this function are described below.
| Argument | Description |
|---|---|
data |
a matrix/data.frame of species abundances (for abundance data) or species-by-site raw incidence matrix (for incidence data). See the DATA FORMAT/INFORMATION section above for detailed required format. |
nT |
needed only when `datatype = "incidence_raw"`, a sequence of named nonnegative integers specifying the number of sampling units in each assemblage. If `names(nT) = NULL`, automatically assigns "site1", "site2",..., as assemblage names. Ignored if `datatype = "abundance"`. |
datatype |
data type of input data: individual-based abundance data (`datatype = "abundance"`), or species-by-site raw incidence matrix (`datatype = "incidence_raw"`). Default is `"abundance"` |
tree |
a phylo object describing the phylogenetic tree in Newick format for all observed species in the pooled assemblage. |
q |
a nonnegative value or sequence specifying the diversity order. Default is `seq(0, 2, by = 0.25)`. |
reftime |
a positive value or sequence specifying the reference time for computing diversity. If `NULL`, `reftime` is set to be the tree depth of the phylogenetic tree spanned by the observed species in the pooled assemblage. Default is `NULL`. |
type |
desired diversity type: `type = "PD"` for Chao et al. (2010) phylogenetic diversity and `type = "meanPD"` for mean phylogenetic diversity (i.e., phylogenetic Hill number). Default is `"PD"`. |
nboot |
a positive integer specifying the number of bootstrap replications in assessing sampling uncertainty and constructing confidence intervals. Enter 0 to skip the bootstrap procedures. Default is 50. |
conf |
a positive number < 1 specifying the level of confidence interval. Default is 0.95. |
- ObsPND():
ObsPND(data.abu, datatype = "abundance", tree, q = c(0,1,2), datatype = "abundance", nboot = 30)
The arguments of this function are described below.
| Argument | Description |
|---|---|
data |
a matrix/data.frame of species abundances (for abundance data) or species-by-site raw incidence matrix (for incidence data). See the DATA FORMAT/INFORMATION section above for detailed required format. |
nT |
needed only when `datatype = "incidence_raw"`, a sequence of named nonnegative integers specifying the number of sampling units in each assemblage. If `names(nT) = NULL`, automatically assigns "site1", "site2",..., as assemblage names. Ignored if `datatype = "abundance"`. |
datatype |
data type of input data: individual-based abundance data (`datatype = "abundance"`), or species-by-site raw incidence matrix (`datatype = "incidence_raw"`). Default is `"abundance"` |
tree |
a phylo object describing the phylogenetic tree in Newick format for all observed species in the pooled assemblage. |
q |
a nonnegative value or sequence specifying the diversity order. Default is `seq(0, 2, by = 0.25)`. |
reftime |
a positive value or sequence specifying the reference time for computing diversity. If `NULL`, `reftime` is set to be the tree depth of the phylogenetic tree spanned by the observed species in the pooled assemblage. Default is `NULL`. |
type |
desired diversity type: `type = "PD"` for Chao et al. (2010) phylogenetic diversity and `type = "meanPD"` for mean phylogenetic diversity (i.e., phylogenetic Hill number). Default is `"PD"`. |
nboot |
a positive integer specifying the number of bootstrap replications in assessing sampling uncertainty and constructing confidence intervals. Enter 0 to skip the bootstrap procedures. Default is 50. |
conf |
a positive number < 1 specifying the level of confidence interval. Default is 0.95. |
- estimatePND():
estimatePND <- function(data, datatype = "abundance", tree, q = c(0,1,2), reftime=NULL, level = NULL, nboot = 50, conf = 0.95)
The arguments of this function are described below.
| Argument | Description |
|---|---|
data |
a matrix/data.frame of species abundances (for abundance data) or species-by-site raw incidence matrix (for incidence data). See the DATA FORMAT/INFORMATION section above for detailed required format. |
nT |
needed only when `datatype = "incidence_raw"`, a sequence of named nonnegative integers specifying the number of sampling units in each assemblage. If `names(nT) = NULL`, automatically assigns "site1", "site2",..., as assemblage names. Ignored if `datatype = "abundance"`. |
datatype |
data type of input data: individual-based abundance data (`datatype = "abundance"`), or species-by-site raw incidence matrix (`datatype = "incidence_raw"`). Default is `"abundance"`. |
tree |
a phylo object describing the phylogenetic tree in Newick format for all observed species in the pooled assemblage. |
q |
a nonnegative value or sequence specifying the diversity order. Default is `c(0,1,2)`. |
reftime |
a positive value or sequence specifying the reference time for computing diversity. If `NULL`, `reftime` is set to be the tree depth of the phylogenetic tree spanned by the observed species in the pooled assemblage. Default is `NULL`. |
type |
desired diversity type: `type = "PD"` for Chao et al. (2010) phylogenetic diversity and `type = "meanPD"` for mean phylogenetic diversity (i.e., phylogenetic Hill number). Default is `"PD"`. |
level |
a positive value or sequence < 1 specifying a particular value of sample coverage. If `NULL`,then `level` will be chosen as the minimum coverage of all sites after extrapolating each site to its double sample sizes. Default is `NULL`. |
nboot |
a positive integer specifying the number of bootstrap replications in assessing sampling uncertainty and constructing confidence intervals. Enter 0 to skip the bootstrap procedures. Default is 50. |
conf |
a positive number < 1 specifying the level of confidence interval. Default is 0.95. |
- NetSpec():
NetSpec(Norfolk, q = seq(0,2,1), datatype = "abundance", nboot =30)
The arguments of this function are described below.
| Argument | Description |
|---|---|
data |
a matrix/data.frame of species abundances (for abundance data) or species-by-site raw incidence matrix (for incidence data). See the DATA FORMAT/INFORMATION section above for detailed required format. |
nT |
needed only when `datatype = "incidence_raw"`, a sequence of named nonnegative integers specifying the number of sampling units in each assemblage. If `names(nT) = NULL`, automatically assigns "site1", "site2",..., as assemblage names. Ignored if `datatype = "abundance"`. |
datatype |
data type of input data: individual-based abundance data (`datatype = "abundance"`), or species-by-site raw incidence matrix (`datatype = "incidence_raw"`). Default is `"abundance"`. |
tree |
a phylo object describing the phylogenetic tree in Newick format for all observed species in the pooled assemblage. |
q |
a nonnegative value or sequence specifying the diversity order. Default is `c(0,1,2)`. |
type |
desired diversity type: `type = "PD"` for Chao et al. (2010) phylogenetic diversity and `type = "meanPD"` for mean phylogenetic diversity (i.e., phylogenetic Hill number). Default is `"PD"`. |
level |
a positive value or sequence < 1 specifying a particular value of sample coverage. If `NULL`,then `level` will be chosen as the minimum coverage of all sites after extrapolating each site to its double sample sizes. Default is `NULL`. |
nboot |
a positive integer specifying the number of bootstrap replications in assessing sampling uncertainty and constructing confidence intervals. Enter 0 to skip the bootstrap procedures. Default is 50. |
iNEXT.link VIA EXAMPLES: Network diversity analysis (taxonomic)
library(ade4) library(tidyverse) library(ape) library(dplyr)
Main function:
1.NetSC():
sc1 <- NetSC(x = Norfolk, datatype = "abundance", nboot = 10)
ggNetSC(sc1)
2.iNEXT_ND():
sample1 <- iNEXT_ND(x = Norfolk, datatype = "abundance", nboot = 30)
iNEXT_ND() returns a list containing three objects:
$DataInfo: The same table from function NDInfo(), which summarizes some network statistics for each assemblage, including reference sample size (n), number of observed species (S.obs), Connectance, the first two rare species frequency counts.
kable(sample1$DataInfo)
$iNextEst: Size-based / coverage-based diversity estimates along with confidence intervals and related statistics.
size-based
kable(head(sample1$iNextEst$size_based,5))
coverage-based
kable(head(sample1$iNextEst$coverage_based,5))
$AsyEst: Asymptotic/ Empirical diversity estimates along with confidence intervals and related statistics.
kable(head(sample1$AsyEst,9))
# only show part of the table, call View(dunes_iNEXT$size_based) to see full table. # sample_iNEXT$DataInfo # sample_iNEXT$iNextEst # sample_iNEXT$AsyEst
3. ggiNEXT_ND
To visualize the curves, use ggiNEXT_ND to obtain plots based on ggplot2 package. This function provides three types of curves, which can be specified in the argument plot.type:
- Sample-size-based rarefaction and extrapolation curve (
plot.type = 1): sampling curve depicting phylogenetic diversity estimates as a function of sample size. - Sample completeness curve (
plot.type = 2): the curve of sample coverage as a function of sample size. - Coverage-based R/E curve (
plot.type = 3): sampling curve depicting Network diversity estimates as a function of sample coverage.
ggiNEXT_ND(sample1, type = 1,facet = "Order.q" )
ggiNEXT_ND(sample1, type = 3, facet = "Assemblage")
4. Empirical / Asymptotic diversity
asy1 = AsyND(Norfolk,q = c(0,1,2),nboot = 10) head(asy1,5)
obs1 = ObsND(Norfolk,q = c(0,1,2),nboot = 10) head(obs1,5)
ggAsyND(rbind(obs1, asy1))
5. estimateND()
kable(estimateND(Norfolk, datatype="abundance", base="coverage",level=0.7, conf=0.95))
The estimateND() function returns a table of the computed diversity for specified/default diversity orders q and reference times for the user-specified values of sample coverage. The corresponding sample sizes and sample coverage values are also provided.
6. Specialization
spec1 = NetSpec(Norfolk, q = seq(0,2,1), datatype = "abundance", nboot =10)
ggSpec(spec1)
7. Dissimilarity
dissimilarity1 = iNEXT_beta_link(x = Norfolk, coverage_expected = seq(0.5,1,0.05), data_type='abundance', q = c(0, 1, 2),level='taxonomic', nboot = 0, conf = 0.95, max_alpha_coverage=F, by='coverage')
ggiNEXT_beta_link(dissimilarity1, type = 'B') ggiNEXT_beta_link(dissimilarity1, type = 'D')
kable(head(dissimilarity1$Region_1$gamma, 10)) kable(head(dissimilarity1$Region_1$alpha, 10)) kable(head(dissimilarity1$Region_1$beta, 10))
EXAMPLES2: Network diversity analysis (phylogenetic)
Main function:
1.NetSC():
sc2 <- NetSC(x = Norfolk, datatype = "abundance", nboot = 10)
2.iNEXT_PND():
sample2 <- iNEXT_PND(x = puerto.rico$data, datatype = "abundance", row.tree = rowtree, col.tree = coltree, nboot = 10)
iNEXT_PND() returns a list containing three objects:
$DataInfo: The same table from function PNDInfo(), which summarizes some network statistics for each assemblage, including reference sample size (n), number of observed species (S.obs), Connectance, the first two rare species frequency counts.
kable(sample2$DataInfo)
$iNextEst: Size-based / coverage-based diversity estimates along with confidence intervals and related statistics.
size-based
kable(head(sample2$iNextEst, 5)%>%rbind(tail(sample2$iNextEst, 5)))
$AsyEst: Asymptotic/ Empirical diversity estimates along with confidence intervals and related statistics.
kable(head(sample2$AsyEst,9))
3. ggiNEXT_PND
To visualize the curves, use ggiNEXT_PND to obtain plots based on ggplot2 package. This function provides three types of curves, which can be specified in the argument plot.type:
- Sample-size-based rarefaction and extrapolation curve (
plot.type = 1): sampling curve depicting phylogenetic diversity estimates as a function of sample size. - Sample completeness curve (
plot.type = 2): the curve of sample coverage as a function of sample size. - Coverage-based R/E curve (
plot.type = 3): sampling curve depicting Network diversity estimates as a function of sample coverage.
ggiNEXT_PND(sample2, type = 1)
ggiNEXT_PND(sample2, type = 3)
4. estimatePND()
kable(estimatePND(puerto.rico$data, col.tree = coltree, row.tree = rowtree, nboot = 10,datatype="abundance",level=0.7, conf=0.95))
5. Specialization
spec2 = phySpec(puerto.rico$data, q= seq(0,2,1), datatype = "abundance", nboot = 30, E = 1:5, method = "Estimated", C = 0.9)
ggSpec(spec2)
6. Dissimilarity
taxonomic
dissimilarity2 = iNEXT_beta_link(puerto.rico$data, coverage_expected = seq(0.5,1,0.025), data_type='abundance', q = c(0, 1, 2),level='taxonomic', row.tree = rowtree,col.tree = coltree, nboot = 0, conf = 0.95, max_alpha_coverage=F, by='coverage')
ggiNEXT_beta_link(dissimilarity2, type = 'B') ggiNEXT_beta_link(dissimilarity2, type = 'D')
kable(head(dissimilarity2$Region_1$gamma, 10)) kable(head(dissimilarity2$Region_1$alpha, 10)) kable(head(dissimilarity2$Region_1$beta, 10))
phylogenetic
dissimilarity3 = iNEXT_beta_link(x = puerto.rico$data, coverage_expected = seq(0.5,0.99,0.025), data_type='abundance', q = c(0, 1, 2),level='phylogenetic', row.tree = rowtree, col.tree = coltree, nboot = 0, conf = 0.95, max_alpha_coverage=F, by='coverage')
ggiNEXT_beta_link(dissimilarity3, type = 'B') ggiNEXT_beta_link(dissimilarity3, type = 'D')
kable(head(dissimilarity3$Region_1$gamma, 10)) kable(head(dissimilarity3$Region_1$alpha, 10)) kable(head(dissimilarity3$Region_1$beta, 10))
License
The iNEXT.link package is licensed under the GPLv3. To help refine iNEXT.link, your comments or feedbacks would be welcome (please send them to Anne Chao).
How to cite
If you publish your work based on results from iNEXT.link (R package), please make reference to Chao et al. given in the following list.
Reference
- Chao, A., Chiu C.-H. and Jost, L. (2010). Phylogenetic diversity measures based on Hill numbers. Philosophical Transactions of the Royal Society B., 365, 3599-3609.
- Chao, A., Chiu, C.-H., Hsieh, T. C., Davis, T., Nipperess, D., and Faith, D. (2015) Rarefaction and extrapolation of phylogenetic diversity. Methods in Ecology and Evolution, 6, 380-388.
- Hsieh, T. C. and Chao, A. (2017). Rarefaction and extrapolation: making fair comparison of abundance-sensitive phylogenetic diversity among multiple assemblages. Systematic Biology 66, 100-111.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.