fit_SAD: Fit a SAD given diversity and a distributional assumption

In mikeroswell/MeanRarity: Hill Diversity Estimation and Visualization

Fit a SAD given diversity and a distributional assumption

Description

Takes a true richness, an inverse-Simpson diversity, and a distributional assumption. Fits an optimal SAD given these constraints using stats::uniroot.

Usage

fit_SAD(
  rich = 50,
  simpson = 40,
  distr = "lnorm",
  int_lwr = 1e-04,
  int_uppr = 100,
  totAb = 1e+07,
  ...
)

Arguments

rich	Total number of species in the SAD, an integer.
simpson	Hill-Simpson diversity of the SAD, a real number in [1,rich].
distr	Name of the distribution ("lnorm" or "gamma").
int_lwr	Lower bound of search space for uniroot(); default is a small number close to 0 to deal with potential boundary issues for stats::uniroot (a scalar).
int_uppr	Upper bound of search space for uniroot (scalar).
totAb	Integer, assumed total # of individuals in hypothetical community. See details.
...	pass arguments to other

Details

The way the SAD is fit, we assume infinite abundance, but finite and fixed diversity. In particular, richness is fixed. The parametric fits use continuous distributions. Species abundances are given at evenly spaced intervals along those continuous distributions. The distributions are described by a shape parameter (the scale parameter of the lognormal is fixed), and the value of that parameter is chosen such that the relative abundances assigned to the species give the target Hill-Simpson diversity.

The parameter totAb is not implemented in the current version of fit_SAD(), as the function simulates SADs with infinite abundance. However, it defaults to 1e7, enabling a warning if the rarest species has relative abundance ⁠< (1/totAb)⁠. This can serve as a reality check as uneven SADs may be fit with species well rarer than 1 in 10 Million. Such SADs may be inappropriate test cases for non-microbial ecologists.

Value

A list with three elements.

distribution_info Contains the name of the distribution and the fitted shape parameter value.

community_info gives richness, Hill-Shannon, and Hill=Simpson diversity of the SAD.

rel_abundances is a vector of relative abundances for each species in SAD.

See Also

uniroot, MeanRarity

Examples

#works
fit_SAD(distr = "gamma") #works
fit_SAD(distr = "lnorm", rich = 50, simpson = 2) #works
fit_SAD(distr = "gamma", rich = 50, simpson = 2) #works
fit_SAD(distr = "gamma", rich = 10, simpson = 6)

## Not run: 
fit_SAD(distr = "nonsense")  #returns error
fit_SAD(distr = "lnorm", rich = 50, simpson = 90) #returns error

## End(Not run)

mikeroswell/MeanRarity documentation built on May 5, 2024, 4:50 p.m.