setup_trial_norm {adaptr} | R Documentation |
Setup a trial specification using a continuous, normally distributed outcome
Description
Specifies the design of an adaptive trial with a continuous, normally
distributed outcome and validates all inputs. Uses normally distributed
posterior distributions for the mean values in each
trial arm; technically, no priors are used (as using normal-normal
conjugate prior models with extremely wide or uniform priors gives similar
results for these simple, unadjusted estimates). This corresponds to the use
of improper, flat priors, although not explicitly specified as such. Use
calibrate_trial()
to calibrate the trial specification to obtain a specific
value for a certain performance metric (e.g., the Bayesian type 1 error
rate). Use run_trial()
or run_trials()
to conduct single/multiple
simulations of the specified trial, respectively.
Note: add_info
as specified in setup_trial()
is set to the arms and
standard deviations used for trials specified using this function.
Further details: please see setup_trial()
. See setup_trial_binom()
for simplified setup of trials with binomially distributed binary outcomes.
For additional trial specification examples, see the the
Basic examples vignette
(vignette("Basic-examples", package = "adaptr")
) and the
Advanced example vignette
(vignette("Advanced-example", package = "adaptr")
).
Usage
setup_trial_norm(
arms,
true_ys,
sds,
start_probs = NULL,
fixed_probs = NULL,
min_probs = rep(NA, length(arms)),
max_probs = rep(NA, length(arms)),
rescale_probs = NULL,
data_looks = NULL,
max_n = NULL,
look_after_every = NULL,
randomised_at_looks = NULL,
control = NULL,
control_prob_fixed = NULL,
inferiority = 0.01,
superiority = 0.99,
equivalence_prob = NULL,
equivalence_diff = NULL,
equivalence_only_first = NULL,
futility_prob = NULL,
futility_diff = NULL,
futility_only_first = NULL,
highest_is_best = FALSE,
soften_power = 1,
cri_width = 0.95,
n_draws = 5000,
robust = FALSE,
description = "generic normally distributed outcome trial"
)
Arguments
arms |
character vector with unique names for the trial arms. |
true_ys |
numeric vector, simulated means of the outcome in all trial
|
sds |
numeric vector, true standard deviations (must be |
start_probs |
numeric vector, allocation probabilities for each arm at
the beginning of the trial. The default ( |
fixed_probs |
numeric vector, fixed allocation probabilities for each
arm. Must be either a numeric vector with |
min_probs |
numeric vector, lower threshold for adaptive allocation
probabilities; lower probabilities will be rounded up to these values. Must
be |
max_probs |
numeric vector, upper threshold for adaptive allocation
probabilities; higher probabilities will be rounded down to these values.
Must be |
rescale_probs |
|
data_looks |
vector of increasing integers, specifies when to conduct
adaptive analyses (= the total number of patients with available outcome
data at each adaptive analysis). The last number in the vector represents
the final adaptive analysis, i.e., the final analysis where superiority,
inferiority, practical equivalence, or futility can be claimed.
Instead of specifying |
max_n |
single integer, number of patients with available outcome data
at the last possible adaptive analysis (defaults to |
look_after_every |
single integer, specified together with |
randomised_at_looks |
vector of increasing integers or |
control |
single character string, name of one of the |
control_prob_fixed |
if a common |
inferiority |
single numeric value or vector of numeric values of the
same length as the maximum number of possible adaptive analyses, specifying
the probability threshold(s) for inferiority (default is |
superiority |
single numeric value or vector of numeric values of the
same length as the maximum number of possible adaptive analyses, specifying
the probability threshold(s) for superiority (default is |
equivalence_prob |
single numeric value, vector of numeric values of the
same length as the maximum number of possible adaptive analyses or |
equivalence_diff |
single numeric value ( |
equivalence_only_first |
single logical in trial specifications where
|
futility_prob |
single numeric value, vector of numeric values of the
same length as the maximum number of possible adaptive analyses or |
futility_diff |
single numeric value ( |
futility_only_first |
single logical in trial specifications designs
where |
highest_is_best |
single logical, specifies whether larger estimates of
the outcome are favourable or not; defaults to |
soften_power |
either a single numeric value or a numeric vector of
exactly the same length as the maximum number of looks/adaptive analyses.
Values must be between |
cri_width |
single numeric |
n_draws |
single integer, the number of draws from the posterior
distributions for each arm used when running the trial. Defaults to
|
robust |
single logical, if |
description |
character string, default is
|
Details
Because the posteriors used in this type of trial (with a generic,
continuous, normally distributed outcome) are by definition normally
distributed, FALSE
is used as the default value for the robust
argument.
Value
A trial_spec
object used to run simulations by run_trial()
or
run_trials()
. The output is essentially a list containing the input
values (some combined in a data.frame
called trial_arms
), but its class
signals that these inputs have been validated and inappropriate
combinations and settings have been ruled out. Also contains best_arm
,
holding the arm(s) with the best value(s) in true_ys
. Use str()
to
peruse the actual content of the returned object.
Examples
# Setup a trial specification using a continuous, normally distributed, desirable outcome
norm_trial <- setup_trial_norm(
arms = c("Control", "New A", "New B", "New C"),
true_ys = c(15, 20, 14, 13),
sds = c(2, 2.5, 1.9, 1.8), # SDs in each arm
max_n = 500,
look_after_every = 50,
control = "Control", # Common control arm
# Square-root-based, fixed control group allocation ratios
control_prob_fixed = "sqrt-based fixed",
# Desirable outcome
highest_is_best = TRUE,
soften_power = 0.5 # Limit extreme allocation ratios
)
# Print using 3 digits for probabilities
print(norm_trial, prob_digits = 3)