Title:	Bayesian Power Analysis Using 'brms' and 'INLA'
Version:	1.0.0
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.0.0)
Imports:	brms (≥ 2.19.0), dplyr (≥ 1.1.0), ggplot2 (≥ 3.4.0), 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-08-26 05:27:37 UTC; user
Author:	Tony Myers [aut, cre]
Repository:	CRAN
Date/Publication:	2025-09-01 09:20:10 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)

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.

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,
  inla_num_threads = NULL,
  progress = c("auto", "text", "none"),
  family_args = list()
)

Arguments

Value

List with results, summary, and settings.

Examples

# Basic usage with automatic INLA threading
results <- brms_inla_power(
  formula = outcome ~ treatment,
  effect_name = "treatment",
  effect_grid = c(0.2, 0.5, 0.8),
  sample_sizes = c(50, 100, 200),
  nsims = 3
)
print(results$summary)

# Manual INLA threading control
results <- brms_inla_power(
  formula = outcome ~ treatment,
  effect_name = "treatment",
  effect_grid = c(0.2, 0.5, 0.8),
  sample_sizes = c(50, 100, 200),
  inla_num_threads = "8:1",  # Use 8 threads for faster computation
  nsims = 3
)

# Multi-effect design with threading
effect_grid <- expand.grid(
  treatment = c(0, 0.3, 0.6),
  age_effect = c(0, 0.2)
)
results <- brms_inla_power(
  formula = outcome ~ treatment + age_effect,
  effect_name = c("treatment", "age_effect"),
  effect_grid = effect_grid,
  sample_sizes = c(100, 200, 400),
  nsims = 3
)
print(results$summary)

# Quick parameter check (runs instantly)
formals(brms_inla_power)

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

# 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)

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

# 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)

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.

Plot Bayes Factor Assurance Curve (Multi-Effect Grid Friendly)

Description

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

Usage

plot_bf_assurance_curve(
  power_results,
  bf_threshold = 3,
  x_effect = NULL,
  facet_by = NULL,
  effect_filters = NULL,
  effect_weights = NULL,
  title = NULL,
  subtitle = NULL
)

Arguments

Value

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.

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

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.

Plot Precision Assurance Fan Chart (Multi-Effect Grid Friendly)

Description

Shows assurance (proportion of runs meeting CI width <= target) across sample size(s) and effect grid. Optionally overlays the range (fan/ribbon) across multiple scenarios.

Usage

plot_precision_fan_chart(
  power_results_list,
  ci_width_target,
  x_effect = NULL,
  facet_by = NULL,
  effect_filters = NULL,
  effect_weights = NULL,
  show_individual_scenarios = FALSE,
  title = NULL,
  subtitle = NULL
)

Arguments

Value

A ggplot object.