Species abundance distribution (SAD) generators

Utilities to generate species abundance distributions (SADs) for a community of n_species and n_individuals.

In spesim, SADs are used to create a per-species abundance vector (named A, B, ...), after which individuals are placed in space.

Details

Most classic SADs are defined as a probability vector \(p_1,\ldots,p_S\) over species ranks, then sampled to integer counts via rmultinom(1, n_individuals, prob = p).

Some sampling-model SADs (e.g. Poisson–lognormal, Poisson–gamma) are implemented by first simulating latent rates and then drawing counts. Because spesim's downstream spatial simulation typically expects exactly n_individuals points, these generators rescale/adjust to sum exactly to n_individuals.

Models

generate_sad() supports (case-insensitive):

"fisher"

Fisher log-series with an explicit dominant species via generate_fisher_log_series().

"geometric"

Geometric series (niche pre-emption / Motomura).

"brokenstick"

Broken stick (MacArthur).

"zipf"

Zipf rank-abundance: \(p_i \propto i^{-a}\).

"zipf-mandelbrot"

Zipf–Mandelbrot: \(p_i \propto (i + q)^{-a}\).

"lognormal"

Lognormal weights + multinomial sampling.

"poisson-lognormal"

Poisson–lognormal sampling model (rates are lognormal; counts are Poisson).

"poisson-gamma"

Poisson–gamma sampling model (rates are Gamma; counts are Poisson). Closely related to negative-binomial mixtures.

"zsm"

Neutral-theory SAD helper. With theta only, this uses a theta-only Ewens sampler (Chinese restaurant) to control the rank–abundance curve. If an immigration probability \(m \in (0,1)\) is supplied, spesim uses a simple neutral death–birth with immigration heuristic (Moran style) to make the SAD more uneven as m decreases. This is a pragmatic SAD helper and is not a full neutral dynamics engine (spatial patterns are controlled separately by the point-process settings). Important notes: (1) The immigration-modulated model runs until convergence is detected (monitoring the abundance vector) or max_steps is reached. (2) The simulation may produce more or fewer species than n_species; the resulting list is truncated or padded with zeros, and the total number of individuals is adjusted to match n_individuals using a proportional allocation method, which avoids lumping tail-end abundances into a single species.

"custom"

User-supplied SAD via a numeric vector or a function (sad argument).