Fit a SAD given diversity and a distributional assumption

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

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

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.

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.

See also

uniroot, MeanRarity

Examples

#works
fit_SAD(distr = "gamma") #works
#> $distribution_info
#>       distribution   fitted parameter 
#>            "gamma" "3.86289520314416" 
#> 
#> $community_info
#>     richness Hill-Shannon Hill-Simpson 
#>     50.00000     44.29982     40.00000 
#> 
#> $rel_abundances
#>  [1] 0.050977208 0.043067059 0.039210234 0.036585333 0.034570836 0.032923087
#>  [7] 0.031520640 0.030293970 0.029199456 0.028207877 0.027298671 0.026456798
#> [13] 0.025670906 0.024932204 0.024233734 0.023569880 0.022936036 0.022328368
#> [19] 0.021743638 0.021179080 0.020632300 0.020101202 0.019583933 0.019078832
#> [25] 0.018584395 0.018099242 0.017622091 0.017151738 0.016687030 0.016226850
#> [31] 0.015770097 0.015315667 0.014862432 0.014409215 0.013954769 0.013497736
#> [37] 0.013036613 0.012569693 0.012094992 0.011610149 0.011112276 0.010597731
#> [43] 0.010061772 0.009497971 0.008897183 0.008245572 0.007520342 0.006678887
#> [49] 0.005622419 0.003971859
#> 
fit_SAD(distr = "lnorm", rich = 50, simpson = 2) #works
#> Warning: Rarest species has relative abundance  4.38248906502601e-08 . 
#> Consider implied community size.
#> $distribution_info
#>       distribution   fitted parameter 
#>            "lnorm" "3.56144818681073" 
#> 
#> $community_info
#>     richness Hill-Shannon Hill-Simpson 
#>    50.000000     3.294258     2.000000 
#> 
#> $rel_abundances
#>  [1] 6.888518e-01 1.409222e-01 6.082007e-02 3.330848e-02 2.059171e-02
#>  [6] 1.370931e-02 9.596922e-03 6.966149e-03 5.196934e-03 3.960780e-03
#> [11] 3.070641e-03 2.413851e-03 1.919412e-03 1.540891e-03 1.246962e-03
#> [16] 1.015930e-03 8.324241e-04 6.853386e-04 5.665088e-04 4.698410e-04
#> [21] 3.907249e-04 3.256299e-04 2.718228e-04 2.271666e-04 1.899756e-04
#> [26] 1.589091e-04 1.328930e-04 1.110608e-04 9.270910e-05 7.726371e-05
#> [31] 6.425335e-05 5.328930e-05 4.404955e-05 3.626620e-05 2.971550e-05
#> [36] 2.420993e-05 1.959182e-05 1.572818e-05 1.250651e-05 9.831452e-06
#> [41] 7.621947e-06 5.808974e-06 4.333651e-06 3.145681e-06 2.202070e-06
#> [46] 1.466069e-06 9.063414e-07 4.963634e-07 2.142236e-07 4.382489e-08
#> 
fit_SAD(distr = "gamma", rich = 50, simpson = 2) #works
#> Warning: Rarest species has relative abundance  2.69995080442289e-83 . 
#> Consider implied community size.
#> $distribution_info
#>         distribution     fitted parameter 
#>              "gamma" "0.0242907270521766" 
#> 
#> $community_info
#>     richness Hill-Shannon Hill-Simpson 
#>    50.000000     2.694709     2.000000 
#> 
#> $rel_abundances
#>  [1] 6.729581e-01 2.005096e-01 7.607360e-02 3.036103e-02 1.219451e-02
#>  [6] 4.850669e-03 1.897665e-03 7.276530e-04 2.729132e-04 9.996717e-05
#> [11] 3.571346e-05 1.242684e-05 4.205614e-06 1.382235e-06 4.404637e-07
#> [16] 1.358457e-07 4.047197e-08 1.162316e-08 3.210401e-09 8.506808e-10
#> [21] 2.156473e-10 5.213926e-11 1.198286e-11 2.607946e-12 5.352530e-13
#> [26] 1.031105e-13 1.854538e-14 3.095739e-15 4.763667e-16 6.704994e-17
#> [31] 8.555806e-18 9.795856e-19 9.942777e-20 8.820577e-21 6.725028e-22
#> [36] 4.318346e-23 2.278772e-24 9.587660e-26 3.096926e-27 7.318875e-29
#> [41] 1.188639e-30 1.220237e-32 7.057474e-35 1.950500e-37 2.010861e-40
#> [46] 5.195004e-44 1.668512e-48 1.608919e-54 1.184325e-63 2.699951e-83
#> 
fit_SAD(distr = "gamma", rich = 10, simpson = 6)
#> $distribution_info
#>       distribution   fitted parameter 
#>            "gamma" "1.23540540463064" 
#> 
#> $community_info
#>     richness Hill-Shannon Hill-Simpson 
#>    10.000000     7.273506     6.000000 
#> 
#> $rel_abundances
#>  [1] 0.286412672 0.188593616 0.142105917 0.110870935 0.087043180 0.067550896
#>  [7] 0.050836952 0.035950731 0.022158130 0.008476971
#> 

if (FALSE) {
fit_SAD(distr = "nonsense")  #returns error
fit_SAD(distr = "lnorm", rich = 50, simpson = 90) #returns error
}