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.
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()
)List with results, summary, diagnostics, and settings.
Model formula.
brms GLM family (e.g., gaussian(), binomial()).
Optional list for INLA's control.family.
Optional vector for binomial trials.
Optional vector for Poisson exposure.
Optional vector scale parameter for INLA families.
Optional brms::prior specification. Supported analysis priors
are translated to INLA controls where possible and recorded in
settings$prior_translation.
Optional function(n, effect) returning a dataset.
Character vector of fixed effect names.
Vector/data.frame of effect values (supports multi-effect). For single effects, use a numeric vector. For multiple effects, use a data.frame with column names matching effect_name.
Vector of sample sizes.
Number of simulations per cell.
Decision probability threshold for summary.
Optional credible interval width target.
Posterior probability threshold for decision rules.
Effect-size threshold.
Credible interval level (default 0.95).
Optional Region of Practical Equivalence bounds (length 2 vector).
Residual standard deviation for Gaussian-like families. Accepts either:
A positive numeric scalar (default 1), or
A named list specifying a distribution from which a fresh value is drawn at every simulation iteration:
list(dist = "halfnormal", sd = X, location = Y) — draws
|Normal(location, sd)|; location defaults to 0.
list(dist = "lognormal", meanlog = X, sdlog = Y)
list(dist = "uniform", min = X, max = Y) — requires min >= 0.
See validate_sd_spec() for validation details.
Random-effects standard deviation. Accepts the same scalar
or distributional list formats as error_sd.
Observations per group.
Optional named list of predictor means.
Optional named list of predictor standard deviations.
Random seed.
Optional INLA-specific hyperparameters.
Logical, compute Bayes Factor if TRUE.
Character. "sd" = Savage-Dickey at 0 (requires proper Normal prior on the tested coefficient); "marglik" = marginal-likelihood Bayes factor via INLA by comparing full vs reduced model (slower).
Numeric Bayes-factor threshold for declaring a "hit" (default 10).
Character string specifying INLA threading (e.g., "4:1" for 4 threads). If NULL (default), automatically detects optimal setting: "4:1" for 4+ cores, "2:1" for 2-3 cores, "1:1" otherwise.
One of "auto", "text", or "none" for progress display.
List of arguments for family-specific data generators.
When error_sd or group_sd is supplied as a distributional list, a fresh
scalar value is drawn from the specified distribution at the start of
each simulation iteration. The drawn value is used by the automatic
data generator for that iteration and stored in the per-simulation results
as sampled_error_sd or sampled_group_sd. The per-cell summary then
reports the mean and standard deviation of the drawn values.
This corresponds to integrating power over variance uncertainty, analogous to the unconditional Bayesian assurance of O'Hagan & Stevens (2001) and the prior-predictive power framing of Chen et al. (2018). It is particularly useful when the residual variance is itself uncertain (e.g., estimated from a small pilot study).
Note: distributional error_sd / group_sd specifications only affect
the built-in automatic data generator. When a custom data_generator
function is supplied the drawn values are recorded but are not injected
into the custom function.
The priors argument is a convenience interface for selected brms-style
analysis priors. Gaussian fixed-effect and intercept priors are translated
directly to INLA control.fixed; student_t() fixed-effect priors use the
package's existing Normal approximation. For Gaussian models,
prior(exponential(rate), class = "sigma") and
prior(exponential(rate), class = "sd", group = "...") are translated to
INLA pc.prec priors with P(sigma > u) = alpha, where
u = -log(alpha) / rate and alpha = 0.05. Direct family_control
settings take precedence over translated sigma priors. Unsupported brms
priors are reported in settings$prior_translation rather than silently
translated. Data-generation controls such as error_sd and group_sd remain
distinct from INLA analysis priors.
if (FALSE) {
# Integrate over uncertainty in the residual SD using a half-normal prior
# centred at 1.0 with spread 0.3
brms_inla_power(
formula = y ~ treatment,
effect_name = "treatment",
effect_grid = 0.5,
sample_sizes = c(50, 100),
nsims = 50,
error_sd = list(dist = "halfnormal", sd = 0.3, location = 1.0),
seed = 42
)
}
Run the code above in your browser using DataLab