Title:	Bayesian Power Analysis Using 'brms' and 'INLA'
Version:	1.1.1
Maintainer:	Tony Myers <admyers@aol.com>
Description:	Provides tools for Bayesian power analysis and assurance calculations using the statistical frameworks of 'brms' and 'INLA'. Includes simulation-based approaches, support for multiple decision rules (direction, threshold, ROPE), sequential designs, and visualisation helpers. Methods are based on Kruschke (2014, ISBN:9780124058880) "Doing Bayesian Data Analysis: A Tutorial with R, JAGS, and Stan", O'Hagan & Stevens (2001) <doi:10.1177/0272989X0102100307> "Bayesian Assessment of Sample Size for Clinical Trials of Cost-Effectiveness", Kruschke (2018) <doi:10.1177/2515245918771304> "Rejecting or Accepting Parameter Values in Bayesian Estimation", Rue et al. (2009) <doi:10.1111/j.1467-9868.2008.00700.x> "Approximate Bayesian inference for latent Gaussian models by using integrated nested Laplace approximations", and Bürkner (2017) <doi:10.18637/jss.v080.i01> "brms: An R Package for Bayesian Multilevel Models using Stan".
License:	MIT + file LICENSE
Encoding:	UTF-8
RoxygenNote:	7.3.2
Depends:	R (≥ 4.1.0)
Imports:	brms (≥ 2.19.0), dplyr (≥ 1.1.0), ggplot2 (≥ 3.4.0), pbapply, rlang (≥ 1.1.0), tibble (≥ 3.2.0), scales (≥ 1.2.0), viridisLite (≥ 0.4.0), stats, utils, magrittr (≥ 2.0.0)
Suggests:	INLA (≥ 22.05.07), testthat (≥ 3.0.0), rmarkdown, MASS, circular, sn
URL:	https://github.com/Tony-Myers/powerbrmsINLA
BugReports:	https://github.com/Tony-Myers/powerbrmsINLA/issues
Additional_repositories:	https://inla.r-inla-download.org/R/stable
NeedsCompilation:	no
Packaged:	2025-11-16 19:13:30 UTC; tonymyers
Author:	Tony Myers [aut, cre]
Repository:	CRAN
Date/Publication:	2025-11-16 19:30:02 UTC

Add Contour Lines to a ggplot2 Plot

Description

Wrapper around geom_contour with preset defaults for color, alpha, width. Uses the correct linewidth/size argument depending on ggplot2 version.

Usage

.add_contour_lines(
  mapping = NULL,
  data = NULL,
  breaks = NULL,
  colour = "white",
  alpha = 0.3,
  width = 0.2,
  bins = NULL
)

.add_contour_lines(
  mapping = NULL,
  data = NULL,
  breaks = NULL,
  colour = "white",
  alpha = 0.3,
  width = 0.2,
  bins = NULL
)

Arguments

Value

A ggplot2 layer adding contour lines.

A ggplot2 layer adding contour lines.

Automatic Data Generator for brms + INLA Simulation (Multi-Effect Ready)

Description

Creates a simulation function taking n (sample size) and a named effect vector/list. Supports multiple predictors, brms-style random effects, and most GLM families.

Usage

.auto_data_generator(
  formula,
  effect_name,
  family = gaussian(),
  family_args = list(),
  error_sd = 1,
  group_sd = 0.5,
  obs_per_group = 10,
  predictor_means = NULL,
  predictor_sds = NULL
)

Arguments

Value

Function: function(n, effect) returns a data.frame with n rows.

Convert brms Formula to INLA Formula (Multi-Fixed Support)

Description

Converts brms-style formula to INLA-ready formula, robust to multi-effect, and random effects.

Usage

.brms_to_inla_formula2(formula, drop_fixed = NULL)

Arguments

Value

List: $inla_formula, $re_specs

Compute Mean Assurance for a Given Metric (Multi-Effect Compatible) Summarises simulation results and computes proportion passing for decision rule metric.

Description

Compute Mean Assurance for a Given Metric (Multi-Effect Compatible) Summarises simulation results and computes proportion passing for decision rule metric.

Usage

.compute_assurance(
  df,
  metric,
  prob_threshold,
  rope_rule = c(">="),
  direction_p = 0.5,
  effect_cols = NULL
)

Arguments

Value

Tibble grouped by n and effects with assurance column.

Create a ggplot2 Line Layer with Version-Compatible Width

Description

Creates a geom_line with a width argument adapted to ggplot2 version.

Usage

.geom_line_lw(mapping = NULL, data = NULL, ..., width = 1)

.geom_line_lw(mapping = NULL, data = NULL, ..., width = 1)

Arguments

Value

ggplot2 layer for lines.

ggplot2 layer for lines.

Create a ggplot2 Point Layer with Version-Compatible Width

Description

Creates a geom_point with a width argument adapted to ggplot2 version.

Usage

.geom_point_lw(mapping = NULL, data = NULL, ..., width = 1.5)

.geom_point_lw(mapping = NULL, data = NULL, ..., width = 1.5)

Arguments

Value

ggplot2 layer for points.

ggplot2 layer for points.

Compute Mean Assurance for a Given Metric (Modern, Multi-Effect Compatible)

Description

Computes the mean assurance (proportion passing) for a given decision metric across grouped cells.

Usage

.gg_line_arg()

.gg_line_arg()

Details

Determine ggplot2 Line Width Argument Name by Version

Returns the correct argument name for line width in ggplot2, depending on package version ("linewidth" for >= 3.4.0, else "size").

Value

Character string of argument name.

Character string of argument name.

Map brms Priors to INLA Priors (Multi-Fixed)

Description

Parses a brms prior specification, mapping fixed effect priors to INLA control.fixed. Supports normal and student_t (variance-matched if df > 2).

Usage

.map_brms_priors_to_inla(priors, approx_t_as_normal = TRUE)

Arguments

Value

List with $control_fixed and $hyper_by_re.

Parse brms-like Random Effects Terms (Modern Robust)

Description

Extracts random-effects specifications from a brms-style formula string. Supports (1 | g), (1 + x | g) - only one slope per term (warns otherwise!).

Usage

.parse_re_terms(formula)

Arguments

Value

List of RE spec lists (group, intercept/slope info)

Plot decision/assurance curve across n

Description

Plot decision/assurance curve across n

Usage

.plot_decision_assurance_curve_from_summary(
  x,
  y_metric = c("assurance", "power_direction", "power_threshold", "power_rope",
    "bf_hit_10"),
  target = NULL,
  effect_filter = NULL,
  first_n_label = TRUE
)

Arguments

Value

ggplot object.

Scale Fill for Viridis Continuous Data

Description

Scale Fill for Viridis Continuous Data

Usage

.scale_fill_viridis_continuous(
  name = "Assurance",
  limits = c(0, 1),
  breaks = seq(0, 1, 0.2),
  labels = scales::percent_format(accuracy = 1)
)

Arguments

Value

ggplot2 fill scale object

Scale Fill for Viridis Discrete Data

Description

Scale Fill for Viridis Discrete Data

Scale Fill for Viridis Discrete Data

Usage

.scale_fill_viridis_discrete(name = "Assurance")

.scale_fill_viridis_discrete(name = "Assurance")

Arguments

Value

ggplot2 fill scale object

ggplot2 fill scale object

Wilson Confidence Interval Early Stopping Rule Determines whether to stop early based on Wilson binomial confidence interval.

Description

Wilson Confidence Interval Early Stopping Rule Determines whether to stop early based on Wilson binomial confidence interval.

Usage

.should_stop_binom(hits, trials, target, margin = 0.02, conf = 0.95)

Arguments

Value

List with stop (logical) and ci (numeric vector)

Map a brms Family to an INLA Family (Modern, Robust)

Description

Map a brms Family to an INLA Family (Modern, Robust)

Convert brms Family to INLA Family Maps brms family specifications to corresponding INLA family names.

Usage

.to_inla_family(family)

.to_inla_family(family)

Arguments

Value

List with $inla and $brms family names.

List with brms and inla elements containing the family names.

Add sample-size decision overlay to an assurance contour

Description

Overlays the output of decide_sample_size() as a step-line on a contour plot (e.g. from plot_power_contour()).

Usage

add_decision_overlay(p, decisions, x_effect = NULL, colour = "red")

Arguments

Details

If the decisions contain multiple effect-grid columns, the overlay is aggregated over all effect columns except x_effect by taking the worst-case (maximum) recommended n at each value of x_effect.

Value

A ggplot object.

Analytic Assurance for Beta-Binomial Designs

Description

Computes assurance (power) using generating and audience Beta priors for a binomial count via a Beta-Binomial predictive distribution.

Usage

beta_binom_power(
  n,
  gen_prior_a,
  gen_prior_b,
  aud_prior_a,
  aud_prior_b,
  hdi_mass = 0.95,
  rope = NULL,
  hdi_max_width = NULL
)

Arguments

Value

Assurance value between 0 and 1.

Beta-Prior Weights Over an Effect Grid

Description

Computes prior weights over a grid of true effect values by evaluating a Beta(mode, n) prior. If the grid is not in (0,1), it is rescaled linearly.

Usage

beta_weights_on_grid(effects, mode, n)

Arguments

Value

Normalised numeric weights over the grid (sum to 1).

Core Bayesian Assurance / Power Simulation (Modern, Multi-Effect Ready)

Description

Provides Bayesian power analysis and assurance calculation using INLA (Integrated Nested Laplace Approximation) for efficient computation. Implements simulation-based power analysis for generalized linear mixed models with automatic threading optimization.

Usage

brms_inla_power(
  formula,
  family = gaussian(),
  family_control = NULL,
  Ntrials = NULL,
  E = NULL,
  scale = NULL,
  priors = NULL,
  data_generator = NULL,
  effect_name,
  effect_grid = 0.5,
  sample_sizes = c(50, 100, 200, 400),
  nsims = 200,
  power_threshold = 0.8,
  precision_target = NULL,
  prob_threshold = 0.95,
  effect_threshold = 0,
  credible_level = 0.95,
  rope_bounds = NULL,
  error_sd = 1,
  group_sd = 0.5,
  obs_per_group = 10,
  predictor_means = NULL,
  predictor_sds = NULL,
  seed = 123,
  inla_hyper = NULL,
  compute_bayes_factor = FALSE,
  bf_method = c("sd", "marglik"),
  bf_cutoff = 10,
  inla_num_threads = NULL,
  progress = c("auto", "text", "none"),
  family_args = list()
)

Arguments

Value

List with results, summary, and settings.

Design-based wrapper for Bayesian power / assurance

Description

Dispatches to one of the three engines depending on design. This function must accept ... and pass it on unchanged.

Usage

brms_inla_power_design(design = c("fixed", "two_stage", "sequential"), ...)

Arguments

Value

Whatever the underlying engine returns.

Parallel wrapper for fixed-design Bayesian power / assurance simulations

Description

Parallelises over cells defined by sample_sizes x effect_grid for the fixed-n engine brms_inla_power().

Usage

brms_inla_power_parallel(
  design = c("fixed"),
  sample_sizes,
  effect_grid,
  nsims,
  n_cores = max(1L, parallel::detectCores() - 1L),
  seed = 123L,
  progress = c("auto", "text", "none"),
  ...
)

Arguments

Value

A list with components summary, results, and settings.

Sequential Bayesian Assurance Simulation Engine (Modern, Multi-Effect Ready)

Description

Simulates assurance sequentially in batches, stopping early per cell based on Wilson confidence intervals.

Usage

brms_inla_power_sequential(
  formula,
  family = gaussian(),
  family_control = NULL,
  Ntrials = NULL,
  E = NULL,
  scale = NULL,
  priors = NULL,
  data_generator = NULL,
  effect_name,
  effect_grid,
  sample_sizes,
  metric = c("direction", "threshold", "rope", "bf"),
  target = 0.8,
  prob_threshold = 0.95,
  effect_threshold = 0,
  rope_bounds = NULL,
  credible_level = 0.95,
  compute_bayes_factor = FALSE,
  error_sd = 1,
  group_sd = 0.5,
  obs_per_group = 10,
  predictor_means = NULL,
  predictor_sds = NULL,
  seed = 1,
  batch_size = 20,
  min_sims = 40,
  max_sims = 600,
  ci_conf = 0.95,
  margin = 0.02,
  inla_num_threads = NULL,
  family_args = list(),
  progress = TRUE
)

Arguments

Details

Sequential Bayesian Assurance Simulation Engine (Modern, Multi-Effect Ready)

Simulates assurance sequentially in batches, stopping early per cell based on Wilson confidence intervals.

Value

List containing summary per cell and simulation settings.

Examples

## Not run: 
# Sequential design with automatic threading
results <- brms_inla_power_sequential(
  formula = outcome ~ treatment,
  effect_name = "treatment",
  effect_grid = c(0.2, 0.5, 0.8),
  sample_sizes = c(50, 100, 200),
  metric = "direction",
  target = 0.80
)
print(results$summary)

## End(Not run)

Two-Stage Bayesian Assurance Simulation (Multi-Effect, User-Friendly API)

Description

Runs a two-stage Bayesian assurance simulation with formula-based multi-effect grids and adaptive refinement.

Usage

brms_inla_power_two_stage(
  formula,
  effect_name,
  effect_grid,
  n_range,
  stage1_k_n = 8,
  stage1_nsims = 100,
  stage2_nsims = 400,
  refine_metric = c("direction", "threshold", "rope"),
  refine_target = 0.8,
  prob_threshold = 0.95,
  effect_threshold = 0,
  obs_per_group = NULL,
  error_sd = NULL,
  group_sd = 0.5,
  band = 0.06,
  expand = 1L,
  inla_num_threads = NULL,
  ...
)

Arguments

Value

A list with combined simulation results, summary, and stage parameters.

Examples

## Not run: 
# Two-stage design with threading
effect_grid <- expand.grid(
  treatment = c(0.2, 0.5, 0.8),
  covariate = c(0.1, 0.3)
)
results <- brms_inla_power_two_stage(
  formula = outcome ~ treatment + covariate,
  effect_name = c("treatment", "covariate"),
  effect_grid = effect_grid,
  n_range = c(50, 200),
  stage1_nsims = 3,
  stage2_nsims = 3,
   error_sd = 1 
)
print(results$summary)

## End(Not run)

Decide recommended sample size from power/assurance results

Description

Returns the smallest n per effect setting that meets user-specified targets. Works with both brms_inla_power() and brms_inla_power_sequential() outputs.

Usage

decide_sample_size(
  x,
  direction = NULL,
  threshold = NULL,
  rope_in = NULL,
  bf10 = NULL,
  bf_prop_min = 0,
  targets = NULL
)

Arguments

Details

You can pass targets directly via arguments (direction, threshold, rope_in, bf10) or via targets = list(direction=..., threshold=..., rope_in=..., bf10=...). Direct arguments take precedence if supplied.

Value

A data.frame with recommended n per effect combination and the rationale.

Highest Density Interval from an Inverse CDF

Description

Computes an HDI of given mass from any distribution for which you have a quantile function (inverse CDF).

Usage

hdi_of_icdf(qfun, width = 0.95, tol = 1e-08, ...)

Arguments

Value

Named numeric vector with elements ll and ul.

Minimum n for Target Assurance (Beta-Binomial)

Description

Minimum n for Target Assurance (Beta-Binomial)

Usage

min_n_beta_binom(
  gen_prior_mode,
  gen_prior_n,
  desired_power,
  aud_prior_mode = 0.5,
  aud_prior_n = 2,
  hdi_mass = 0.95,
  rope = NULL,
  hdi_max_width = NULL,
  n_start = 20,
  n_max = 1e+05,
  verbose = TRUE
)

Arguments

Value

Smallest n meeting the target assurance.

Internal Coalesce Operator Returns the left-hand side if it is not NULL, otherwise the right-hand side.

Description

Internal Coalesce Operator Returns the left-hand side if it is not NULL, otherwise the right-hand side.

Usage

x %||% y

Arguments

Value

If x is not NULL, returns x; else y.

Plot Assurance with Robustness Ribbon (Multi-Effect Grid Friendly)

Description

Compares assurance results from multiple scenarios by showing the range ("ribbon") of values across scenarios for each sample size and effect grid variable.

Usage

plot_assurance_with_robustness(
  power_results_list,
  metric = c("precision", "direction", "threshold", "bf"),
  x_effect = NULL,
  facet_by = NULL,
  precision_target = NULL,
  p_star = 0.95,
  bf_threshold = 10,
  effect_filters = NULL,
  effect_weights = NULL,
  show_individual_scenarios = FALSE,
  title = NULL,
  subtitle = NULL
)

Arguments

Value

A ggplot object.

Bayes-factor assurance curve (user-facing wrapper)

Description

This is the main function users should call to visualise Bayes-factor "power" / assurance. It is a thin wrapper around plot_bf_assurance_curve_smooth(), so all existing behaviour is preserved.

Usage

plot_bf_assurance_curve(power_results, bf_threshold = 10, effect_filter = NULL)

Arguments

Value

A ggplot object.

Bayes-factor assurance curve with Wilson CIs (multi-effect grid friendly)

Description

Plots the proportion of simulations in which BF10 meets or exceeds a threshold, grouped by sample size and any effect grid variables.

Usage

plot_bf_assurance_curve_smooth(x, cutoff = 10, effect_filter = NULL)

Arguments

Value

A ggplot object.

Plot Expected Evidence (mean log10 BF10, Multi-Effect Grid Friendly)

Description

Plots the average log10 BF10 against any effect grid variable, grouped/faceted.

Usage

plot_bf_expected_evidence(
  power_results,
  x_effect = NULL,
  facet_by = NULL,
  n = NULL,
  agg_fun = mean,
  title = NULL,
  subtitle = NULL
)

Arguments

Value

A ggplot object.

Plot Bayes Factor Heatmap (mean log10 BF10, Multi-Effect Grid Friendly)

Description

Heatmap of mean log10 BF10 as a function of two effect grid columns (x/y), with optional faceting.

Usage

plot_bf_heatmap(
  power_results,
  x_effect = NULL,
  y_effect = "n",
  facet_by = NULL,
  n = NULL,
  agg_fun = mean,
  title = NULL,
  subtitle = NULL
)

Arguments

Value

ggplot object.

Plot Decision Assurance Curve (Multi-Effect Grid Friendly)

Description

Plots the assurance (proportion of simulation runs meeting a posterior probability decision rule) versus an effect grid variable, for a given metric ("direction", "threshold", or "rope") at a fixed decision probability threshold p_star.

Usage

plot_decision_assurance_curve(
  power_results,
  metric = c("direction", "threshold", "rope"),
  p_star = 0.95,
  x_effect = NULL,
  facet_by = NULL,
  effect_filters = NULL,
  effect_weights = NULL,
  title = NULL,
  subtitle = NULL
)

Arguments

Value

A ggplot object.

Plot Decision Threshold Contour (Multi-Effect Grid Friendly)

Description

Shows assurance as a function of decision threshold p* and one effect grid column, optionally faceted.

Usage

plot_decision_threshold_contour(
  power_results,
  metric = c("direction", "threshold", "rope"),
  p_star_grid = seq(0.5, 0.99, by = 0.01),
  effect_var = NULL,
  facet_by = NULL,
  effect_value = NULL,
  effect_weights = NULL,
  title = NULL,
  subtitle = NULL
)

Arguments

Value

ggplot2 object.

Plot Interaction Assurance Surface/Heatmap/Lines (Multi-Effect Grid Friendly)

Description

Visualizes a metric (e.g., assurance) as a function of two effect grid variables for a fixed sample size or averaged over n. Allows line, heatmap, or contour modes.

Usage

plot_interaction_surface(
  data,
  metric,
  effect1,
  effect2,
  n = NULL,
  line = FALSE,
  facet_by = NULL,
  agg_fun = mean,
  title = NULL,
  subtitle = NULL
)

Arguments

Value

A ggplot object.

Draw a filled contour plot of assurance for a chosen metric, as a function of two effect grid columns and sample size.

Description

Draw a filled contour plot of assurance for a chosen metric, as a function of two effect grid columns and sample size.

Usage

plot_power_contour(
  power_results,
  power_metric = c("direction", "threshold", "rope"),
  x_effect = NULL,
  y_effect = "n",
  facet_by = NULL,
  power_threshold = 0.8,
  show_threshold_line = TRUE,
  title = NULL,
  subtitle = NULL
)

Arguments

Value

A ggplot object.

Plot Bayesian Power / Assurance Heatmap (Multi-Effect Grid Friendly)

Description

Heatmap of assurance for a chosen metric across two selected effect grid variables and sample sizes.

Usage

plot_power_heatmap(
  power_results,
  power_metric = c("direction", "threshold", "rope"),
  x_effect = NULL,
  y_effect = "n",
  facet_by = NULL,
  title = NULL,
  subtitle = NULL
)

Arguments

Value

A ggplot object.

Plot Precision Assurance Curve (Multi-Effect Grid Friendly)

Description

Plots the assurance (proportion of runs meeting CI width <= target) vs. a chosen effect grid variable across sample size(s). Supports faceting, effect filtering, and weights.

Usage

plot_precision_assurance_curve(
  power_results,
  precision_target,
  x_effect = NULL,
  facet_by = NULL,
  effect_filters = NULL,
  effect_weights = NULL,
  title = NULL,
  subtitle = NULL
)

Arguments

Value

A ggplot object.

Precision assurance as a function of sample size

Description

Plots the proportion of simulations in which the posterior credible interval width is less than or equal to a target, as a function of sample size n. Optionally colours separate curves by an effect-grid variable.

Usage

plot_precision_fan_chart(
  power_results,
  ci_width_target,
  effect_filter = NULL,
  colour_by = NULL,
  title = NULL,
  subtitle = NULL
)

Arguments

Details

This implementation works directly from the per-simulation results (column ci_width) and does not rely on the robustness engine.

Value

A ggplot object.