A Quick Introduction to iNEXT via Examples
T. C. Hsieh, K. H. Ma, and Anne Chao
20190124
iNEXT
(iNterpolation and EXTrapolation) is an R package modified from the original version which was supplied in the Supplement of Chao et al. (2014). In the latest updated version, we have added more user‐friendly features and refined the graphic displays. In this document, we provide a quick introduction demonstrating how to run iNEXT
. Detailed information about iNEXT
functions is provided in the iNEXT Manual, also available in CRAN. See Chao & Jost (2012), Colwell et al. (2012) and Chao et al. (2014) for methodologies. A short review of the theoretical background and a brief description of methods are included in an application paper by Hsieh, Ma & Chao (2016). An online version of iNEXT
(http://chao.stat.nthu.edu.tw/wordpress/software_download/inextonline/) is also available for users without an R background.
iNEXT
focuses on three measures of Hill numbers of order q: species richness (q = 0
), Shannon diversity (q = 1
, the exponential of Shannon entropy) and Simpson diversity (q = 2
, the inverse of Simpson concentration). For each diversity measure, iNEXT
uses the observed sample of abundance or incidence data (called the “reference sample”) to compute diversity estimates and the associated 95% confidence intervals for the following two types of rarefaction and extrapolation (R/E):
 Sample‐size‐based R/E sampling curves:
iNEXT
computes diversity estimates for rarefied and extrapolated samples up to an appropriate size. This type of sampling curve plots the diversity estimates with respect to sample size.
 Coverage‐based R/E sampling curves:
iNEXT
computes diversity estimates for rarefied and extrapolated samples with sample completeness (as measured by sample coverage) up to an appropriate coverage. This type of sampling curve plots the diversity estimates with respect to sample coverage.
iNEXT
also plots the above two types of sampling curves and a sample completeness curve. The sample completeness curve provides a bridge between these two types of curves.
SOFTWARE NEEDED TO RUN INEXT IN R
HOW TO RUN INEXT:
The iNEXT
package is available on CRAN and can be downloaded with a standard R installation procedure using the following commands. For a first‐time installation, an additional visualization extension package (ggplot2
) must be loaded.
## install iNEXT package from CRAN
install.packages("iNEXT")
## install the latest version from github
install.packages('devtools')
library(devtools)
install_github('JohnsonHsieh/iNEXT')
## import packages
library(iNEXT)
library(ggplot2)
Remark: In order to install devtools
package, you should update R to the latest version. Also, to get install_github
to work, you should install the httr
package.
MAIN FUNCTION: iNEXT()
We first describe the main function iNEXT()
with default arguments:
iNEXT(x, q=0, datatype="abundance", size=NULL, endpoint=NULL, knots=40, se=TRUE, conf=0.95, nboot=50)
The arguments of this function are briefly described below, and will be explained in more details by illustrative examples in later text. This main function computes diversity estimates of order q, the sample coverage estimates and related statistics for K (if
knots=K
) evenly‐spaced knots (sample sizes) between size 1 and the
endpoint
, where the endpoint is described below. Each knot represents a particular sample size for which diversity estimates will be calculated. By default, endpoint = double the reference sample size (total sample size for abundance data; total sampling units for incidence data). For example, if
endpoint = 10
,
knot = 4
, diversity estimates will be computed for a sequence of samples with sizes (1, 4, 7, 10).
x

a matrix , data.frame , lists of species abundances, or lists of incidence frequencies (see data format/information below).

q

a number or vector specifying the diversity order(s) of Hill numbers.

datatype

type of input data, “abundance” , “incidence_raw” or “incidence_freq” .

size

an integer vector of sample sizes for which diversity estimates will be computed. If NULL , then diversity estimates will be calculated for those sample sizes determined by the specified/default endpoint and knots.

endpoint

an integer specifying the sample size that is the endpoint for R/E calculation; If NULL , then endpoint=double the reference sample size.

knots

an integer specifying the number of equally‐spaced knots between size 1 and the endpoint.

se

a logical variable to calculate the bootstrap standard error and conf confidence interval.

conf

a positive number < 1 specifying the level of confidence interval.

nboot

an integer specifying the number of bootstrap replications.

This function returns an "iNEXT"
object which can be further used to make plots using the function ggiNEXT()
to be described below.
GRAPHIC DISPLAYS: FUNCTION ggiNEXT()
The function ggiNEXT()
, which extends ggplot2
to the "iNEXT"
object with default arguments, is described as follows:
ggiNEXT(x, type=1, se=TRUE, facet.var="none", color.var="site", grey=FALSE)
Here x
is an "iNEXT"
object. Three types of curves are allowed:
Samplesizebased R/E curve (type=1
): see Figs. 1a and 2a in the main text. This curve plots diversity estimates with confidence intervals (if se=TRUE
) as a function of sample size up to double the reference sample size, by default, or a user‐specified endpoint
.
Sample completeness curve (type=2
) with confidence intervals (if se=TRUE
): see Figs. 1b and 2b in the main text. This curve plots the sample coverage with respect to sample size for the same range described in (1).
Coveragebased R/E curve (type=3
): see Figs. 1c and 2c in the main text. This curve plots the diversity estimates with confidence intervals (if se=TRUE
) as a function of sample coverage up to the maximum coverage obtained from the maximum size described in (1).
The argument facet.var=("none", "order", "site" or "both")
is used to create a separate plot for each value of the specified variable. For example, the following code displays a separate plot (in Figs 1a and 1c) for each value of the diversity order q. The user may also use the argument grey=TRUE
to plot black/white figures. The usage of color.var is illustrated in the incidence data example described in later text. The ggiNEXT()
function is a wrapper around ggplot2
package to create a R/E curve using a single line of code. The resulting object is of class "ggplot"
, so can be manipulated using the ggplot2
tools.
out < iNEXT(spider, q=c(0, 1, 2), datatype="abundance", endpoint=500)
# Sample‐size‐based R/E curves, separating by "site""
ggiNEXT(out, type=1, facet.var="site")
## Not run:
# Sample‐size‐based R/E curves, separating by "order"
ggiNEXT(out, type=1, facet.var="order")
# display black‐white theme
ggiNEXT(out, type=1, facet.var="order", grey=TRUE)
## End(Not run)
The argument facet.var="site"
in ggiNEXT
function creates a separate plot for each site as shown below:
# Sample‐size‐based R/E curves, separating by "site""
ggiNEXT(out, type=1, facet.var="site")
The argument facet.var="order"
and color.var="site"
creates a separate plot for each diversity order site, and within each plot, different colors are used for two sites.
ggiNEXT(out, type=1, facet.var="order", color.var="site")
The following commands return the sample completeness curve in which different colors are used for the two sites:
ggiNEXT(out, type=2, facet.var="none", color.var="site")
The following commands return the coverage‐based R/E sampling curves in which different colors are used for the two sites (facet.var="site"
) and for three orders (facet.var="order"
)
ggiNEXT(out, type=3, facet.var="site")
ggiNEXT(out, type=3, facet.var="order", color.var="site")
INCIDENCE DATA
For illustration, we use the tropical ant data (in the dataset ant included in the package) at five elevations (50m, 500m, 1070m, 1500m, and 2000m) collected by Longino & Colwell (2011) from Costa Rica. The 5 lists of incidence frequencies are shown below. The first entry of each list must be the total number of sampling units, followed by the species incidence frequencies.
data(ant)
str(ant)
List of 5
$ h50m : num [1:228] 599 330 263 236 222 195 186 183 182 129 ...
$ h500m : num [1:242] 230 133 131 123 78 73 65 60 60 56 ...
$ h1070m: num [1:123] 150 99 96 80 74 68 60 54 46 45 ...
$ h1500m: num [1:57] 200 144 113 79 76 74 73 53 50 43 ...
$ h2000m: num [1:15] 200 80 59 34 23 19 15 13 8 8 ...
The argument color.var = ("none", "order", "site" or "both")
is used to display curves in different colors for values of the specified variable. For example, the following code using the argument color.var="site"
displays the sampling curves in different colors for the five sites. Note that theme_bw()
is a ggplot2 function to modify display setting from grey background to black‐and‐white. The following commands return three types R/E sampling curves for ant data.
t < seq(1, 700, by=10)
out.inc < iNEXT(ant, q=0, datatype="incidence_freq", size=t)
# Sample‐size‐based R/E curves
ggiNEXT(out.inc, type=1, color.var="site") +
theme_bw(base_size = 18) +
theme(legend.position="none")