save = TRUE to temporarily save the
simulation state. Function supports parallel and cluster computing,
global and local debugging, error handling (including fail-safe
stopping when functions fail too often, even across nodes), and is designed to be cross-platform.runSimulation(design, replications, generate, analyse, summarise,
fixed_objects = NULL, parallel = FALSE, packages = NULL,
ncores = parallel::detectCores(), MPI = FALSE, save = FALSE,
save_results = FALSE, save_generate_data = FALSE, filename = NULL,
max_errors = 50, include_errors = TRUE, seed = NULL,
save_details = list(), edit = "none", verbose = TRUE)data.frame object containing the Monte Carlo simulation conditions to
be studied, where each row represents a unique conditiondesign).
Must be greater than 0generate for detailssummarise for detailslist)
containing additional user-defined objects
that should remain fixed across conditions. This is useful when including
long fixed vectors of population parameters, data
that should be used across all conditparallel package over each
unique condition?c('MASS', 'mvtnorm', 'simsem') ). Use this input when parallel = TRUE or
MPI = TRUE to use non-standard functions from additional packagforeach package in a form usable by MPI to run simulation
in parallel on a cluster? Default is FALSETRUE, a temp file
will be created in the working directory which allows the simulation state to be saved
and ranalyse to external
.rds files located in the defined save_results_dirname directory/folder?
Use this if you would like to keep track of thegenerate to external .rds files
located in the defined save_generate_data_dirname directory/folder?
It is generally recommended to leave this .rds file to save the final simulation results to.
When NULL the final simulation object is not saved to the drive. As well,
if the same file name already exists in the working directy at the time of saving then aTRUE, this information will be stacked at the end
of the returned simulation results with the name of the specific error used as the column name in the
data.frame objedesign.
This argument calls set.seed or
save, save_results, or save_generate_data are triggered.[object Object],[object Object],[object Object],[object Object],[object Ob
browser() call for editing and debugging.
General options are 'none' (default) and 'all', which are used
to disable debugging and to debug all the user defined functions, rTRUEdata.frame (also of class 'SimDesign')
with the original design conditions in the left-most columns,
simulation results in the middle columns, additional information (such as REPLICATIONS and SIM_TIME),
to the right of the results, and ERROR_MESSAGE's in the right-most columnssave = TRUE was used
then the original code in
the main source file need only be rerun again to resume the simulation.
The saved temp file will be read into the function, and the simulation will continue where it left
off before the simulation was terminated. Upon completion, a data.frame with the simulation
will be returned in the R session. If specified, an .rds file may also be saved
to the hard-drive if a suitable filename argument was included.
Finally, to save the complete list of results returned
from analyse to unique files use save_results = TRUE.[object Object],[object Object],[object Object],[object Object]
For a skeleton version of the work-flow which may be useful when initially defining a simulation,
see SimDesign_functions. This function will write the template of the simulation
to one/two files so that modifying the respective functions and objects can begin immediately and
with minimal error. This means that you can focus on your Monte Carlo simulation right away rather
than worry about the administrative work required to organize the code.
Additional information for each condition are also returned:
REPLICATIONS to indicate the number of Monte Carlo replications,
SIM_TIME to indicate how long (in seconds) it took to complete
all the Monte Carlo replications for each respective condition, SEED if the seed argument
was used, and, if include_errors = TRUE,
columns containing the number of replications due to try() errors where the error messages
represent the names of the columns prefixed with a ERROR_MESSAGE string.
Note that when running simulations in parallel (either with parallel = TRUE or MPI = TRUE)
R objects defined in the global environment will not be visible across nodes. Hence, you may see errors
such as Error: object 'something' not found. To avoid this, simply pass additional objects to the
fixed_objects input (usually it's convenient to supply a named list of these objects).
Fortunately, however, custom functions defined in the global environment are exported across
nodes automatically. This makes it convenient when writing code because custom functions will
always be available across nodes if they are visible in the R workspace.
Additional examples, presentation files, and tutorials can be found on the package wiki located at