Skip to contents

Add Confidence Intervals to an Indicator Object

Source: R/add_ci.R
add_ci.Rd

This function calculates bootstrap confidence intervals for an existing indicator_ts object. It supports both cube-level bootstrapping (resampling occurrence records) and indicator-level bootstrapping (resampling calculated values), allowing for advanced transformations during the CI calculation process.

Usage

add_ci(
  indicator,
  num_bootstrap = 1000,
  bootstrap_level = c("cube", "indicator"),
  ci_type = c("perc", "bca", "norm", "basic", "none"),
  trans = function(t) t,
  inv_trans = function(t) t,
  confidence_level = 0.95,
  overwrite = TRUE,
  boot_args = list(),
  ci_args = list(),
  seed = 123,
  ...
)

Arguments

indicator

An object of class indicator_ts to which confidence intervals should be added.

num_bootstrap

(Optional) Number of bootstrap replicates to perform. (Default: 1000)

bootstrap_level

(Optional) Level at which to perform bootstrapping:

  • cube (default): Bootstrapping is done by resampling the occurrence records in the cube. This is mathematically more robust as it captures the underlying sampling uncertainty.

  • indicator: Bootstrapping is done by resampling indicator values. This is faster for large cubes but less robust.

ci_type

(Optional) Type of bootstrap confidence intervals to calculate. (Default: "perc"). Supported options are:

  • perc: Percentile intervals.

  • bca: Bias-corrected and accelerated intervals.

  • norm: Normal approximation intervals.

  • basic: Basic bootstrap intervals.

  • none: No confidence intervals calculated.

trans

(Optional) A function for transforming the indicator values before calculating confidence intervals (e.g., log). (Default: identity function)

inv_trans

(Optional) The inverse of the transformation function trans (e.g., exp). Used to back-transform the intervals to the original scale. (Default: identity function)

confidence_level

(Optional) The confidence level for the calculated intervals (e.g., 0.95 for 95% CIs). (Default: 0.95)

overwrite

(Optional) Logical. If the indicator already contains confidence intervals (ll and ul columns), should they be replaced? (Default: TRUE)

boot_args

(Optional) Named list of additional arguments passed to dubicube::bootstrap_cube(). (Default: list())

ci_args

(Optional) Named list of additional arguments passed to dubicube::calculate_bootstrap_ci(). (Default: list())

seed

(Optional) Integer. Random seed for bootstrapping. (Default: 123)

...

(Optional) Additional arguments passed to calc_ci().

Value

An updated object of class indicator_ts containing the original data with the following additional columns:

  • ll: Lower limit of the confidence interval.

  • ul: Upper limit of the confidence interval.

  • est_boot: The bootstrap estimate of the indicator value.

  • se_boot: The bootstrap standard error.

  • bias_boot: The bootstrap estimate of bias.

  • int_type: The type of interval calculated (e.g., 'perc').

  • conf: The confidence level used.

Details

The function acts as a bridge to the dubicube package to calculate bootstrap confidence intervals.

Indicator-specific defaults

Depending on the indicator, default settings are internally applied when calculating bootstrap confidence intervals. These defaults control whether bootstrapping is performed per group, which transformation is used, and whether bias correction is disabled.

The following defaults are used unless explicitly overridden via trans, inv_trans, boot_args, or ci_args:

  • total_occ

    • Group-specific bootstrapping: yes

    • Transformation: none (identity)

    • Bias correction: disabled (no_bias = TRUE)

  • spec_occ, spec_range

    • Group-specific bootstrapping: yes

    • Transformation: none (identity)

    • Bias correction: enabled

  • pielou_evenness, williams_evenness

    • Group-specific bootstrapping: no

    • Transformation: logit

    • Inverse transformation: inverse logit

    • Bias correction: enabled

  • occ_density, ab_rarity, area_rarity, newness

    • Group-specific bootstrapping: no

    • Transformation: none (identity)

    • Bias correction: enabled

Group-specific bootstrapping means that resampling is performed within each group (e.g., species or year), which is required for indicators that are inherently group-based. This in contrast to whole-cube bootstrapping where resampling is performed across the whole dataset; applicable for indicators that combine information across groups

Transformations are applied prior to confidence interval calculation and inverted afterwards to return intervals on the original scale.

Indicators outside scope of this function

For certain indicators, confidence intervals cannot be added post-hoc as they are calculated internally via the iNext package, or if they are not relevant. In such cases, a warning is issued and the original object is returned. The following indicators cannot have confidence intervals added via add_ci():

  • hill0, hill1, hill2 (calculated internally)

  • obs_richness

  • cum_richness

  • occ_turnover

  • tax_distinct

See also

dubicube::bootstrap_cube(), dubicube::calculate_bootstrap_ci()