Simulates trials in which data accumulate and are analysed with INLA at a prespecified schedule of interim looks. At each look a posterior probability criterion is evaluated and the trial stops for success, futility, or (for the ROPE metric) practical equivalence; otherwise it continues to the maximum sample size. The function returns the design's operating characteristics: the probability of each decision, the distribution of stopping times, the expected sample size, and the average effect estimate at early success stops (a direct measure of optional stopping exaggeration).
This complements brms_inla_power() (fixed-n designs) and is not the
same as brms_inla_power_sequential(), which adaptively stops the Monte
Carlo simulation itself rather than simulating sequential trials.
Because Bayesian posterior quantities obey the likelihood principle, the interpretation of the final posterior is unaffected by the stopping rule; the purpose of this simulation is to quantify the frequency properties of the design (false-go rate, expected sample size, estimate exaggeration), which do depend on the stopping rule.
brms_inla_sequential_trial(
design = NULL,
formula = NULL,
family = gaussian(),
family_control = NULL,
priors = NULL,
data_generator = NULL,
effect_name = NULL,
true_effect = 0.5,
looks = NULL,
nsims = 200,
metric = c("direction", "threshold", "rope"),
alternative = c("greater", "less"),
prob_success = 0.95,
prob_futility = NULL,
effect_threshold = 0,
rope_bounds = NULL,
credible_level = 0.95,
error_sd = 1,
group_sd = 0.5,
obs_per_group = 10,
predictor_means = NULL,
predictor_sds = NULL,
seed = 123,
inla_num_threads = NULL,
family_args = list(),
progress = c("auto", "text", "none")
)A list of class "powerbrmsINLA_seq_trial" with components:
results: one row per simulated trial (scenario, true effect,
decision, stopping n and look, posterior estimate at stopping).
summary: operating characteristics per scenario (see Details).
look_summary: per-look stopping distribution per scenario.
diagnostics: failed/warned INLA fits per scenario.
settings: a record of all design parameters.
Optional "powerbrmsINLA_seq_design" object from
sequential_design(). When supplied, it overrides formula, family,
priors, effect_name, metric, alternative, looks,
prob_success, prob_futility, effect_threshold, rope_bounds, and
credible_level, so the simulated operating characteristics correspond
exactly to the design that will be monitored with
sequential_analysis().
Model formula (brms syntax; random effects supported).
Response family, e.g. gaussian(), binomial().
Optional INLA control.family list; takes precedence
over translated priors, as in brms_inla_power().
Optional brms prior specification, translated via the
built-in prior bridge (see brms_inla_power()).
Optional function(n, effect) returning a data frame
with n rows ordered by accrual time (see Details). Defaults to the
package's automatic generator.
Single character: the primary (monitored) effect.
Either a numeric vector of fixed true-effect scenarios
(conditional sequential power per value), or a design-prior list such as
list(dist = "normal", mean = 0.5, sd = 0.15), in which case a fresh
true effect is drawn for every simulated trial and the resulting success
proportion is the design's sequential assurance.
Increasing integer vector of cumulative sample sizes (total
observations, the same units as sample_sizes in brms_inla_power())
at which interim analyses occur. The last element is the maximum n.
Number of simulated trials per scenario.
"direction", "threshold", or "rope".
"greater" or "less"; the prespecified direction for
the direction/threshold metrics. Ignored for "rope".
Scalar or length(looks) vector of stop-for-success
posterior probability thresholds (default 0.95).
Scalar or length(looks) vector of stop-for-futility
thresholds, or NULL (default) to disable futility stopping. Ignored
with a warning for metric = "rope".
Threshold for metric = "threshold" (on the model
coefficient scale; use a negative value with alternative = "less").
Length-2 numeric vector for metric = "rope".
Credible level used for the reported interval widths.
Scalar or distributional list, as in
brms_inla_power(). With a distributional specification a fresh value is
drawn once per simulated trial (a trial has one true nuisance value;
it does not change between looks).
Passed to the automatic
data generator (see brms_inla_power()).
Integer seed.
INLA threads ("outer:inner"); auto-detected if NULL.
Named list of family-specific arguments for the automatic generator.
"auto", "text", or "none".
Accrual model. For each simulated trial one dataset of the maximum size
is generated, and the analysis at a look of size n uses its first n
rows, so the data genuinely accumulate across looks. With the automatic
data generator, rows are exchangeable given the random effects (grouping
factors cycle across rows), which corresponds to all clusters recruiting in
parallel while observations accumulate within them. For a different accrual
pattern (for example, whole clusters arriving one at a time), supply a
custom data_generator whose rows are ordered by accrual time.
Decision rules. Let pr be the posterior probability of the
prespecified alternative at a look (computed, as elsewhere in the package,
from a Normal approximation to the INLA fixed-effect posterior):
metric = "direction": pr = P(effect > 0 | data) (or < 0 when
alternative = "less").
metric = "threshold": pr = P(effect > effect_threshold | data)
(or < when alternative = "less").
metric = "rope": two probabilities are monitored; the trial stops
for "success" when P(outside ROPE) >= prob_success and for
"equivalence" when P(inside ROPE) >= prob_success.
For the direction and threshold metrics the trial stops for success when
pr >= prob_success and for futility when pr <= prob_futility (futility
stopping is disabled when prob_futility = NULL). prob_success and
prob_futility may be vectors of length(looks) to implement stricter
early thresholds (O'Brien-Fleming-like behaviour).
What to report. summary contains, per scenario: p_success,
p_futility, p_equivalence, p_inconclusive, expected_n,
p_stop_early, and mean_est_at_success next to mean_true_at_success
(their difference estimates the exaggeration of effect estimates caused by
early stopping). Under true_effect containing 0, p_success is the
false-go rate of the design.
if (FALSE) {
looks <- c(40, 80, 120, 160, 200)
# Conditional sequential power at fixed true effects (0 = false-go rate)
seq_fixed <- brms_inla_sequential_trial(
formula = y ~ treatment,
effect_name = "treatment",
true_effect = c(0, 0.5),
looks = looks,
nsims = 200,
metric = "threshold",
effect_threshold = 0.2,
prob_success = 0.95,
prob_futility = 0.05,
seed = 123
)
print(seq_fixed)
# Sequential assurance: draw the true effect from a design prior
seq_assur <- brms_inla_sequential_trial(
formula = y ~ treatment,
effect_name = "treatment",
true_effect = list(dist = "normal", mean = 0.5, sd = 0.15),
looks = looks,
nsims = 200,
metric = "threshold",
effect_threshold = 0.2,
prob_futility = 0.05,
seed = 123
)
print(seq_assur)
}
Run the code above in your browser using DataLab