Template-based generation of the Generate-Analyse-Summarise functions

This function prints template versions of the required Design and Generate-Analyse-Summarise functions for SimDesign to run simulations. Templated output comes complete with the correct inputs, class of outputs, and optional comments to help with the initial definitions. Use this at the start of your Monte Carlo simulation study. Following the definition of the SimDesign template file please refer to detailed the information in runSimulation for how to edit this template to make a working simulation study.

Usage

SimFunctions(
  filename = NULL,
  dir = getwd(),
  save_structure = "single",
  extra_file = FALSE,
  nAnalyses = 1,
  nGenerate = 1,
  summarise = TRUE,
  comments = FALSE,
  openFiles = TRUE,
  spin_header = TRUE,
  SimSolve = FALSE
)

Arguments

filename: a character vector indicating whether the output should be saved to two respective files containing the simulation design and the functional components, respectively. Using this option is generally the recommended approach when beginning to write a Monte Carlo simulation
dir: the directory to write the files to. Default is the working directory
save_structure: character indicating the number of files to break the simulation code into when filename is included (default is 'single' for one file). When save_structure = 'double' the output is saved to two separate files containing the functions and design definitions, and when save_structure = 'all' the generate, analyse, summarise, and execution code area all saved into separate files. The purpose for this structure is because multiple structured files often makes organization and debugging slightly easier larger Monte Carlo simulations, though in principle all files could be stored into a single R script
extra_file: logical; should an extra file be saved containing user-defined functions or objects? Default is FALSE
nAnalyses: number of analysis functions to create (default is 1). Increasing the value of this argument when independent analysis are being performed allows function definitions to be better partitioned and potentially more modular
nGenerate: number of generate functions to create (default is 1). Increase the value of this argument when when the data generation functions are very different and should be isolated from each other (otherwise, if there is much in common between the generate steps, the default of 1 should be preferred). Otherwise, if nGenerate == 0 then no generate function will be provided and instead this data-generation step can be defined in the analysis function(s) (only recommended for smaller simulations)
summarise: include summarise function? Default is TRUE
comments: logical; include helpful comments? Default is FALSE
openFiles: logical; after files have been generated, open them in your text editor (e.g., if Rstudio is running the scripts will open in a new tab)?
spin_header: logical; include a basic knitr::spin header to allow the simulation to be knitted? Default is TRUE. For those less familiar with spin documents see https://bookdown.org/yihui/rmarkdown-cookbook/spin.html for further details
SimSolve: logical; should the template be generated that is intended for a SimSolve implementation? Default is FALSE

Details

The recommended approach to organizing Monte Carlo simulation files is to first save the template generated by this function to the hard-drive by passing a suitable filename argument (which, if users are interacting with R via the RStudio IDE, will also open the template file after it has been saved). For larger simulations, two separate files could also be used (achieved by changing out.files), and may be easier for debugging/sourcing the simulation code; however, this is a matter of preference and does not change any functionality in the package.

References

Chalmers, R. P., & Adkins, M. C. (2020). Writing Effective and Reliable Monte Carlo Simulations with the SimDesign Package. The Quantitative Methods for Psychology, 16(4), 248-280. doi:10.20982/tqmp.16.4.p248

Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte Carlo simulation. Journal of Statistics Education, 24(3), 136-156. doi:10.1080/10691898.2016.1246953

Author

Phil Chalmers rphilip.chalmers@gmail.com

Examples


SimFunctions()
#> #-------------------------------------------------------------------
#> 
#> library(SimDesign)
#> 
#> Design <- createDesign(factor1 = NA,
#>                        factor2 = NA)
#> 
#> #-------------------------------------------------------------------
#> 
#> Generate <- function(condition, fixed_objects) {
#>     dat <- data.frame()
#>     dat
#> }
#> 
#> Analyse <- function(condition, dat, fixed_objects) {
#>     ret <- nc(stat1 = NaN, stat2 = NaN)
#>     ret
#> }
#> 
#> Summarise <- function(condition, results, fixed_objects) {
#>     ret <- c(bias = NaN, RMSE = NaN)
#>     ret
#> }
#> 
#> #-------------------------------------------------------------------
#> 
#> res <- runSimulation(design=Design, replications=2, generate=Generate, 
#>                      analyse=Analyse, summarise=Summarise)
#> res
#> 
SimFunctions(comments = TRUE) #with helpful comments
#> #-------------------------------------------------------------------
#> 
#> library(SimDesign)
#> 
#> ### Define design conditions
#> Design <- createDesign(factor1 = NA,
#>                        factor2 = NA)
#> 
#> #-------------------------------------------------------------------
#> 
#> ### Define essential simulation functions
#> 
#> Generate <- function(condition, fixed_objects) {
#>     # Define data generation code ...
#> 
#>     # Return a vector, matrix, data.frame, or list
#>     dat <- data.frame()
#>     dat
#> }
#> 
#> Analyse <- function(condition, dat, fixed_objects) {
#>     # Run statistical analyses of interest ... 
#> 
#>     # Return a named vector or list
#>     ret <- nc(stat1 = NaN, stat2 = NaN)
#>     ret
#> }
#> 
#> Summarise <- function(condition, results, fixed_objects) {
#>     # Summarise the simulation results ...
#> 
#>     # Return a named vector of results
#>     ret <- c(bias = NaN, RMSE = NaN)
#>     ret
#> }
#> 
#> #-------------------------------------------------------------------
#> 
#> ### Run the simulation
#> res <- runSimulation(design=Design, replications=2, generate=Generate, 
#>                      analyse=Analyse, summarise=Summarise)
#> res
#> 

if (FALSE) { # \dontrun{

# write output files to a single file with comments
SimFunctions('mysim', comments = TRUE)

# Multiple analysis functions for optional partitioning
SimFunctions(nAnalyses = 2)
SimFunctions(nAnalyses = 3)

# Multiple analysis + generate functions
SimFunctions(nAnalyses = 2, nGenerate=2)

# save multiple files for the purpose of designing larger simulations
#  (also include extra_file for user-defined objects/functions)
SimFunctions('myBigSim', save_structure = 'all',
   nAnalyses = 3, nGenerate=2, extra_file = TRUE)


} # }