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,
n_workers = 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().
n_workersinteger. Number of parallel workers. When
n_workers = 1 (default), replicates are run sequentially.
When n_workers > 1, replicates are distributed across
parallel workers using the mirai package, which must be
installed separately. Each worker receives a serialized copy of
the trial and listener objects and runs its share of replicates
independently. If any replicate encounters an error, execution
stops and already-collected results are preserved in
$get_output(). To debug, manually set seed in
trial() and n_workers = 1 in run() for reproduced
results. Note that optimal n_workers may not be
parallel::detectCores(). For example, Macbook with M1/M2/M3 chips
may have performance cores and efficiency cores. To achieve the best
parallel performance, one may want to use the performance cores only.
For a M1 laptop with 4 performance cores, n_workers = 3 may give
the best performance.
plot_eventlogical. Create event plot if TRUE. Forced to
FALSE when n > 1 or n_workers > 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.