sim_sad: Simulate species abundance distributions
In mobsim: Spatial Simulation and Scale-Dependent Analysis of Biodiversity Changes

Description Usage Arguments Details Value Author(s) Examples

Simulate species abundance distribution (SAD) of a local community with user-defined number of species and relative abundance distribution in the pool, and user-defined number of individuals in the simulated local community.

sim_sad(
  s_pool,
  n_sim,
  sad_type = c("lnorm", "bs", "gamma", "geom", "ls", "mzsm", "nbinom", "pareto",
    "poilog", "power", "powbend", "weibull"),
  sad_coef = list(cv_abund = 1),
  fix_s_sim = FALSE,
  drop_zeros = TRUE
)

`s_pool`	Number of species in the pool (integer)
`n_sim`	Number of individuals in the simulated community (integer)
`sad_type`	Root name of the species abundance distribution model of the species pool (character) - e.g., "lnorm" for the lognormal distribution (`rlnorm`); "geom" for the geometric distribution (`rgeom`), or "ls" for Fisher's log-series distribution (`rls`). See the table in Details below, or `rsad` for all SAD model options.
`sad_coef`	List with named arguments to be passed to the distribution function defined by the argument `sad_type`. An overview of parameter names is given in the table below. In `mobsim` the log-normal and the Poisson log-normal distributions can alternatively be parameterized by the coefficient of variation (cv) of the relative abundances in the species pool. Accordingly, `cv_abund` is the standard deviation of abundances divided by the mean abundance (no. of individuals / no. of species). `cv_abund` is thus negatively correlated with the evenness of the species abundance distribution. Please note that the parameters mu and sigma are not equal to the mean and standard deviation of the log-normal distribution.
`fix_s_sim`	Should the simulation constrain the number of species in the simulated local community? (logical)
`drop_zeros`	Should the function remove species with abundance zero from the output? (logical)

The function sim_sad was built using code of the function rsad from the R package sads. However, in contrast to rsad, the function sim_sad allows to define the number of individuals in the simulated local community. This is implemented by converting the abundance distribution simulated based on rsad into a relative abundance distribution. This relative abundance distribution is considered as the species pool for the local community. In a second step the required no. of individuals (n_sim) is sampled (with replacement) from this relative abundance distribution.

Please note that this might effect the interpretation of the parameters of the underlying statistical distribution, e.g. the mean abundance will always be n_sim/s_pool irrespective of the settings of sad_coef.

When fix_s_sim = FALSE the species number in the local community might deviate from s_pool due to stochastic sampling. When fix_s_sim = TRUE the local number of species will equal s_pool, but this constraint can result in systematic biases from the theoretical distribution parameters. Generally, with fix_s_sim = TRUE additional very rare species will be added to the community, while the abundance of the most common ones is reduced to keep the defined number of individuals.

Here is an overview of all available models (sad_type) and their respective coefficients (sad_coef). Further information is provided by the documentation of the specific functions that can be accesses by the links. Please note that the coefficient cv_abund for the log-normal and Poisson log-normal model are only available within mobsim.

SAD function	Distribution name	coef #1	coef #2	coef #3
`rbs`	Mac-Arthur's brokenstick	N	S
`rgamma`	Gamma distribution	shape	rate	scale
`rgeom`	Geometric distribution	prob
`rlnorm`	Log-normal distributions	meanlog	sdlog	cv_abund
`rls`	Fisher's log-series distribution	N	alpha
`rmzsm`	Metacommunity zero-sum multinomial	J	theta
`rnbinom`	Negative binomial distribution	size	prob	mu
`rpareto`	Pareto distribution	shape	scale
`rpoilog`	Poisson-lognormal distribution	mu	sigma	cv_abund
`rpower`	Power discrete distributions	s
`rpowbend`	Puyeo's Power-bend discrete distribution	s	omega
`rweibull`	Weibull distribution	shape	scale

Object of class sad, which contains a named integer vector with species abundances

Felix May

#Simulate log-normal species abundance distribution
sad_lnorm1 <- sim_sad(s_pool = 100, n_sim = 10000, sad_type = "lnorm",
                      sad_coef = list("meanlog" = 5, "sdlog" = 0.5))
plot(sad_lnorm1, method = "octave")
plot(sad_lnorm1, method = "rank")

# Alternative parameterization of the log-normal distribution
sad_lnorm2 <- sim_sad(s_pool = 100, n_sim = 10000, sad_type = "lnorm",
                      sad_coef = list("cv_abund" = 0.5))
plot(sad_lnorm2, method = "octave")

# Fix species richness in the simulation by adding rare species
sad_lnorm3a <- sim_sad(s_pool = 500, n_sim = 10000, sad_type = "lnorm",
                       sad_coef = list("cv_abund" = 5), fix_s_sim = TRUE)
sad_lnorm3b <- sim_sad(s_pool = 500, n_sim = 10000, sad_type = "lnorm",
                       sad_coef = list("cv_abund" = 5))

plot(sad_lnorm3a, method = "rank")
points(1:length(sad_lnorm3b), sad_lnorm3b, type = "b", col = 2)
legend("topright", c("fix_s_sim = TRUE","fix_s_sim = FALSE"),
       col = 1:2, pch = 1)

# Different important SAD models

# Fisher's log-series
sad_logseries <- sim_sad(s_pool = NULL, n_sim = 10000, sad_type = "ls",
                         sad_coef = list("N" = 1e5, "alpha" = 20))

# Poisson log-normal
sad_poilog <- sim_sad(s_pool = 100, n_sim = 10000, sad_type = "poilog",
                      sad_coef = list("mu" = 5, "sig" = 0.5))

# Mac-Arthur's broken stick
sad_broken_stick <- sim_sad(s_pool = NULL, n_sim = 10000, sad_type = "bs",
                            sad_coef = list("N" = 1e5, "S" = 100))

# Plot all SADs together as rank-abundance curves
plot(sad_logseries, method = "rank")
lines(1:length(sad_lnorm2), sad_lnorm2, type = "b", col = 2)
lines(1:length(sad_poilog), sad_poilog, type = "b", col = 3)
lines(1:length(sad_broken_stick), sad_broken_stick, type = "b", col = 4)
legend("topright", c("Log-series","Log-normal","Poisson log-normal","Broken stick"),
       col = 1:4, pch = 1)