Species Accumulation Curves
specaccum.Rd
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 functionhow
, 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
(defaultsxvar
) andy
axis.- ylim
the y limits of the plot.
- xvar
Variable used for the horizontal axis:
"individuals"
can be used only withmethod = "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 itemindividuals
.- 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
inmethod = "collector"
, and it is estimated from permutations inmethod = "random"
, and from analytic equations in other methods.- perm
Permutation results with
method = "random"
andNULL
in other cases. Each column inperm
holds one permutation.- weights
Matrix of accumulated weights corresponding to the columns of the
perm
matrix when model was fitted with argumentw
.- fitted, residuals, coefficients
Only in
fitspecacum
: fitted values, residuals and nonlinear model coefficients. Formethod = "random"
these are matrices with a column for each random accumulation.- models
Only in
fitspecaccum
: list of fittednls
models (see Examples on accessing these models).
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.
Author
Roeland Kindt r.kindt@cgiar.org and Jari Oksanen.
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.
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)
#> Warning: the standard deviation is zero
sp2 <- specaccum(BCI, "random")
sp2
#> Species Accumulation Curve
#> Accumulation method: random, with 100 permutations
#> Call: specaccum(comm = BCI, method = "random")
#>
#>
#> Sites 1.0000 2.00000 3.00000 4.0000 5.00000 6.00000 7.00000
#> Richness 90.8800 121.28000 138.57000 150.3600 158.77000 165.47000 170.72000
#> sd 6.9809 6.78394 6.45615 6.0595 6.08501 5.61645 5.24757
#>
#> Sites 8.00000 9.00000 10.00000 11.00000 12.00000 13.000 14.00000
#> Richness 175.62000 179.24000 182.40000 185.02000 187.48000 190.150 192.03000
#> sd 5.28726 5.29936 5.53227 5.22229 5.32097 5.058 4.80415
#>
#> Sites 15.00000 16.00000 17.00000 18.00000 19.00000 20.00000 21.00000
#> Richness 193.90000 195.46000 197.23000 198.82000 200.48000 201.70000 203.03000
#> sd 4.49354 4.22695 4.10187 3.99591 3.83888 3.82311 3.54895
#>
#> Sites 22.00000 23.00000 24.00000 25.00000 26.00 27.00000 28.00000
#> Richness 204.24000 205.49000 206.65000 207.80000 208.83 209.92000 210.84000
#> sd 3.44398 3.35898 3.40343 3.44656 3.30 3.31413 3.24028
#>
#> Sites 29.00000 30.00000 31.00000 32.00000 33.00000 34.00000 35.00000
#> Richness 211.75000 212.85000 213.57000 214.59000 215.27000 216.16000 216.92000
#> sd 3.15068 3.10872 3.17902 3.11106 3.06448 2.99737 2.84154
#>
#> Sites 36.00000 37.00000 38.00000 39.00000 40.00000 41.00000 42.00000
#> Richness 217.64000 218.29000 218.95000 219.56000 220.35000 221.02000 221.52000
#> sd 2.65726 2.59485 2.58736 2.45904 2.28908 2.26069 2.03246
#>
#> Sites 43.00000 44.00000 45.00000 46.00000 47.00000 48.00000 49.0000
#> Richness 221.97000 222.44000 223.01000 223.46000 223.82000 224.22000 224.6300
#> sd 1.85568 1.74842 1.46677 1.20118 1.03845 0.90543 0.6139
#>
#> Sites 50
#> Richness 225
#> sd 0
summary(sp2)
#> 1 sites 2 sites 3 sites 4 sites
#> Min. : 81.00 Min. :103.0 Min. :122.0 Min. :135.0
#> 1st Qu.: 85.00 1st Qu.:116.0 1st Qu.:134.0 1st Qu.:145.0
#> Median : 90.00 Median :122.0 Median :139.0 Median :151.0
#> Mean : 90.88 Mean :121.3 Mean :138.6 Mean :150.4
#> 3rd Qu.: 93.00 3rd Qu.:125.2 3rd Qu.:143.0 3rd Qu.:155.0
#> Max. :109.00 Max. :140.0 Max. :153.0 Max. :163.0
#> 5 sites 6 sites 7 sites 8 sites
#> Min. :142.0 Min. :151.0 Min. :156.0 Min. :165.0
#> 1st Qu.:154.0 1st Qu.:162.0 1st Qu.:167.0 1st Qu.:172.0
#> Median :159.0 Median :166.0 Median :171.0 Median :176.0
#> Mean :158.8 Mean :165.5 Mean :170.7 Mean :175.6
#> 3rd Qu.:163.0 3rd Qu.:169.2 3rd Qu.:174.0 3rd Qu.:179.2
#> Max. :173.0 Max. :175.0 Max. :182.0 Max. :188.0
#> 9 sites 10 sites 11 sites 12 sites
#> Min. :168.0 Min. :171.0 Min. :174.0 Min. :174.0
#> 1st Qu.:175.0 1st Qu.:178.8 1st Qu.:181.8 1st Qu.:184.0
#> Median :179.0 Median :182.0 Median :185.0 Median :187.0
#> Mean :179.2 Mean :182.4 Mean :185.0 Mean :187.5
#> 3rd Qu.:183.0 3rd Qu.:186.0 3rd Qu.:190.0 3rd Qu.:192.0
#> Max. :191.0 Max. :193.0 Max. :195.0 Max. :198.0
#> 13 sites 14 sites 15 sites 16 sites
#> Min. :177.0 Min. :179.0 Min. :182.0 Min. :184.0
#> 1st Qu.:186.0 1st Qu.:189.0 1st Qu.:190.0 1st Qu.:192.0
#> Median :190.0 Median :192.0 Median :194.0 Median :196.0
#> Mean :190.2 Mean :192.0 Mean :193.9 Mean :195.5
#> 3rd Qu.:194.0 3rd Qu.:195.2 3rd Qu.:197.2 3rd Qu.:199.0
#> Max. :201.0 Max. :202.0 Max. :202.0 Max. :202.0
#> 17 sites 18 sites 19 sites 20 sites
#> Min. :185.0 Min. :188.0 Min. :190.0 Min. :190.0
#> 1st Qu.:195.0 1st Qu.:196.8 1st Qu.:197.8 1st Qu.:199.0
#> Median :198.0 Median :199.0 Median :200.0 Median :202.0
#> Mean :197.2 Mean :198.8 Mean :200.5 Mean :201.7
#> 3rd Qu.:200.0 3rd Qu.:201.0 3rd Qu.:203.0 3rd Qu.:204.0
#> Max. :204.0 Max. :209.0 Max. :209.0 Max. :211.0
#> 21 sites 22 sites 23 sites 24 sites
#> Min. :192.0 Min. :194.0 Min. :195.0 Min. :196.0
#> 1st Qu.:201.0 1st Qu.:202.0 1st Qu.:203.8 1st Qu.:205.0
#> Median :203.0 Median :205.0 Median :206.0 Median :207.0
#> Mean :203.0 Mean :204.2 Mean :205.5 Mean :206.7
#> 3rd Qu.:205.2 3rd Qu.:206.0 3rd Qu.:208.0 3rd Qu.:209.0
#> Max. :211.0 Max. :212.0 Max. :212.0 Max. :214.0
#> 25 sites 26 sites 27 sites 28 sites
#> Min. :197.0 Min. :197.0 Min. :199.0 Min. :199.0
#> 1st Qu.:206.0 1st Qu.:207.0 1st Qu.:208.0 1st Qu.:209.0
#> Median :208.0 Median :209.0 Median :210.0 Median :211.0
#> Mean :207.8 Mean :208.8 Mean :209.9 Mean :210.8
#> 3rd Qu.:210.0 3rd Qu.:211.0 3rd Qu.:213.0 3rd Qu.:213.0
#> Max. :215.0 Max. :216.0 Max. :217.0 Max. :218.0
#> 29 sites 30 sites 31 sites 32 sites
#> Min. :199.0 Min. :200.0 Min. :202.0 Min. :203.0
#> 1st Qu.:210.0 1st Qu.:211.0 1st Qu.:212.0 1st Qu.:213.0
#> Median :212.0 Median :213.0 Median :214.0 Median :215.0
#> Mean :211.8 Mean :212.8 Mean :213.6 Mean :214.6
#> 3rd Qu.:214.0 3rd Qu.:215.0 3rd Qu.:216.0 3rd Qu.:216.2
#> Max. :219.0 Max. :219.0 Max. :220.0 Max. :221.0
#> 33 sites 34 sites 35 sites 36 sites
#> Min. :204.0 Min. :207.0 Min. :208.0 Min. :210.0
#> 1st Qu.:214.0 1st Qu.:214.0 1st Qu.:215.0 1st Qu.:216.0
#> Median :216.0 Median :217.0 Median :217.0 Median :218.0
#> Mean :215.3 Mean :216.2 Mean :216.9 Mean :217.6
#> 3rd Qu.:217.0 3rd Qu.:218.0 3rd Qu.:219.0 3rd Qu.:220.0
#> Max. :222.0 Max. :223.0 Max. :223.0 Max. :224.0
#> 37 sites 38 sites 39 sites 40 sites 41 sites
#> Min. :210.0 Min. :210.0 Min. :210.0 Min. :212.0 Min. :213
#> 1st Qu.:217.0 1st Qu.:217.0 1st Qu.:218.0 1st Qu.:219.0 1st Qu.:220
#> Median :218.0 Median :219.0 Median :220.0 Median :221.0 Median :221
#> Mean :218.3 Mean :218.9 Mean :219.6 Mean :220.3 Mean :221
#> 3rd Qu.:220.0 3rd Qu.:221.0 3rd Qu.:221.0 3rd Qu.:222.0 3rd Qu.:223
#> Max. :224.0 Max. :225.0 Max. :225.0 Max. :225.0 Max. :225
#> 42 sites 43 sites 44 sites 45 sites 46 sites
#> Min. :216.0 Min. :217 Min. :218.0 Min. :220 Min. :220.0
#> 1st Qu.:220.0 1st Qu.:221 1st Qu.:221.0 1st Qu.:222 1st Qu.:223.0
#> Median :222.0 Median :222 Median :223.0 Median :223 Median :223.0
#> Mean :221.5 Mean :222 Mean :222.4 Mean :223 Mean :223.5
#> 3rd Qu.:223.0 3rd Qu.:223 3rd Qu.:224.0 3rd Qu.:224 3rd Qu.:225.0
#> Max. :225.0 Max. :225 Max. :225.0 Max. :225 Max. :225.0
#> 47 sites 48 sites 49 sites 50 sites
#> Min. :220.0 Min. :220.0 Min. :223.0 Min. :225
#> 1st Qu.:223.0 1st Qu.:224.0 1st Qu.:224.0 1st Qu.:225
#> Median :224.0 Median :224.0 Median :225.0 Median :225
#> Mean :223.8 Mean :224.2 Mean :224.6 Mean :225
#> 3rd Qu.:225.0 3rd Qu.:225.0 3rd Qu.:225.0 3rd Qu.:225
#> Max. :225.0 Max. :225.0 Max. :225.0 Max. :225
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)
#> Asym xmid slope
#> 258.440682 2.442061 1.858694
fitted(mod1)
#> [1] 94.34749 121.23271 137.45031 148.83053 157.45735 164.31866 169.95946
#> [8] 174.71115 178.78954 182.34254 185.47566 188.26658 190.77402 193.04337
#> [15] 195.11033 197.00350 198.74606 200.35705 201.85227 203.24499 204.54643
#> [22] 205.76612 206.91229 207.99203 209.01150 209.97609 210.89054 211.75903
#> [29] 212.58527 213.37256 214.12386 214.84180 215.52877 216.18692 216.81820
#> [36] 217.42437 218.00703 218.56767 219.10762 219.62811 220.13027 220.61514
#> [43] 221.08369 221.53679 221.97528 222.39991 222.81138 223.21037 223.59747
#> [50] 223.97327
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)
#> [1] 311.6777 339.3428 360.0927 299.6324 271.8605 352.6303 351.1309 346.9388
#> [9] 332.9162 339.3872 342.8842 318.2202 324.2260 329.6036 279.4905 320.2862
#> [17] 296.5978 304.1313 320.1109 337.4196 324.8484 300.3558 337.8074 327.3490
#> [25] 324.1918 334.4916 344.6955 332.5127 326.9841 331.7491 284.7534 317.9683
#> [33] 331.7503 324.0334 335.0137 333.0192 301.3500 362.5924 352.4797 318.7456
#> [41] 321.2433 352.3388 342.5373 337.0975 347.4913 333.5532 342.1247 319.3285
#> [49] 312.0145 362.7032 304.5709 307.0715 295.3983 357.9605 311.3779 348.7694
#> [57] 304.0819 327.8630 353.6658 314.1851 323.1093 320.9968 343.2834 348.8533
#> [65] 322.1267 327.3126 332.6625 342.4624 351.3331 342.5683 336.9944 321.5591
#> [73] 360.5222 320.7123 310.1364 345.6802 286.4162 313.5608 336.6158 322.3123
#> [81] 296.6553 348.3919 335.0432 301.8475 362.5773 361.6093 326.3865 335.7143
#> [89] 343.5142 359.0284 303.7928 329.4691 334.8476 312.2365 303.6824 327.0915
#> [97] 352.2847 353.3203 315.8118 362.1672