get_mob_stats: Carry out biodiversity metric comparisons between groups.

In MoBiodiv/mobr: Measurement of Biodiversity

Carry out biodiversity metric comparisons between groups.

Description

This function can compute a range of biodiversity metrics, their uncertainty, and carries out a permutation test to examine if groups differ in a particular metric more than would be expected due to random chance.

Usage

get_mob_stats(
  mob_in,
  group_var,
  index = c("N", "S", "S_n", "S_PIE"),
  effort_samples = NULL,
  effort_min = 5,
  extrapolate = TRUE,
  return_NA = FALSE,
  rare_thres = 0.05,
  scales = c("alpha", "gamma", "beta"),
  PIE_replace = FALSE,
  C_target_gamma = NA,
  n_perm = 199,
  cl = NULL,
  ci = TRUE,
  ci_cent_stat = "median",
  ci_algo = "boot",
  ci_n_boot = 1000,
  quiet_mode = TRUE,
  ...
)

Arguments

mob_in	an object of class mob_in created by make_mob_in()
group_var	String that specifies which variable in mob_in$env the data should be grouped by.
index	The calculated biodiversity indices. The options are N ... Number of individuals (total abundance) S ... Number of species S_n ... Rarefied or extrapolated number of species for n individuals S_C ... Estimate species richness of a given level of coverage by C_target_gamma S_asymp ... Estimated asymptotic species richness f_0 ... Estimated number of undetected species pct_rare ... The percent of rare species as defined by rare_thres PIE ... Hurlbert's PIE (Probability of Interspecific Encounter) S_PIE ... Effective number of species based on PIE See Details for additional information on the biodiversity statistics.
effort_samples	An integer that specifies the standardized number of individuals used for the calculation of rarefied species richness at the alpha-scale. It must be a single integer. The default value of NULL will result in the using the minimum number of individuals found across the samples is used, when this is not smaller than effort_min.
effort_min	The minimum number of individuals considered for the calculation of rarefied richness (Default value of 5). Samples with less individuals then effort_min are excluded from the analysis with a warning. Accordingly, when effort_samples is set by the user it has to be higher than effort_min.
extrapolate	Boolean which specifies if richness should be extrapolated when effort is larger than the number of individuals using the chao1 method (Chao 1984, 1987). Defaults to TRUE.
return_NA	Boolean in which the rarefaction function returns the observed S when effort is larger than the number of individuals. If set to TRUE then NA is returned. Note that this argument is only relevant when extrapolate = FALSE.
rare_thres	The threshold that determines how the metric pct_rare is computed. It can range from (0, 1] and defaults to 0.05 which specifies that any species with less than or equal to 5 abundance in a sample is considered rare. It can also be specified as "N/S" which results in using average abundance as the threshold which McGill (2011) found to have the best small sample behavior.
scales	The scales to compute the diversity indices for: alpha ... for each row of the site x species community matrix gamma ... for the entire site x species community matrix beta ... the ratio of diversity at the gamma and alpha scales. Defaults to all three scales: c('alpha', 'gamma', 'beta')
PIE_replace	Used for PIE and SPIE. If TRUE, sampling with replacement is used. Otherwise, sampling without replacement (default).
C_target_gamma	When computing coverage based richness (S_C) then this argument can be used to specify the coverage to be used for the gamma scale richness estimate. This defaults to NA in which case the target cover is computed by calc_C_target (i.e., the largest allowable sample size).
n_perm	number of iterations to run for null tests, defaults to 1000.
cl	A cluster object created by makeCluster, or an integer to indicate number of child-processes (integer values are ignored on Windows) for parallel evaluations (see Details on performance). It can also be "future" to use a future backend (see Details), NULL (default) refers to sequential evaluation.
ci	boolean, if TRUE then confidence intervals are calculated. Defaults to TRUE.
ci_cent_stat	a string that is either 'mean' or 'median' which specifies the measure of central tendency. Defaults to 'median'.
ci_algo	can be either 'boot' or 'loo' for bootstrap or leave-one-out methods respectively. Default value is 'boot'.
quiet_mode	boolean, defaults to TRUE in which case warnings from the diversity calculations are not returned. These are typically generated when calculating the metric SPIE which is undefined when all species are singletons.
...	additional arguments that can be passed to calc_div

Details

This function is partially a wrapper for the functions calc_comm_div or calc_comm_div_ci that makes group comparisons easier to implement.

See calc_comm_div for more details on the biodiversity indices.

Group comparison metric and test

For each metric group comparison the function computes D_bar: the average absolute difference between the groups. At the alpha scale the indices are averaged first before computing D_bar.

Permutation tests are carried out for testing differences of the biodiversity statistics among the groups (Legendre & Legendre 1998). This is accomplished by using D_bar as the test statistic and random shuffling the group label across the samples. The p-value indicates how many of the permutations result in a D_bar as large as the observed D_bar value.

Value

A list of class mob_stats that contains two objects: 1) comm_div a data.frame of each diversity metrics for each group at each scale specified, and 2) gorup_tests a data.frame of the average difference between groups in their diversity metric (D_bar) with an associated p-value derived from the permutation test.

References

Chao, A. 1984. Nonparametric Estimation of the Number of Classes in a Population. Scandinavian Journal of Statistics 11:265–270.

Chao, A. 1987. Estimating the population size for capture-recapture data with unequal catchability. Biometrics, 43, 783-791.

Gotelli, N. J., and R. K. Colwell. 2001. Quantifying biodiversity: procedures and pitfalls in the measurement and comparison of species richness. Ecology Letters 4:379–391.

Hurlbert, S. H. 1971. The nonconcept of species diversity: a critique and alternative parameters. Ecology 52:577–586.

Jost, L. 2007. Partitioning diversity into independent alpha and beta components. Ecology 88:2427–2439.

McGill, B. J. 2011. Species abundance distributions. Pages 105-122 Biological Diversity: Frontiers in Measurement and Assessment, eds. A.E. Magurran and B.J. McGill.

Whittaker, R. H. 1972. Evolution and measurement of species diversity. Taxon 21:213–251.

Examples

# tank community analysis
data(tank_comm)
data(tank_plot_attr)
tank_mob <- make_mob_in(tank_comm, tank_plot_attr)
tank_stats <- get_mob_stats(tank_mob, 'group', index = c('S', 'S_PIE', 'S_C'),
                            n_perm = 5, ci_n_boot = 5)
tank_stats    

MoBiodiv/mobr documentation built on June 9, 2025, 8:34 a.m.