sim_sad: Simulate species abundance distributions

View source: R/Sim_Community.R

sim_sadR Documentation

Simulate species abundance distributions


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.


  s_pool = NULL,
  n_sim = NULL,
  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,
  seed = NULL



Number of species in the pool (integer)


Number of individuals in the simulated community (integer)


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.


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.


Should the simulation constrain the number of species in the simulated local community? (logical)


Should the function remove species with abundance zero from the output? (logical)


Integer. Any integer passed to set.seed for reproducibility.


The function sim_sad was built using code of the function sads::rsad from the R package sads. However, in contrast to sads::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 sads::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
sads::rbs Mac-Arthur's brokenstick N S
stats: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
sads::rmzsm Metacommunity zero-sum multinomial J theta
stats::rnbinom Negative binomial distribution size prob mu
sads::rpareto Pareto distribution shape scale
sads::rpoilog Poisson-lognormal distribution mu sigma cv_abund
sads::rpower Power discrete distributions s
sads::rpowbend Puyeo's Power-bend discrete distribution s omega
stats::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 = NULL, 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 = NULL, 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)

MoBiodiv/MoBspatial documentation built on May 22, 2024, 7:44 p.m.