specaccum {vegan}

Species Accumulation Curves

Description

Function specaccum finds species accumulation curves or the number of species for a certain number of sampled sites or individuals.

Usage

specaccum(comm, method = "exact", permutations = 100,
          conditioned =TRUE, gamma = "jack1",  w = NULL, subset, ...)
## S3 method for class 'specaccum'
plot(x, add = FALSE, random = FALSE, ci = 2, 
    ci.type = c("bar", "line", "polygon"), col = par("fg"), lty = 1,
    ci.col = col, ci.lty = 1, ci.length = 0, xlab, ylab = x$method, ylim,
    xvar = c("sites", "individuals", "effort"), ...)
## S3 method for class 'specaccum'
boxplot(x, add = FALSE, ...)
fitspecaccum(object, model, method = "random", ...)
## S3 method for class 'fitspecaccum'
plot(x, col = par("fg"), lty = 1, xlab = "Sites", 
    ylab = x$method, ...) 
## S3 method for class 'specaccum'
predict(object, newdata, interpolation = c("linear", "spline"), ...)
## S3 method for class 'fitspecaccum'
predict(object, newdata, ...)
specslope(object, at)

Arguments

comm

Community data set.

method

Species accumulation method (partial match). Method "collector" adds sites in the order they happen to be in the data, "random" adds sites in random order, "exact" finds the expected (mean) species richness, "coleman" finds the expected richness following Coleman et al. 1982, and "rarefaction" finds the mean when accumulating individuals instead of sites.

permutations

Number of permutations with method = "random". Usually an integer giving the number permutations, but can also be a list of control values for the permutations as returned by the function how, or a permutation matrix where each row gives the permuted indices.

conditioned

Estimation of standard deviation is conditional on the empirical dataset for the exact SAC

gamma

Method for estimating the total extrapolated number of species in the survey area by function specpool

w

Weights giving the sampling effort.

subset

logical expression indicating sites (rows) to keep: missing values are taken as FALSE.

x

A specaccum result object

add

Add to an existing graph.

random

Draw each random simulation separately instead of drawing their average and confidence intervals.

ci

Multiplier used to get confidence intervals from standard deviation (standard error of the estimate). Value ci = 0 suppresses drawing confidence intervals.

ci.type

Type of confidence intervals in the graph: "bar" draws vertical bars, "line" draws lines, and "polygon" draws a shaded area.

col

Colour for drawing lines.

lty

line type (see par).

ci.col

Colour for drawing lines or filling the "polygon".

ci.lty

Line type for confidence intervals or border of the "polygon".

ci.length

Length of horizontal bars (in inches) at the end of vertical bars with ci.type = "bar".

xlab, ylab

Labels for x (defaults xvar) and y axis.

ylim

the y limits of the plot.

xvar

Variable used for the horizontal axis: "individuals" can be used only with method = "rarefaction".

object

Either a community data set or fitted specaccum model.

model

Nonlinear regression model (nls). See Details.

newdata

Optional data used in prediction interpreted as number of sampling units (sites). If missing, fitted values are returned.

interpolation

Interpolation method used with newdata.

at

Number of plots where the slope is evaluated. Can be a real number.

...

Other parameters to functions.

Details

Species accumulation curves (SAC) are used to compare diversity properties of community data sets using different accumulator functions. The classic method is "random" which finds the mean SAC and its standard deviation from random permutations of the data, or subsampling without replacement (Gotelli & Colwell 2001). The "exact" method finds the expected SAC using sample-based rarefaction method that has been independently developed numerous times (Chiarucci et al. 2008) and it is often known as Mao Tau estimate (Colwell et al. 2012). The unconditional standard deviation for the exact SAC represents a moment-based estimation that is not conditioned on the empirical data set (sd for all samples > 0). The unconditional standard deviation is based on an estimation of the extrapolated number of species in the survey area (a.k.a. gamma diversity), as estimated by function specpool. The conditional standard deviation that was developed by Jari Oksanen (not published, sd=0 for all samples). Method "coleman" finds the expected SAC and its standard deviation following Coleman et al. (1982). All these methods are based on sampling sites without replacement. In contrast, the method = "rarefaction" finds the expected species richness and its standard deviation by sampling individuals instead of sites. It achieves this by applying function rarefy with number of individuals corresponding to average number of individuals per site.

Methods "random" and "collector" can take weights (w) that give the sampling effort for each site. The weights w do not influence the order the sites are accumulated, but only the value of the sampling effort so that not all sites are equal. The summary results are expressed against sites even when the accumulation uses weights (methods "random", "collector"), or is based on individuals ("rarefaction"). The actual sampling effort is given as item Effort or Individuals in the printed result. For weighted "random" method the effort refers to the average effort per site, or sum of weights per number of sites. With weighted method = "random", the averaged species richness is found from linear interpolation of single random permutations. Therefore at least the first value (and often several first) have NA richness, because these values cannot be interpolated in all cases but should be extrapolated. The plot function defaults to display the results as scaled to sites, but this can be changed selecting xvar = "effort" (weighted methods) or xvar = "individuals" (with method = "rarefaction").

The summary and boxplot methods are available for method = "random".

Function predict for specaccum can return the values corresponding to newdata. With method "exact", "rarefaction" and "coleman" the function uses analytic equations for interpolated non-integer values, and for other methods linear (approx) or spline (spline) interpolation. If newdata is not given, the function returns the values corresponding to the data. NB., the fitted values with method="rarefaction" are based on rounded integer counts, but predict can use fractional non-integer counts with newdata and give slightly different results.

Function fitspecaccum fits a nonlinear (nls) self-starting species accumulation model. The input object can be a result of specaccum or a community in data frame. In the latter case the function first fits a specaccum model and then proceeds with fitting the nonlinear model. The function can apply a limited set of nonlinear regression models suggested for species-area relationship (Dengler 2009). All these are selfStart models. The permissible alternatives are "arrhenius" (SSarrhenius), "gleason" (SSgleason), "gitay" (SSgitay), "lomolino" (SSlomolino) of vegan package. In addition the following standard R models are available: "asymp" (SSasymp), "gompertz" (SSgompertz), "michaelis-menten" (SSmicmen), "logis" (SSlogis), "weibull" (SSweibull). See these functions for model specification and details.

When weights w were used the fit is based on accumulated effort and in model = "rarefaction" on accumulated number of individuals. The plot is still based on sites, unless other alternative is selected with xvar.

Function predict for fitspecaccum uses predict.nls, and you can pass all arguments to that function. In addition, fitted, residuals, nobs, coef, AIC, logLik and deviance work on the result object.

Function specslope evaluates the derivative of the species accumulation curve at given number of sample plots, and gives the rate of increase in the number of species. The function works with specaccum result object when this is based on analytic models "exact", "rarefaction" or "coleman", and with non-linear regression results of fitspecaccum.

Nonlinear regression may fail for any reason, and some of the fitspecaccum models are fragile and may not succeed.

Value

Function specaccum returns an object of class "specaccum", and fitspecaccum a model of class "fitspecaccum" that adds a few items to the "specaccum" (see the end of the list below):

call

Function call.

method

Accumulator method.

sites

Number of sites. For method = "rarefaction" this is the number of sites corresponding to a certain number of individuals and generally not an integer, and the average number of individuals is also returned in item individuals.

effort

Average sum of weights corresponding to the number of sites when model was fitted with argument w

richness

The number of species corresponding to number of sites. With method = "collector" this is the observed richness, for other methods the average or expected richness.

sd

The standard deviation of SAC (or its standard error). This is NULL in method = "collector", and it is estimated from permutations in method = "random", and from analytic equations in other methods.

perm

Permutation results with method = "random" and NULL in other cases. Each column in perm holds one permutation.

weights

Matrix of accumulated weights corresponding to the columns of the perm matrix when model was fitted with argument w.

fitted, residuals, coefficients

Only in fitspecacum: fitted values, residuals and nonlinear model coefficients. For method = "random" these are matrices with a column for each random accumulation.

models

Only in fitspecaccum: list of fitted nls models (see Examples on accessing these models).

Note

The SAC with method = "exact" was developed by Roeland Kindt, and its standard deviation by Jari Oksanen (both are unpublished). The method = "coleman" underestimates the SAC because it does not handle properly sampling without replacement. Further, its standard deviation does not take into account species correlations, and is generally too low.

Author(s)

Roeland Kindt [e-mail] and Jari Oksanen.

References

Chiarucci, A., Bacaro, G., Rocchini, D. & Fattorini, L. (2008). Discovering and rediscovering the sample-based rarefaction formula in the ecological literature. Commun. Ecol. 9: 121–123.

Coleman, B.D, Mares, M.A., Willis, M.R. & Hsieh, Y. (1982). Randomness, area and species richness. Ecology 63: 1121–1133.

Colwell, R.K., Chao, A., Gotelli, N.J., Lin, S.Y., Mao, C.X., Chazdon, R.L. & Longino, J.T. (2012). Models and estimators linking individual-based and sample-based rarefaction, extrapolation and comparison of assemblages. J. Plant Ecol. 5: 3–21.

Dengler, J. (2009). Which function describes the species-area relationship best? A review and empirical evaluation. Journal of Biogeography 36, 728–744.

Gotelli, N.J. & Colwell, R.K. (2001). Quantifying biodiversity: procedures and pitfalls in measurement and comparison of species richness. Ecol. Lett. 4, 379–391.

See Also

rarefy and rrarefy are related individual based models. Other accumulation models are poolaccum for extrapolated richness, and renyiaccum and tsallisaccum for diversity indices. Underlying graphical functions are boxplot, matlines, segments and polygon.

Examples

data(BCI)
sp1 <- specaccum(BCI)
sp2 <- specaccum(BCI, "random")
sp2
summary(sp2)
plot(sp1, ci.type="poly", col="blue", lwd=2, ci.lty=0, ci.col="lightblue")
boxplot(sp2, col="yellow", add=TRUE, pch="+")
## Fit Lomolino model to the exact accumulation
mod1 <- fitspecaccum(sp1, "lomolino")
coef(mod1)
fitted(mod1)
plot(sp1)
## Add Lomolino model using argument 'add'
plot(mod1, add = TRUE, col=2, lwd=2)
## Fit Arrhenius models to all random accumulations
mods <- fitspecaccum(sp2, "arrh")
plot(mods, col="hotpink")
boxplot(sp2, col = "yellow", border = "blue", lty=1, cex=0.3, add= TRUE)
## Use nls() methods to the list of models
sapply(mods$models, AIC)