getAlphaMetrics: Alpha diversity metrics

In BioTIMEr: Tools to Use and Explore the 'BioTIME' Database

Alpha diversity metrics

Description

Calculates a set of standard alpha diversity metrics

Usage

getAlphaMetrics(x, measure)

Arguments

x	(data.frame) BioTIME data in the format of the output of the resampling function. The resamp column is optional.
measure	(character) chosen currency defined by a single column name.

Details

The function getAlphaMetrics computes nine alpha diversity metrics for a given community data frame, where measure is a character input specifying the abundance or biomass field used for the calculations. For each row of the data frame with data, getAlphaMetrics calculates the following metrics:

- Species richness (S) as the total number of species in each year with currency > 0.

- Numerical abundance (N) as the total currency (sum) in each year (either total abundance or total biomass).

- Maximum Numerical abundance (maxN) as the highest currency value reported in each year.

- Shannon or Shannon–Weaver index is calculated as \sum_{i}p_{i}log_{b}p_{i}, where p_{i} is the proportional abundance of species i and b is the base of the logarithm (natural logarithms), while exponential Shannon is given by exp(Shannon).

- Simpson's index is calculated as 1-sum(p_{i}^{2}), while Inverse Simpson as 1/sum(p_{i}^{2}).

- McNaughton's Dominance is calculated as the sum of the pi of the two most abundant species.

- Probability of intraspecific encounter or PIE is calculated as \left(\frac{N}{N-1}\right)\left(1-\sum_{i=1}^{S}\pi_{i}^{2}\right).

Note that the input data frame needs to be in the format of the output of the gridding function and/or resampling functions, which includes keeping the default BioTIME data column names. If such columns are not found an error is issued and the computations are halted. There is an exception for the resamp column: the function runs even without it.

Value

Returns a data.frame with results for species richness (S), numerical abundance (N), maximum numerical abundance (maxN), Shannon Index (Shannon), Exponential Shannon (expShannon), Simpson's Index (Simpson), Inverse Simpson (InvSimpson), Probability of intraspecific encounter (PIE) and McNaughton's Dominance (DomMc) for each year and assemblageID.

Examples

  # Mean and sd values of the metrics for several resamplings
  gridding(BTsubset_meta, BTsubset_data) |>
    resampling(measure = "BIOMASS", resamps = 2) |>
    getAlphaMetrics(measure = "BIOMASS") |>
    dplyr::summarise(
       dplyr::across(
          .cols = !resamp, # FIXME
          .fns = c(mean = mean, sd = sd)),
       .by = c(assemblageID, YEAR)) |>
    tidyr::pivot_longer(
       col = dplyr::contains("_"),
       names_to = c("metric", "stat"),
       names_sep = "_",
       names_transform = as.factor) |>
    tidyr::pivot_wider(names_from = stat) |>
    head(10)

BioTIMEr documentation built on Feb. 10, 2026, 5:08 p.m.