run_trials {adaptr} | R Documentation |
Simulate multiple trials
Description
This function conducts multiple simulations using a trial specification as
specified by setup_trial()
, setup_trial_binom()
or setup_trial_norm()
.
This function essentially manages random seeds and runs multiple simulation
using run_trial()
- additional details on individual simulations are
provided in that function's description. This function allows simulating
trials in parallel using multiple cores, automatically saving and re-loading
saved objects, and "growing" already saved simulation files (i.e., appending
additional simulations to the same file).
Usage
run_trials(
trial_spec,
n_rep,
path = NULL,
overwrite = FALSE,
grow = FALSE,
cores = NULL,
base_seed = NULL,
sparse = TRUE,
progress = NULL,
version = NULL,
compress = TRUE,
export = NULL,
export_envir = parent.frame()
)
Arguments
trial_spec |
|
n_rep |
single integer; the number of simulations to run. |
path |
single character string; if specified (defaults to |
overwrite |
single logical; defaults to |
grow |
single logical; defaults to |
cores |
|
base_seed |
single integer or |
sparse |
single logical, as described in |
progress |
single numeric |
version |
passed to |
compress |
passed to |
export |
character vector of names of objects to export to each
parallel core when running in parallel; passed as the |
export_envir |
|
Details
Exporting objects when using multiple cores
If setup_trial()
is used to define a trial specification with custom
functions (in the fun_y_gen
, fun_draws
, and fun_raw_est
arguments of
setup_trial()
) and run_trials()
is run with cores > 1
, it is necessary
to export additional functions or objects used by these functions and defined
by the user outside the function definitions provided. Similarly, functions
from external packages loaded using library()
or require()
must be
exported or called prefixed with the namespace, i.e., package::function
.
The export
and export_envir
arguments are used to export objects calling
the parallel::clusterExport()
-function. See also setup_cluster()
, which
may be used to setup a cluster and export required objects only once per
session.
Value
A list of a special class "trial_results"
, which contains the
trial_results
(results from all simulations; note that seed
will be
NULL
in the individual simulations), trial_spec
(the trial
specification), n_rep
, base_seed
, elapsed_time
(the total simulation
run time), sparse
(as described above) and adaptr_version
(the version
of the adaptr
package used to run the simulations). These results may be
extracted, summarised, and plotted using the extract_results()
,
check_performance()
, summary()
, print.trial_results()
,
plot_convergence()
, check_remaining_arms()
, plot_status()
, and
plot_history()
functions. See the definitions of these functions for
additional details and details on additional arguments used to select arms
in simulations not ending in superiority and other summary choices.
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 10 simulations with a specified random base seed
res <- run_trials(binom_trial, n_rep = 10, base_seed = 12345)
# See ?extract_results, ?check_performance, ?summary and ?print for details
# on extracting resutls, summarising and printing