Uncertainty in Biodiversity Indicators

Introduction 🛡️

Quantifying uncertainty is crucial for robust biodiversity assessments. The b3gbi package provides a flexible and powerful way to calculate confidence intervals (CIs) for biodiversity indicators using bootstrapping methods, leveraging the dubicube package for robust cube-level resampling.

dubicube is developed alongside b3gbi within the B-Cubed project and is installed from R-universe:

install.packages("dubicube",
                 repos = c("https://b-cubed-eu.r-universe.dev",
                           "https://cloud.r-project.org"))

If dubicube is not installed, add_ci() falls back to indicator-level bootstrapping (see below) and tells you so.

To maintain a clean and efficient workflow, uncertainty calculation is decoupled from the initial indicator calculation. This “two-step” process allows users to first explore their data and indicators quickly, and then perform computationally intensive bootstrapping only when needed.

The Two-Step Workflow

The standard workflow for adding uncertainty to an indicator is as follows:

1. Calculate the Indicator: Use a time-series wrapper function (e.g., total_occ_ts(), pielou_evenness_ts()).
2. Add Confidence Intervals: Pass the resulting indicator object to the add_ci() function.

library(b3gbi)

# 1. Process the cube
denmark_cube <- process_cube(system.file("extdata", 
                                         "denmark_mammals_cube_eqdgc.csv", 
                                         package = "b3gbi"))

# 2. Calculate a time series of total occurrences
# By default, CIs are NOT calculated during this step
occ_ts <- total_occ_ts(denmark_cube)

# 3. Add confidence intervals using add_ci()
# With dubicube installed, this uses cube-level bootstrapping by default
occ_ts_with_ci <- add_ci(occ_ts, num_bootstrap = 100) # Using 100 for speed in this example

# 4. Plot the result
plot(occ_ts_with_ci, title = "Total Occurrences with 95% CI")

Bootstrapping Levels

The add_ci() function supports two levels of bootstrapping, selectable via the bootstrap_level argument. The default, bootstrap_level = "auto", uses cube-level bootstrapping when dubicube is installed and indicator-level bootstrapping otherwise. The level that was used is stored in the ci_method element of the result and shown when it is printed.

Automatic Indicator Configuration

The add_ci() function automatically applies appropriate bootstrapping strategies based on the indicator type. This ensures statistically correct confidence intervals without requiring manual configuration:

• Group-Specific Bootstrapping: This method isolates resampling strictly within each grouping variable. For indicators like Total Occurrences (total_occ), which calculate a raw count per year, resampling only within that year provides mathematically correct variance without cross-contamination between years.

• Whole-Cube Bootstrapping: This method resamples the entire dataset at once. This is automatically applied to aggregate indicators (evenness, rarity, density metrics) as well as species-level indicators (spec_occ, spec_range). For species-level indicators, whole-cube resampling is computationally optimized to process thousands of species simultaneously in a single pass while correctly capturing changes in species composition during resampling.

• Bounded Indicators: Evenness metrics (pielou_evenness, williams_evenness) automatically use logit transformation to ensure confidence intervals remain within valid [0, 1] bounds.

These defaults are applied internally (at cube level), but can be overridden using boot_args or ci_args (see below) if needed.

Advanced Configuration

The add_ci() function provides several arguments for fine-tuning the CI calculation:

Types of Confidence Intervals

The ci_type argument allows you to choose between different methods for calculating bootstrap confidence intervals. At cube level these are passed to dubicube::calculate_bootstrap_ci(); at indicator level to boot::boot.ci():

• Percentile ("perc"): (Default) The simplest and most commonly used method. It uses the ordered bootstrap replicates to find the intervals (e.g., the 2.5th and 97.5th percentiles for a 95% CI). It is transformation-invariant and generally robust for biodiversity indicators.
• Bias-Corrected and Accelerated ("bca"): An improvement over the percentile method that adjusts for both bias and skewness in the bootstrap distribution. It is highly recommended for accuracy but requires more computation.
• Normal Approximation ("norm"): Assumes the bootstrap distribution is approximately normal. It uses the standard error of the bootstrap replicates to calculate the interval. While fast, it may be less accurate for skewed distributions typical of biodiversity metrics.
• Basic ("basic"): Also known as the “reverse percentile” method. It uses the percentiles of the distribution of the difference between the bootstrap replicates and the original estimate.

occ_ts_custom <- add_ci(occ_ts,
                        num_bootstrap = 500,
                        seed = 42,
                        ci_type = "perc",
                        confidence_level = 0.9,
                        boot_args = list(progress = TRUE))

# Example: Calculate CIs for evenness on raw scale (no logit transformation)
evenness_raw <- add_ci(my_evenness_indicator,
                       num_bootstrap = 1000,
                       ci_args = list(h = identity,
                                      hinv = identity))

# Example: Force bias correction for total_occ
occ_with_bias <- add_ci(my_occ_indicator,
                        num_bootstrap = 1000,
                        ci_args = list(no_bias = FALSE))

Supported Indicators

Confidence intervals can be added post-hoc for the following indicators:

• Total Occurrences (total_occ)
• Occurrence Density (occ_density)
• Newness (newness)
• Williams Evenness (williams_evenness)
• Pielou Evenness (pielou_evenness)
• Abundance-based Rarity (ab_rarity)
• Area-based Rarity (area_rarity)
• Species Occurrences (spec_occ)
• Species Range (spec_range)

Data Exploration with dubicube 🔍

While b3gbi focuses on indicator calculation and visualization, the underlying dubicube package offers powerful functions for initial data exploration and quality assessment of your biodiversity data cubes.

To learn more about the full capabilities of dubicube, including in-depth tutorials and advanced data processing techniques, please visit the dubicube documentation.

Summary

The add_ci() function provides a unified and robust interface for adding uncertainty to your biodiversity assessments. By leveraging the power of dubicube, b3gbi ensures that your results are not just numbers, but scientifically grounded estimates with clearly defined confidence boundaries.

With automatic indicator configuration, most users can rely on sensible defaults while advanced users retain full control over the bootstrapping process through the boot_args and ci_args parameters.