SimDesign: reSummarise – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

reSummarise

Run a summarise step for results that have been saved to the hard drive

Description

When runSimulation() uses the option save_results = TRUE the R replication results from the Generate-Analyse functions are stored to the hard drive. As such, additional summarise components may be required at a later time, whereby the respective .rds files must be read back into R to be summarised. This function performs the reading of these files, application of a provided summarise function, and final collection of the respective results.

Usage

reSummarise(
  summarise,
  dir = NULL,
  files = NULL,
  results = NULL,
  Design = NULL,
  fixed_objects = NULL,
  boot_method = "none",
  boot_draws = 1000L,
  CI = 0.95
)

Arguments

`summarise`	a summarise function to apply to the read-in files. See `runSimulation` for details
`dir`	directory pointing to the .rds files to be read-in that were saved from `runSimulation(..., save_results=TRUE)`. If `NULL`, it is assumed the current working directory contains the .rds files
`files`	(optional) names of files to read-in. If `NULL` all files located within `dir` will be used
`results`	(optional) the results of `runSimulation` when no `summarise` function was provided. Can be either a `matrix`, indicating that exactly one design condition was evaluated, or a `list` of `matrix` objects indicating that multiple conditions were performed with no summarise evaluation. Alternatively, if `store_results = TRUE` in the `runSimulation()` execution then the final SimDesign object may be passed, where the generate-analyse information will be extracted from the object instead
`Design`	(optional) if `results` input used, and design condition information important in the summarise step, then the original `design` object from `runSimulation` should be included
`fixed_objects`	(optional) see `runSimulation` for details
`boot_method`	method for performing non-parametric bootstrap confidence intervals for the respective meta-statistics computed by the `Summarise` function. See `runSimulation` for details
`boot_draws`	number of non-parametric bootstrap draws to sample for the `summarise` function after the generate-analyse replications are collected. Default is 1000
`CI`	bootstrap confidence interval level (default is 95%)

Author(s)

Phil Chalmers rphilip.chalmers@gmail.com

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

Examples

Design <- data.frame(N = c(10, 20, 30))

Generate <- function(condition, fixed_objects = NULL) {
    dat <- with(condition, rnorm(N, 10, 5)) # distributed N(10, 5)
    dat
}

Analyse <- function(condition, dat, fixed_objects = NULL) {
    ret <- mean(dat) # mean of the sample data vector
    ret
}

## Not run: 
# run the simulation
runSimulation(design=Design, replications=50,
              generate=Generate, analyse=Analyse,
              summarise=NA, save_results=TRUE,
              save_details = list(save_results_dirname='simresults'))

Summarise <- function(condition, results, fixed_objects = NULL){
    ret <- c(mu=mean(results), SE=sd(results))
    ret
}

res <- reSummarise(Summarise, dir = 'simresults/')
res

Summarise2 <- function(condition, results, fixed_objects = NULL) {
    mean(results)
}

res2 <- reSummarise(Summarise2, dir = 'simresults/')
res2

SimClean('simresults/')


## End(Not run)

###
# similar to above, but using objects defined in workspace
results <- runSimulation(design=Design, replications=50,
                         generate=Generate, analyse=Analyse)
str(results)

Summarise <- function(condition, results, fixed_objects = NULL){
    ret <- c(mu=mean(results), SE=sd(results))
    ret
}

res <- reSummarise(Summarise, results=results, Design=Design)
res

res <- reSummarise(Summarise, results=results, boot_method = 'basic')
res

###
# Also similar, but storing the results within the summarised simulation

Summarise <- function(condition, results, fixed_objects = NULL){
    ret <- c(mu=mean(results), SE=sd(results))
    ret
}

res <- runSimulation(design=Design, replications=50, store_results = TRUE,
                     generate=Generate, analyse=Analyse, summarise=Summarise)
res

# internal results stored
results <- SimExtract(res, what = 'results')
str(results)

# pass SimDesign object to results
res <- reSummarise(Summarise, results=res, boot_method = 'basic')
res

SimDesign

Structure for Organizing Monte Carlo Simulation Designs

v2.3

GPL (>= 2)

Authors

Phil Chalmers [aut, cre] (<https://orcid.org/0000-0001-5332-2810>), Matthew Sigal [ctb], Ogreden Oguzhan [ctb]

Initial release