mikeroswell / meanrarity

Repo for development of MeanRarity R package

MeanRarity

You can install the R package MeanRarity with the following command:

devtools::install_github("mikeroswell/MeanRarity")

This R package allows estimating and visualizing Hill diversity (aka "Hill numbers") in terms of the average species "rarity."

The average species rarity may be simpler to interpret than a transformed, generalized entropy. The rarity parameterization clarifies the role of the scaling exponent, and this R package provides illustration tools to visualize that scaling concretely. Furthermore, this framework may provide an entry point for developing and testing diversity estimators and their related interval estimates (e.g. confidence intervals); this package contains novel tools to simulate species abundance distributions that should streamline that process.

Three key functions

rarity() computes Hill diversity of a sample, parameterized in terms of the mean rarity.

rarity_plot() makes balance plots to visualize mean rarity.

fit_SAD() simulates a species abundance distribution with known richness, Hill-Simpson diversity, and a distributional assumption (lognormal or gamma).

Details

rarity(x, l) is equivalent to vegan::renyi(x, scale = 1-l, hill = T). Re-parameterizing Hill diversity in terms of species rarity can provide conceptual clarity.

"Balance plots" called with rarity_plot() illustrate the computation in rarity().

fit_SAD() is a potentially novel way to simulate abundance distributions that always gives precisely the same relative abundances for a given set of parameters, and may be a helpful tool for exploring the behavior of diversity metrics under different sampling scenarios.

Vignettes

We are working on vignettes now. Currently Estimating_Mean_Rarity provides code to make the figures in Roswell et al. 2021 Oikos https://doi.org/10.1111/oik.07202, Gods_estimator explores a playful extension of the tools in this package, and Using_MeanRarity is a more traditional, "user's guide" -type vignette.

meanrarity's Issues

fix pkgdown YAML header to get figures to render properly

Right now vignette figures look funny in html rendering (mainly the balance plots) with pkgdown.

Numerical instability with negative ell

rarity(c(10,1),-1e4) returns Inf, should be about 1.1

Include option for non-integer abundance in rarity plots

Right now, the internal function MeanRarity:::fancy_rep requires integer abundances, and the rarity plot entirely depends on the output for this. Probably needs a separate pathway to construct non-integer abundance version.

Get ratioScales in Using_MeanRarity MS

deal with perfectly even communities in fit_SAD with gamma

Looks like for gamma distribution, if Hill-Simpson = richness, fit_SAD throws an error. Should give a more specific error/warning.

Parameterize functions with "q" as well as "l"

Since many users will be familiar with the "q" parameterization used in vegan, iNEXT, etc., might be good to have an option (not default) to use "q" instead of "l". Will need good warning messages, implement across all main functions.

refactor sample_funs.R, checkplot_inf.R to avoid importing `furrr` and `future`

Skeleton code from Wickham and Bryan's R Packages book:

You need the suggested package for this function

my_fun <- function(a, b) {
if (!requireNamespace("pkg", quietly = TRUE)) {
stop("Package "pkg" needed for this function to work. Please install it.",
call. = FALSE)
}
}

There's a fallback method if the package isn't available

my_fun <- function(a, b) {
if (requireNamespace("pkg", quietly = TRUE)) {
pkg::f()
} else {
g()
}
}

add `na.rm = TRUE` defaul to `rarity()`

rarity(c(1,2,3, NA), 1) returns NA with an inscrutable warning, should just return 3 (perhaps with warning about NA values) by default.

Is it possible to remove rdpack from package dependencies?

Rdpack seems very helpful for package development, but would be nice if everyone building the package didn't have to install it. Is there a way to get the functionality for citations, anything else it is used for, without requiring another dependency?