setup_trial_norm {adaptr}  R Documentation 
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 normalnormal
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("Basicexamples", package = "adaptr")
) and the
Advanced example vignette
(vignette("Advancedexample", package = "adaptr")
).
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)),
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"
)
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 
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

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.
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.
# 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
# Squarerootbased, fixed control group allocation ratios
control_prob_fixed = "sqrtbased 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)