aggregate_simulations: Collapse separate simulation files into a single result

Description

This function aggregates the results from SimDesign's runSimulation into a single objects suitable for post-analyses, or combines all the saved results directories and combines them into one. This is useful when results are run piecewise on one node (e.g., 500 replications in one batch, 500 again at a later date) or run independently across different nodes/computers that are not on the same network.

Usage

aggregate_simulations(
  files = NULL,
  filename = NULL,
  dirs = NULL,
  results_dirname = "SimDesign_aggregate_results",
  select = NULL,
  check.only = FALSE,
  target.reps = NULL
)

Value

if files is used the function returns a data.frame/tibble with the (weighted) average of the simulation results. Otherwise, if dirs is used, the function returns NULL

Arguments

files: a character vector containing the names of the simulation's final .rds files
filename: (optional) name of .rds file to save aggregate simulation file to. If not specified then the results will only be returned in the R console
dirs: a character vector containing the names of the save_results directories to be aggregated. A new folder will be created and placed in the results_dirname output folder
results_dirname: the new directory to place the aggregated results files
select: a character vector indicating columns to variables to select from the SimExtract(what='results') information. This is mainly useful when RAM is an issue given simulations with many stored estimates. Default includes the results objects in their entirety, though to omit all internally stored simulation results pass the character 'NONE'
check.only: logical; for larger simulations file sets, such as those generated by runArraySimulation, return the design conditions that do no satisfy the target.reps
target.reps: (optional) number of replications to check against to evaluate whether the simulation files returned the desired number of replications. If missing, the highest detected value from the collected set of replication information will be used

Author

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. tools:::Rd_expr_doi("10.20982/tqmp.16.4.p248")