Create a class of controller to run a trial.
Public methods in this R6 class are used in developing this package. Thus, we have to export the whole R6 class which exposures all public methods. However, only the public methods in the list below are useful to end users.
$run()
$get_output()
$reset()
new()initialize a controller of the trial
Controllers$new(trial, listener)triala trial object returned from trial().
listenera listener object returned from listener().
get_listener()return listener in a controller.
Controllers$get_listener()
get_trial()return trial in a controller.
Controllers$get_trial()
mute()mute all messages (not including warnings).
Controllers$mute()silentlogical.
reset()reset the trial and listener registered to the controller before running
additional replicate of simulation. This is usually done between two
calls of controller$run().
Controllers$reset()
get_output()return a data frame of all current outputs saved by calling save().
Controllers$get_output(cols = NULL, simplify = TRUE, tidy = FALSE)colscharacter vector. Columns to be returned from the data frame
of simulation outputs. If NULL, all columns are returned.
simplifylogical. Return vector rather than a data frame of one
column when length(cols) == 1 and simplify == TRUE.
tidylogical. TrialSimulator automatically records a set
of standard outputs at milestones, even when doNothing is used
as action functions. These includes time of triggering milestones,
number of observed events for time-to-event endpoints, and number of
non-missing readouts for non-TTE endpoints
(see vignette('actionFunctions')). This usually mean a large
number of columns in outputs. If users have no intent to summarize a
trial on these columns, setting tidy = TRUE can eliminate these
columns from get_output(). This is useful to reduced the size of
output data frame when a large number of replicates are done for
simulation. Note that currently we use regex
"^n_events_<.*?>_<.*?>$" and
"^milestone_time_<.*?>$" to match columns to be eliminated.
If users plan to use tidy = TRUE, caution is needed when naming
custom outputs in save(). Default FALSE.
run()run trial simulation.
Controllers$run(n = 1, plot_event = TRUE, silent = FALSE, dry_run = FALSE)ninteger. Number of replicates of simulation.
n = 1 by default. Simulation results can be accessed by
controller$get_output().
plot_eventlogical. Create event plot if FALSE. Users
should set it to be FALSE if n > 1.
silentlogical. TRUE if muting all messages during a
trial. Note that warning messages are still displayed.
dry_runlogical. We are considering retire this argument.
TRUE if action function provided by users is
ignored and an internal default action .default_action is called
instead. This default function only locks data when the milestone is
triggered. Milestone time and number of endpoints' events or sample sizes
are saved. It is suggested to set dry_run = TRUE to estimate
distributions of triggering time and number of events before formally
using custom action functions if a fixed design is in use.
This helps determining planned maximum
information for group sequential design and reasonable time of milestone
of interest when planning a trial. Set it to FALSE for formal
simulations. However, for an adaptive design where arm(s) could
possibly be added or removed, setting dry_run to TRUE
is usually not helpful because adaption should be executed
before estimating the milestone time.
clone()The objects of this class are cloneable with this method.
Controllers$clone(deep = FALSE)deepWhether to make a deep clone.