rsad {sads}R Documentation

Sampling from a species abundance distribution

Description

A given number of realizations of a probability distribution (species abundances in a community) is sampled with replacement by a Poisson or Negative Binomial process, or without replacement by a hypergeometric process.

Usage

rsad(S = NULL, frac, sad = c("bs","gamma","geom","lnorm","ls","mzsm","nbinom","pareto",
                             "poilog","power", "powbend", "volkov", "weibull"), 
                 coef, trunc=NaN, sampling=c("poisson", "nbinom", "hypergeometric"), 
                 k, zeroes=FALSE, ssize=1) 

Arguments

S

positive integer; number of species in the community, which is the number of random deviates generated by the probability distribution given by argument sad. Notice that for some distributions, the value of S is deduced from the coefficients, so this value is ignored (see details).

frac

single numeric 0 < frac <= 1; fraction of the community sampled. Usually the proportion of total number of individuals or of total area or volume sampled. Notice that assumptions of Poisson and binomial sampling are only valid for small values of frac (see Details).

sad

numeric; a vector of positive real numbers depicting abundances of species in a community or sample OR character; root name of community sad distribution - e.g., lnorm for the lognormal distribution rlnorm; geom for the geometric distribution rgeom or ls for the lognormal distribution ls.

coef

list with named arguments to be passed to the probability function defined by the argument sad.

trunc

The truncation point at which the random distribution defined in argument sad should be truncated; see rtrunc. The default value of NaN means that no truncation is performed.

sampling

character; if poisson the sampling process is Poisson (independent sampling of individuals with replacement); if nbinom negative binomial sampling is used to simulate aggregation of individuals in sampling units with replacement; finally, hypergeometric samples a fixed number of frac times the number of individuals in the simulated community, without replacement. Partial matching is allowed.

k

positive; size parameter for the sampling binomial negative. This parameter is ignored for other sampling techniques.

zeroes

logical; should zero values be included in the returned vector?

ssize

positive integer; sample size: number of draws taken from the community.

Details

This function simulates one or more random samples taken from a community with S species. The expected species abundances in the sampled community can (i) follow a probability distribution given by the argument sad or (ii) be a numeric vector provided by the user through this same argument. A fraction frac of the whole set of units that made up the community (usually individuals) is sampled. Hence the expected abundance in the sample of each species is frac*n, where n is the species' expected abundance in the community.

Three sampling processes can be simulated. Sampling with replacement can be done with Poisson (individuals are sampled independently) or negative binomial sampling (where individuals of each species are aggregated over sampling units). The "hypergeometric" sampling scheme draws frac * n individuals without replacement.

For Poisson and negative binomial schemes the species abundances in the sample are statistically independent. In general terms, these two sampling schemes takes a Poisson or negative binomial sampling with replacement of a vector of S realizations of a random variable, with the sampling intensity given by frac. The resulting values are realizations of a Poisson (or a Negative Binomial) random variable where the parameter that corresponds to the mean (=expected value of the variable) follows a probability distribution or the numeric vector given by the argument sad. Because these two sampling schemes assume replacement but the sampled community is finite, they are valid only when the fraction of the sampled community is small (frac<<1).

The "hypergeometric" scheme simulates a sample of a fixed total number of individuals from the community. Therefore, abundances of the species in the sample are interdependent (Connoly et al. 2009). Sampling is carried out with base::sample(..., replace = FALSE). This scheme samples without replacement a finite community and therefore provides valid results for any value of frac.

For the broken-stick, logseries, MZSM and Volkov distributions, the expected value of S is deduced from the coefficients provided in the argument coef; thus, the value of the parameter S is ignored and may be left blank. The expressions for the number of species in each case are:

* Broken-stick: coefficient S * Log-series: alpha log(1 + N/alpha) * MZSM: sum_x=1^J theta/x (1 - x/J)^(theta - 1) * Volkov: sum of the unnormalized PDF from 1 to J, see dvolkov

Value

if ssize=1 a vector of (zero truncated) abundances in the sample; if ssize>1 a data frame with sample identification, species identification, and (zero truncated) abundances.

Author(s)

Paulo I. Prado prado@ib.usp.br and Andre Chalom.

References

Pielou, E.C. 1977. Mathematical Ecology. New York: John Wiley and Sons.

Green, J. and Plotkin, J.B. 2007 A statistical theory for sampling species abundances. Ecology Letters 10:1037–1045

Connolly, S.R., Dornelas, M., Bellwood, D.R. and Hughes, T.P. 2009. Testing species abundance models: a new bootstrap approach applied to Indo-Pacific coral reefs. Ecology, 90(11): 3138–3149.

See Also

dpoix, dpoig and dpoilog for examples of compound Poisson probability distributions like those simulated by rsad.

Examples

##A Poisson sample from a community with a lognormal sad
samp2 <- rsad(S = 100, frac=0.1, sad="lnorm", coef=list(meanlog=5, sdlog=2))
## Preston plot
plot(octav(samp2))
## Once this is a Poisson sample of a lognormal community, the abundances
## in the sample should follow a Poisson-lognormal distribution.
## Adds line of theoretical Poisson-lognormal with
## mu=meanlog+log(frac) and sigma=sdlog)
## Predicted by the theoretical Poisson-lognormal truncated at zero
samp2.pred <- octavpred(samp2, sad="poilog", coef= list(mu=5+log(0.1), sig=2), trunc=0)
## Adding the line in the Preston plot
lines(samp2.pred)

[Package sads version 0.6.3 Index]