run_trial {adaptr}  R Documentation 
Simulate a single trial
Description
This function conducts a single trial simulation using a trial specification
as specified by setup_trial()
, setup_trial_binom()
or
setup_trial_norm()
.
During simulation, the function randomises "patients", randomly generates
outcomes, calculates the probabilities that each arm
is the best (and
better than the control, if any). This is followed by checking inferiority,
superiority, equivalence and/or futility as desired; dropping arms, and
readjusting allocation probabilities according to the criteria specified in
the trial specification. If there is no common control
arm, the trial
simulation will be stopped at the final specified adaptive analysis, when 1
arm is superior to the others, or when all arms are considered equivalent (if
equivalence is assessed). If a common control
arm is specified, all other
arms will be compared to that, and if 1 of these pairwise comparisons crosses
the applicable superiority threshold at an adaptive analysis, that arm will
become the new control and the old control will be considered inferior and
dropped. If multiple noncontrol arms cross the applicable superiority
threshold in the same adaptive analysis, the one with the highest probability
of being the overall best will become the new control. Equivalence/futility
will also be checked if specified, and equivalent or futile arms will be
dropped in designs with a common control
arm and the entire trial will be
stopped if all remaining arms are equivalent in designs without a common
control
arm. The trial simulation will be stopped when only 1 arm is left,
when the final arms are all equivalent, or after the final specified adaptive
analysis.
After stopping (regardless of reason), a final analysis including outcome
data from all patients randomised to all arms will be conducted (with the
final control
arm, if any, used as the control
in this analysis).
Results from this analysis will be saved, but not used with regards to the
adaptive stopping rules. This is particularly relevant if less patients have
available outcome data at the last adaptive analyses than the total number of
patients randomised (as specified in setup_trial()
, setup_trial_binom()
,
or setup_trial_norm()
), as the final analysis will then include all
patients randomised, which may be more than in the last adaptive analysis
conducted.
Usage
run_trial(trial_spec, seed = NULL, sparse = FALSE)
Arguments
trial_spec 

seed 
single integer or 
sparse 
single logical; if 
Value
A trial_result
object containing everything listed below if
sparse
(as described above) is FALSE
. Otherwise only final_status
,
final_n
, followed_n
, trial_res
, seed
, and sparse
are included.

final_status
: either"superiority"
,"equivalence"
,"futility"
, or"max"
(stopped at the last possible adaptive analysis), as calculated during the adaptive analyses. 
final_n
: the total number of patients randomised. 
followed_n
: the total number of patients with available outcome data at the last adaptive analysis conducted. 
max_n
: the prespecified maximum number of patients with outcome data available at the last possible adaptive analysis. 
max_randomised
: the prespecified maximum number of patients randomised at the last possible adaptive analysis. 
looks
: numeric vector, the total number of patients with outcome data available at each conducted adaptive analysis. 
planned_looks
: numeric vector, the cumulated number of patients planned to have outcome data available at each adaptive analysis, even those not conducted if the simulation is stopped before the final possible analysis. 
randomised_at_looks
: numeric vector, the cumulated number of patients randomised at each conducted adaptive analysis (only including the relevant numbers for the analyses actually conducted). 
start_control
: character, initial commoncontrol
arm (if specified). 
final_control
: character, final commoncontrol
arm (if relevant). 
control_prob_fixed
: fixed commoncontrol
arm probabilities (if specified; seesetup_trial()
). 
inferiority
,superiority
,equivalence_prob
,equivalence_diff
,equivalence_only_first
,futility_prob
,futility_diff
,futility_only_first
,highest_is_best
, andsoften_power
: as specified insetup_trial()
. 
best_arm
: the bestarm
(s), as described insetup_trial()
. 
trial_res
: adata.frame
containing most of the information specified for each arm insetup_trial()
includingtrue_ys
(true outcomes as specified insetup_trial()
) and for each arm the sum of the outcomes (sum_ys
/sum_ys_all
; i.e., the total number of events for binary outcomes or the totals of continuous outcomes) and sum of patients (ns
/ns_all
), summary statistics for the raw outcome data (raw_ests
/raw_ests_all
, calculated as specified insetup_trial()
, defaults to mean values, i.e., event rates for binary outcomes or means for continuous outcomes) and posterior estimates (post_ests
/post_ests_all
,post_errs
/post_errs_all
,lo_cri
/lo_cri_all
, andhi_cri
/hi_cri_all
, calculated as specified insetup_trial()
),final_status
of each arm ("inferior"
,"superior"
,"equivalence"
,"futile"
,"active"
, or"control"
(currently active control arm, including if the current control when stopped for equivalence)),status_look
(specifying the cumulated number of patients with outcome data available when an adaptive analysis changed thefinal_status
to"superior"
,"inferior"
,"equivalence"
, or"futile"
),status_probs
, the probability (in the last adaptive analysis for each arm) that each arm was the best/better than the common control arm (if any)/equivalent to the common control arm (if any and stopped for equivalence;NA
if the control arm was stopped due to the last remaining other arm(s) being stopped for equivalence)/futile if stopped for futility at the last analysis it was included in,final_alloc
, the final allocation probability for each arm the last time patients were randomised to it, including for arms stopped at the maximum sample size, andprobs_best_last
, the probabilities of each remaining arm being the overall best in the last conducted adaptive analysis (NA
for previously dropped arms).
Note: for the variables in thedata.frame
where a version including the_all
suffix is included, the versions WITHOUT this suffix are calculated using patients with available outcome data at the time of analysis, while the versions WITH the_all
suffixes are calculated using outcome data for all patients randomised at the time of analysis, even if they have not reached the time of followup yet (seesetup_trial()
). 
all_looks
: a list of lists containing one list per conducted trial look (adaptive analysis). These lists contain the variablesarms
,old_status
(status before the analysis of the current round was conducted),new_status
(as specified above, status after current analysis has been conducted),sum_ys
/sum_ys_all
(as described above),ns
/ns_all
(as described above),old_alloc
(the allocation probability used during this look),probs_best
(the probabilities of each arm being the best in the current adaptive analysis),new_alloc
(the allocation probabilities after updating these in the current adaptive analysis; NA for all arms when the trial is stopped and no further adaptive analyses will be conducted),probs_better_first
(if a common control is provided, specifying the probabilities that each arm was better than the control in the first analysis conducted during that look),probs_better
(asprobs_better_first
, but updated if another arm becomes the new control),probs_equivalence_first
andprobs_equivalence
(as forprobs_better
/probs_better_first
, but for equivalence if equivalence is assessed). The last variables areNA
if the arm was not active in the applicable adaptive analysis or if they would not be included during the next adaptive analysis. 
allocs
: a character vector containing the allocations of all patients in the order of randomization. 
ys
: a numeric vector containing the outcomes of all patients in the order of randomization (0
or1
for binary outcomes). 
seed
: the random seed used, if specified. 
description
,add_info
,cri_width
,n_draws
,robust
: as specified insetup_trial()
,setup_trial_binom()
orsetup_trial_norm()
. 
sparse
: single logical, corresponding to thesparse
input.
Examples
# Setup a trial specification
binom_trial < setup_trial_binom(arms = c("A", "B", "C", "D"),
true_ys = c(0.20, 0.18, 0.22, 0.24),
data_looks = 1:20 * 100)
# Run trial with a specified random seed
res < run_trial(binom_trial, seed = 12345)
# Print results with 3 decimals
print(res, digits = 3)