powerbrmsINLA (version 1.3.0)

decide_sample_size: Decide recommended sample size from power/assurance results

Description

Returns the smallest per-group sample size that meets user-specified power or assurance targets. Works with brms_inla_power() and related engine outputs.

Usage

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

Value

An object of class "powerbrmsINLA_sample_size" (which inherits from data.frame) with a print.powerbrmsINLA_sample_size() method.

Assurance mode columns:

metric

Requested metric name ("direction", "threshold", "rope_in", "bf10").

target

The assurance target supplied.

n_recommended

Smallest per-group sample size achieving the target, or NA if none in the grid qualifies.

assurance_achieved

Assurance value at the recommended n.

prior_description

Plain-text description of the design prior.

Conditional mode columns:

<effect column(s)>

One column per effect variable.

n_recommended

Smallest per-group sample size meeting all targets, or NA.

cond_power_*

Conditional power at the recommended n for each requested metric.

Arguments

x

A list with $summary (engine output) or a plain data.frame summary.

direction

Numeric in \([0,1]\): assurance target (assurance mode) or required conditional power (conditional mode) for power_direction. Omit to exclude this metric.

threshold

Numeric in \([0,1]\): assurance target (assurance mode) or required conditional power (conditional mode) for power_threshold. Omit to exclude this metric.

rope_in

Numeric in \([0,1]\): assurance target (assurance mode) or maximum allowed Pr(in ROPE) (conditional mode). Omit to exclude this metric.

bf10

Numeric Bayes-factor cutoff (e.g., 10). If provided the function looks for a column bf_hit_<bf10>; if absent it falls back to per-simulation bf10 in x$results.

bf_prop_min

Numeric in \([0,1]\): minimum proportion of simulations that must achieve BF >= bf10 (default 0; conditional mode only).

targets

Optional named list alternative to the direct arguments. Ignored when any direct argument is non-NULL.

prior_weights

A design prior for assurance mode. Accepts the same formats as compute_assurance(): a named numeric vector of weights over effect-grid values, or a distribution list such as list(dist = "normal", mean = 0.5, sd = 0.2). When NULL (default), the function operates in conditional mode.

target

Numeric in \([0,1]\): fallback assurance level used only when a metric is requested without a valid numeric threshold (default 0.80). In normal usage the per-metric value (e.g., direction = 0.70) supersedes this argument.

Details

Targets may be supplied as direct arguments or via a targets list; direct arguments take precedence.

Modes of operation

Assurance mode (recommended): supply prior_weights with a design prior over the effect grid. The function calls compute_assurance() internally and returns the smallest sample size where unconditional Bayesian assurance reaches the per-metric target for each requested metric.

In assurance mode the numeric value passed to direction, threshold, rope_in, or bf10 is the assurance target for that metric. For example, direction = 0.70 finds the smallest n where direction assurance >= 0.70, and threshold = 0.60 finds the smallest n where threshold assurance >= 0.60. Multiple metrics may be requested simultaneously, each with its own target.

Conditional mode (backward compatible): when prior_weights = NULL, the function selects the smallest n at which the per-cell conditional power meets the specified target for each effect-size value. If the summary contains sampled variance columns (e.g., from distributional error_sd), they are averaged out before selecting n.

See Also

compute_assurance(), assurance_prior_weights(), beta_weights_on_grid()

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),
  power_threshold = c(0.30, 0.55, 0.75,
                      0.50, 0.72, 0.88,
                      0.62, 0.80, 0.92),
  stringsAsFactors = FALSE
)
syn_result <- list(
  summary  = syn_summary,
  settings = list(effect_name = "treatment")
)

# --- Assurance mode: each metric value IS the assurance target ---
w <- assurance_prior_weights(c(0.2, 0.5, 0.8), dist = "normal",
                              mean = 0.5, sd = 0.2)
# Find n where direction assurance >= 0.80 AND threshold assurance >= 0.75
rec_assurance <- decide_sample_size(
  syn_result,
  direction     = 0.80,
  threshold     = 0.75,
  prior_weights = w
)
print(rec_assurance)

# --- Conditional mode (backward compatible) ---
rec_cond <- decide_sample_size(syn_result, direction = 0.80)
print(rec_cond)