specaccum: Species Accumulation Curves
In pattakosn/Rworkshop: Community Ecology Package

Description Usage Arguments Details Value Note Author(s) References See Also Examples

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

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"), ci.col = col, 
    ci.lty = 1, 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, ...)

`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"`.
`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 (an experimental feature that may be removed).
`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`	...
`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.
`ci.col`	Colour for drawing lines or filling the `"polygon"`.
`ci.lty`	Line type for confidence intervals or border of the `"polygon"`.
`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.
`lty`	line type code (see `par`.
`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`.
`...`	Other parameters to functions.

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 the method that was independently developed by Ugland et al. (2003), Colwell et al. (2004) and Kindt et al. (2006). 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), unlike the conditional standard deviation that was developed by Jari Oksanen (not published, sd=0 for all samples). The unconditional standard deviation is based on an estimation of the total extrapolated number of species in the survey area (a.k.a. gamma diversity), as estimated by function specpool. 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.

The function has a plot method. In addition, method = "random" has summary and boxplot methods.

Function predict can return the values corresponding to newdata using linear (approx) or spline (spline) interpolation. The function cannot extrapolate with linear interpolation, and with spline the type and sensibility of the extrapolation depends on argument method which is passed to spline. If newdata is not given, the function returns the values corresponding to the data.

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 a 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.

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

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

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`.
`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.
`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).

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.

Roeland Kindt r.kindt@cgiar.org and Jari Oksanen.

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

Colwell, R.K., Mao, C.X. & Chang, J. (2004). Interpolating, extrapolating, and comparing incidence-based species accumulation curves. Ecology 85: 2717–2727.

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

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

Kindt, R. (2003). Exact species richness for sample-based accumulation curves. Manuscript.

Kindt R., Van Damme, P. & Simons, A.J. (2006) Patterns of species richness at varying scales in western Kenya: planning for agroecosystem diversification. Biodiversity and Conservation, 10: 3235–3249.

Ugland, K.I., Gray, J.S. & Ellingsen, K.E. (2003). The species-accumulation curve and estimation of species richness. Journal of Animal Ecology 72: 888–897.

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.

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)