powerbrmsINLA (version 1.3.0)

compute_assurance: Compute unconditional Bayesian assurance from simulation results

Description

Computes unconditional Bayesian assurance — the probability of a successful trial outcome averaged over prior uncertainty about the true effect size — from the output of brms_inla_power() or related engines.

Usage

compute_assurance(
  power_result,
  prior_weights,
  metric = c("direction", "threshold", "rope", "bf"),
  weight_tol = 0.01
)

Value

A list of class "powerbrmsINLA_assurance" containing:

assurance

Data frame with columns sample_size and assurance.

metric

The decision metric used.

power_col

Name of the summary column used for power.

prior_spec

The prior_weights argument as supplied (useful for reproducibility).

weights

Named numeric vector of the normalised weights actually applied.

eff_cols

Character vector of effect-grid column names identified in the summary.

Arguments

power_result

A list returned by brms_inla_power(), brms_inla_power_parallel(), brms_inla_power_two_stage(), or brms_inla_power_sequential(); or a plain data frame with at least columns n and the relevant power_* metric column.

prior_weights

Either (a) a named numeric vector of weights over effect-size values (must sum to 1 within tolerance 0.01), or (b) a list specifying a distribution — see Details. The output of beta_weights_on_grid() and assurance_prior_weights() is directly compatible.

metric

Character string selecting the decision metric. Must match a column present in the summary. One of:

• "direction" → power_direction

• "threshold" → power_threshold

• "rope" → power_rope

• "bf" → bf_hit_10

weight_tol

Numeric tolerance for the weights-sum-to-1 check (default 0.01).

Details

Assurance vs. conditional Bayesian power

The simulations run by brms_inla_power() are conditional: for each point on the effect grid the engine estimates the probability that the chosen decision rule is satisfied. This is Bayesian design power (a function of the unknown true effect).

Assurance, in the sense of O'Hagan & Stevens (2001) and O'Hagan, Stevens & Campbell (2005), is the unconditional version:

$$ A(n) = \int \mathrm{Power}(n, \delta)\, \pi(\delta)\, d\delta \approx \sum_j w_j \cdot \mathrm{Power}(n, \delta_j) $$

where \(\pi(\delta)\) is a design prior on the effect size and \(w_j\) are the normalised prior weights over the discrete effect grid \(\{\delta_j\}\). Assurance therefore accounts for the investigator's genuine uncertainty about the effect, not just a single "assumed" value (Ristl et al., 2019; Kunzmann et al., 2021).

Variance uncertainty

If the simulation was run with multiple sampled variance parameters (stored in columns such as sampled_error_sd or sampled_group_sd in the results), the averaging over those values is already implicit in each per-cell power estimate, so no additional action is required here.

Supplying prior weights

Two forms are accepted for prior_weights:

• Named numeric vector — names must match the effect-grid values used in power_result (as produced by as.character(), which is the format used by beta_weights_on_grid() and assurance_prior_weights()). Unnamed vectors are accepted only when their length equals the number of unique effect values, in which case they are applied in ascending order.

• Distribution list — a list with at minimum $dist naming one of "normal" (mean, sd), "uniform" (min, max), or "beta" (shape1/shape2 or mode/n). Weights are computed by evaluating the density at each grid point and normalising. Supported for single-effect results only.

For multi-effect grids the prior_weights argument must be a numeric vector of length equal to the number of unique effect combinations in the summary (sorted lexicographically by effect columns). Use assurance_prior_weights() or beta_weights_on_grid() to construct compatible weights for single-effect cases.

References

O'Hagan, A., & Stevens, J. W. (2001). Bayesian assessment of sample size for clinical trials of cost-effectiveness. Medical Decision Making, 21(3), 219–230. tools:::Rd_expr_doi("10.1177/0272989X0102100307")

O'Hagan, A., Stevens, J. W., & Campbell, M. J. (2005). Assurance in clinical trial design. Pharmaceutical Statistics, 4(3), 187–201. tools:::Rd_expr_doi("10.1002/pst.175")

Ristl, R., Glimm, E., Stallard, N., & Posch, M. (2019). Optimal design and analysis of two-stage adaptive enrichment trials. Biometrical Journal, 61(6), 1461–1481.

Kunzmann, K., Grayling, M. J., Lee, K. M., Robertson, D. S., Rufibach, K., & Wason, J. M. S. (2021). A review of Bayesian perspectives on sample size derivation for confirmatory trials. The American Statistician, 75(4), 424–432. tools:::Rd_expr_doi("10.1080/00031305.2021.1901782")

Examples

# Build a small synthetic power_result without running INLA
syn_summary <- data.frame(
  n               = rep(c(50, 100, 200), each = 3),
  treatment       = rep(c(0.2, 0.5, 0.8), 3),
  power_direction = c(0.40, 0.65, 0.85,
                      0.60, 0.82, 0.95,
                      0.72, 0.90, 0.98),
  stringsAsFactors = FALSE
)
syn_result <- list(
  summary  = syn_summary,
  settings = list(effect_name = "treatment")
)

# (a) Uniform weights — assurance is the simple mean of per-cell powers
w_uniform <- c("0.2" = 1/3, "0.5" = 1/3, "0.8" = 1/3)
out <- compute_assurance(syn_result, prior_weights = w_uniform)
print(out)

# (b) Normal design prior centred on a medium-sized effect
out2 <- compute_assurance(
  syn_result,
  prior_weights = list(dist = "normal", mean = 0.5, sd = 0.2)
)
print(out2)

# (c) Using assurance_prior_weights() to build the weight vector explicitly
w_norm <- assurance_prior_weights(c(0.2, 0.5, 0.8), dist = "normal",
                                  mean = 0.5, sd = 0.2)
out3 <- compute_assurance(syn_result, prior_weights = w_norm)