Package 'sprex'

Title: Calculate Species Richness and Extrapolation Metrics
Description: Calculate species richness functions for rarefaction and extrapolation.
Authors: Eric Archer [aut, cre]
Maintainer: Eric Archer <[email protected]>
License: GNU General Public License
Version: 1.4.1
Built: 2024-11-28 06:33:09 UTC
Source: CRAN

Help Index

Calculate species richness and extrapolation metrics

Description

Calculate species richness and expected number of species primarily based on algorithms in Colwell, R.K., A. Chao, N.J. Gotelli, S.-Y. Lin, C.X. Mao, R.L. Chazdon, and J.T. Longino. 2012. Models and estimators linking individual-based and sample-based rarefaction, extrapolation and comparison of assemblages. Journal of Plant Ecology 5(1):3-21.

Details

sprex

Number of Unobserved Species

Description

Calculate the number of unobserved species (f0).

Usage

ACE(f)

Chao1(f)

Clench(f, pct.n = 0.85, num.reps = 100)

Swor1(f, N)

iChao1(f)

jack1(f)

jack2(f)

Arguments

f

a vector of species frequencies where f[i] is the number of species represented by only i samples.
pct.n

percent of samples to use in bootstrap draws. Must be in range of 0:1.
num.reps

number of random re-orderings of samples to fit curve to.
N

population size.

Value

All functions return a vector containing the estimated number of species (s.est), unobserved species (f0), observed species (s.obs), and the total number of samples (n). Swor1 also returns the standard deviation of s.est as sd.s.est.

Author(s)

Eric Archer [email protected]

References

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

jack1,jack2: Burnham, KP and WS Overton. 1978. Estimation of the size of a closed population when capture probabilities vary among animals. Biometrika 65(3):625-633.

Swor1: Chao, A. and C.-W. Lin. 2012. Nonparametric lower bounds for species richness and shared species richness under sampling without replacement. Biometrics 68:912-921.

iChao1: Chiu, C-H, Wang, Y-T, Walther, BA, and A Chao. 2014. An impro.ved nonparametric lower bound of species richness via a modified Good-Turing frequency formula. Biometrics 70(3):671-682.

clench: Clench, H. 1979. How to make regional lists of butterflies: Some thoughts. Journal of the Lepidopterists' Society 33(4):216-231

Examples

data(osa.second.growth)
f <- expand.freqs(osa.second.growth)

ace.est <- ACE(f)
chao1.est <- Chao1(f)
jack1.est <- jack1(f)
jack2.est <- jack2(f)
swor1.est <- Swor1(f, 20000)
ichao1.est <- iChao1(f)
clench.est <- Clench(f, num.reps = 50)

f0.est <- cbind(
  ACE = ace.est["f0"],
  Chao1 = chao1.est["f0"],
  jack1 = jack1.est["f0"],
  jack2 = jack2.est["f0"],
  Swor1 = swor1.est["f0"],
  iChao1 = ichao1.est["f0"],
  clench = clench.est["f0"]
)
f0.est

Bootstrap Assemblage of Species

Description

Create bootstrap assemblage of species.

Usage

bootstrap.assemblage(f, f0.func, n.boot = 500, ...)

Arguments

f

a vector of species frequencies where f[i] is the number of species represented by only i samples.
f0.func

function calculating the unobserved number of species (f0).
n.boot

number of bootstrap replicates.
...

other arguments to f0.func.

Value

a list of bootstrap replicates of species frequencies.

Author(s)

Eric Archer [email protected]

References

Chao, A., N.J. Gotelli, T.C. Hsieh, E.L. Sander, K.H. Ma, R.K. Colwell, and A.M. Ellison. 2014. Rarefaction and extrapolation with Hill numbers: a framework for sampling and estimation in species diversity studies. Ecological Monographs 84(1):45-67.

Discovery Curve

Description

Calculate the components of a species discovery curve.

Usage

discovery.curve(f, f0.func, max.x = sum(f * 1:length(f)), n.pts = 100,
  ci = 0.95, ...)

Arguments

f

a vector of species frequencies where f[i] is the number of species represented by only i samples.
f0.func

function to use to calculate f0.
max.x

the maximum number of samples to calculate the curve for. Defaults to the sample size of f.
n.pts

number of points between 0 and max.x to estimate.
ci

size of the confidence interval (0.5:1).
...

other arguments to f0.func.

Value

a list with:

f.stats

a named vector from f0.func.
s.ind

a matrix of S.ind estimates for each value of m along with the standard deviation of S.ind.
s.ind.ci

a matrix of the upper and lower confidence intervals of S.ind.
ci.poly

a matrix of points describing the ci polygon.
rarefact.line

a matrix of points defining the rarefaction line (<= S.obs).
extrap.line

a matrix of points defining the extrapolation line (> S.obs).

Author(s)

Eric Archer [email protected]

References

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

See Also

plot.discovery.curve

Examples

data(osa.old.growth)
f <- expand.freqs(osa.old.growth)
d <- discovery.curve(f, f0.func = Chao1, max.x = 1200)
plot(d)

Expand Frequency Matrix

Description

Expand a matrix or data.frame of species frequencies to full vector.

Usage

expand.freqs(freq.mat)

Arguments

freq.mat

a two column matrix or data.frame where the first column is the number of samples, and the second column is the number of species represented by with that many samples.

Value

a vector(f) of species frequencies where each element (f[i]) is the number of species represented by only i samples.

Author(s)

Eric Archer [email protected]

Examples

data(osa.old.growth)
f <- expand.freqs(osa.old.growth)
f

Expected Number of Species

Description

Calculate the expected number of species for a given sample size.

Usage

expected.num.species(m, f, f0.func, ...)

Arguments

m

number of samples.
f

a vector of species frequencies where f[i] is the number of species represented by only i samples.
f0.func

a function that computes the number of unobserved species (f0).
...

other arguments to f0.func.

Value

a vector or matrix (depending on whether m is a scalar or vector, respectively) of the estimated number of species (s.ind) seen in m samples, and the standard deviation (sd.s.ind).

Author(s)

Eric Archer [email protected]

References

Eqns 4, 5, 9, and 10 in Colwell, R.K., A. Chao, N.J. Gotelli, S.-Y. Lin, C.X. Mao, R.L. Chazdon, and J.T. Longino. 2012. Models and estimators linking individual-based and sample-based rarefaction, extrapolation and comparison of assemblages. Journal of Plant Ecology 5(1):3-21.

Examples

data(osa.old.growth)
f <- expand.freqs(osa.old.growth)
expected.num.species(60, f = f, f0.func = Chao1)

expected.num.species(c(60, 70, 75), f = f, f0.func = Chao1)

Frequency Vector Statistics

Description

Number of observed species and samples in species frequency vector.

Usage

f.stats(f)

Arguments

f

a vector of species frequencies where f[i] is the number of species represented by only i samples.

Value

a vector of the number of observed species (s.obs), and the total number of samples (n).

Author(s)

Eric Archer [email protected]

Examples

data(osa.second.growth)
f <- expand.freqs(osa.second.growth)
f.stats(f)

Number of Samples Required

Description

Calculate the additional number of samples to required to observe a given proportion of the total number of species.

Usage

num.samples.required(g, f, f0.func, ...)

Arguments

g

propotion of total number of species.
f

a vector of species frequencies where f[i] is the number of species represented by only i samples.
f0.func

a function that computes the number of unobserved species (f0).
...

other arguments to f0.func.

Value

a vector containing of the estimated additional number of samples (m.g) required to observe g percent of the total number of species.

Author(s)

Eric Archer [email protected]

References

Eqn 12 in Chao, A., R.K. Colwell, C.-W. Lin, and N.J. Gotelli. 2009. Sufficient sampling for asymptotic minimum species richness estimators. Ecology 90(4):1125-1133.
Eqn 11 in Colwell, R.K., A. Chao, N.J. Gotelli, S.-Y. Lin, C.X. Mao, R.L. Chazdon, and J.T. Longino. 2012. Models and estimators linking individual-based and sample-based rarefaction, extrapolation and comparison of assemblages. Journal of Plant Ecology 5(1):3-21.

Examples

data(osa.old.growth)
f <- expand.freqs(osa.old.growth)
num.samples.required(0.6, f = f, f0.func = Chao1)

Osa beetle species counts

Description

Matrices of the number of beetle species (fi) occuring i times in a survey.

Usage

data(osa.old.growth)
data(osa.second.growth)

References

Janzen DH (1973) Sweep samples of tropical foliage insects: effects of seasons, vegetation types, elevation, time of day, and insularity. Ecology 54:687-708.
Janzen DH (1973) Sweep samples of tropical foliage insects: description of study sites, with data on species abundances and size distributions. Ecology 54:659-86.

Plot a Discovery Curve

Description

Plot a species discovery curve.

Usage

## S3 method for class 'discovery.curve'
plot(x, col = "darksalmon", lwd = 2,
  xlab = "# Samples", ylab = "n", add = FALSE, ...)

Arguments

x

result of a call to discovery.curve.
col

color of confidence interval polygon and line denoting s.est.
lwd

line widths.
xlab, ylab

labels of x and y axes. Only used if add = FALSE.
add

logical. If TRUE, polygon and lines are added to the current plot.
...

other arguments passed to plot (ignored).

Author(s)

Eric Archer [email protected]

References

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

See Also

discovery.curve

Examples

data(osa.old.growth)
f <- expand.freqs(osa.old.growth)
d <- discovery.curve(f, f0.func = Chao1, max.x = 1200)
plot(d)

Rarefaction Overlap

Description

Calculate the percent of overlap between two species estimate distributions where the larger sample size has been rarefied to match the smaller sample size.

Usage

rarefaction.overlap(x, y, f0.func, n.rare = NULL, ...)

Arguments

x, y

two vectors of species frequencies where the i-th element is the number of species represented by only i samples.
f0.func

function to use to calculate f0. Can be Chao1, ACE, jack1, jack2, iChao1, or Swor1.
n.rare

sample size to rarefy both populations to. Must be <= the minimum sample size. If NULL, the minimum sample size is used.
...

other arguments to f0.func.

Details

Calculates the expected number of species and the standard deviation for the smaller sample size of x and y using the frequency distributions of each. The function then fits a gamma distribution to each of these estimates, and returns the percent of overlap as the integral of the mininum value of the PDF for the two distributions. Integration takes place from 0 to the largest quantile representing 0.99999 of either distribution.

Value

a vector with the percent of overlap between the two distributions, the sample size, and species estimates for the x and y vectors.

Author(s)

Eric Archer [email protected]

References

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

See Also

discovery.curve

Examples

data(osa.old.growth)
data(osa.second.growth)
x <- expand.freqs(osa.old.growth)
y <- expand.freqs(osa.second.growth)
rarefaction.overlap(x, y, Chao1)

Create Vector of Species Frequencies

Description

Create vector of species frequencies from vector of sample frequencies.

Usage

sample.to.species.freq(x, min.f = NULL)

Arguments

x

a vector where x[i] is of the number of samples in the i-th species.
min.f

minimum size of return vector. Return vector is zero-padded up to this length if it would normally be shorter.

Value

a vector(f) of species frequencies where f[i] is the number of species represented by only i samples.

Author(s)

Eric Archer [email protected]

See Also

species.to.sample.freq

Examples

x <- sample(1:20, 20, rep = TRUE)
f <- sample.to.species.freq(x)
print(x)
print(f)

Create Vector of Sample Frequencies

Description

Create vector of sample frequencies from vector of species frequencies.

Usage

species.to.sample.freq(f)

Arguments

f

a vector of species frequencies where f[i] is the number of species represented by only i samples.

Value

a vector(x) where x[i] is of the number of samples in the i-th species.

Author(s)

Eric Archer [email protected]

See Also

sample.to.species.freq

Examples

data(osa.old.growth)
f <- expand.freqs(osa.old.growth)
x <- species.to.sample.freq(f)
print(f)
print(x)