other touchups

Author: philchalmers

vignettes/Catch_errors.Rmd

@@ -107,7 +107,7 @@ SimExtract(result, what = 'errors')
 
 
 
-Finally, `SimDesign` has a built-in safety feature controlled by with `max_errors` argument to avoid getting stuck in infinite redrawing loops. By default, if more than 50 errors are consecutively returned then the simulation condition will be halted, and a warning message will be printed to the console indicating the last observed fatal error. These safety features are built-in because too many consecutive `stop()` calls generally indicates a major problem in the simulation code which should be fixed before continuing. However, when encountering fatal errors in a given simulation condition the remainder of the simulation experiment will still be executed as normal, where for the problematic conditions combinations `NA` placeholders will be assigned to these rows in the final output object. This is so that the entire experiment does not unexpectedly terminate due to one or more problematic row conditions in `Design`, and instead these conditions can be inspected and debugged at a later time. Of course, if inspecting the code directly, the simulation could be manually halted so that these terminal errors can be attended to immediately (e.g., using `Ctrl + c`, or clicking the 'Stop' icon in Rstudio).
+Finally, `SimDesign` has a built-in safety feature controlled by with `max_errors` argument to avoid getting stuck in infinite redrawing loops. By default, if more than 50 errors are consecutively returned then the simulation condition will be halted, and a warning message will be printed to the console indicating the last observed fatal error. These safety features are built-in because too many consecutive `stop()` calls generally indicates a major problem in the simulation code which should be fixed before continuing. However, when encountering fatal errors in a given simulation condition the remainder of the simulation experiment will still be executed as normal, where for the problematic conditions`NA` placeholders will be assigned to these rows in the final output object. This is so that the entire experiment does not unexpectedly terminate due to one or more problematic row conditions in `Design`, and instead these conditions can be inspected and debugged all at once at a later time. Of course, if inspecting the code directly, the simulation could be manually halted so that these terminal errors can be attended to immediately (e.g., using `Ctrl + c`, or clicking the 'Stop' icon in Rstudio).
 
 # What to do (explicit debugging)
 
@@ -146,9 +146,9 @@ runSimulation(Design, replications = 100, load_seed=picked_seed, debug='analyse-
               generate=Generate, analyse=Analyse, summarise=Summarise)
 ```
 
-The `.Random.seed` state will be loaded at this exact state, and will always be related at this state as well (in case `c` is typed in the debugger, or somehow the error is harder to find while walking through the debug mode). Hence, users must type `Q` to exit the debugger after they have better understood the nature of the error message first-hand. 
+The `.Random.seed` state will be loaded at this exact state, and will always be repeated at this state as well (in case `c` is typed in the debugger, or somehow the error is harder to find while walking through the debug mode). Hence, users must type `Q` to exit the debugger after they have better understood the nature of the error message first-hand, after which the `load_seed` input should be removed. 
 
-# Converting warings to errors explicitly
+# Converting warings to errors explicitly via `manageWarnings()`
 
 ```{r include=FALSE}
 knitr::opts_chunk$set(

vignettes/Fixed_obj_fun.Rmd

@@ -30,7 +30,7 @@ par(mar=c(3,3,1,1)+.1)
 
 # Including fixed objects
 
-R is fun language for computer programming and statistics, but it's not without it's quirks. For instance, R generally has a recursive strategy when attempting to find objects within functions. If an object can't be found, R will start to look outside the function's environment to see if the object can be located there, and if not, look within even higher-level environments... This recursive search continues until it searches for the object in the user workspace/Global environment, and only when the object can't be found here will an error be thrown. This is a strange feature to most programmers who come from other languages, and when writing simulations may cause some severely unwanted issues. This tutorial demonstrates how to make sure all required user-defined objects are visible to `SimDesign`. 
+R is fun language for computer programming and statistics, but it's not without it's quirks. For instance, R generally has a recursive strategy when attempting to find objects within functions. If an object can't be found, R will start to look outside the function's environment to see if the object can be located there, and if not, look within even higher-level environments... This recursive search continues until it searches for the object in the user workspace/Global environment, and only when the object can't be found here will an error be thrown. This is a strange feature to most programmers who come from other languages, and when writing simulations may cause some severely unwanted masking issues. This tutorial demonstrates how to make sure all required user-defined objects are visible to `SimDesign`. 
 
 # Scoping
 
@@ -76,17 +76,17 @@ clusterExport(cl=cl, c('obj1', 'obj2'))
 parSapply(cl=cl, 1:4, myfun)
 ```
 
-The same reasoning above applies to functions defined in the R workspace as well, including functions defined within external R packages. Hence, in order to use functions from other packages they must either be explicitly loaded with `require()` or `library()` within the distributed code, or referenced via their Namespace with the `::` operator (e.g., `mvtnorm::rmvtnorm()`).
+The same reasoning above applies to functions defined in the R work-space as well, including functions defined within third-party R packages. Hence, in order to use functions from other packages they must either be explicitly loaded with `require()` or `library()` within the distributed code, or referenced via their Namespace with the `::` operator (e.g., `mvtnorm::rmvtnorm()`).
 
 ```{r echo=FALSE}
 stopCluster(cl)
 ```
 
-# Exporting objects example 
+# Exporting objects example in `SimDesign`
 
 In order to make objects safely visible in `SimDesign` the strategy is very simple: wrap all desired objects into a named list (or other object), and pass this to the `fixed_objects` argument. From here, elements can be indexed using the `$` operator or `with()` function, or whatever other method may be convenient. Note, however, this is only required for defined *objects* not *functions* --- `SimDesign` automatically makes user-defined functions available across all nodes.
 
-As an aside, an alternative approach is simply to define/source the objects within the respective `SimDesign` functions; that way they will clearly be visible at runtime. The following `fixed_objects` approach is really only useful when the defined objects contain a large amount of code.
+As an aside, an alternative approach is simply to define/source the objects within the respective `SimDesign` functions; that way they will clearly be visible at run-time. The following `fixed_objects` approach is really only useful when the defined objects contain a large amount of code.
 
 ```{r}
 library(SimDesign)

vignettes/Saving-results.Rmd

@@ -131,10 +131,10 @@ SimClean('my-simple-sim.rds')
 Notice that when complete, the temporary file is removed from the hard-drive.
 
 Relatedly, the `.Random.seed` states for each successful replication can be saved by passing
-`control = list(store_Random.seeds = TRUE))` to \code{runSimulation}, though these are generally only useful
+`control = list(store_Random.seeds = TRUE))` to `runSimulation()`, though these are generally only useful
 under exceptional circumstances (e.g., when the generate-analyse results are unusual but did not throw a warning or error message, yet should be inspected interactively).
 
-# `store_results` (`TRUE` by default, though not recommended if RAM is suspected to be an issue)
+# `store_results` (`TRUE` by default)
 
 Passing `store_results = TRUE` stores the `results` object information that are passed to `Summarise()` in the returned object. This allows for further inspection of the simulation results, and potential to use functions such as `reSummarise()` to provide meta-summaries of the simulation at a later time.  After the simulation is complete, these results can be extracted using `SimResults(res)` (or more generally with `SimExtract(res, what = 'results')`). For example,
 
@@ -148,7 +148,7 @@ results
 
 Note that this should be used if the number of replications/`design` conditions is small enough to warrant such storage; otherwise, the R session may run out of memory (RAM) as the simulation progresses. Otherwise, `save_results = TRUE` described below is the recommended approach to resolve potential memory issues. 
 
-# Option: `save_results = TRUE` (`FALSE` by default; recommended during official simulation run if RAM is an issue)
+# Option: `save_results = TRUE` (`FALSE` by default; set to `TRUE` if RAM is an issue)
 
 Finally, the `save_results` argument will output the `results` elements that were passed to `Summarise()` to separate `.rds` files containing all the analysis results and `condition` information. This option is supported primarily for simulations that are anticipated to have memory storage issues, where the results are written to the hard-drive and released from memory. Note that when using `save_results` the `save` flag is automatically set to `TRUE` to ensure that the simulation state is correctly tracked.
 
@@ -196,5 +196,7 @@ SimClean(results = TRUE)
 
 # Recommendations
 
-My general recommendation when running simulations is to supply a `filename = 'some_simulation_name'` when your simulation is finally ready for run time (particularly for simulations which take a long time to finish), and to leave the default `save = TRUE` and `store_results = TRUE` to track any temporary files in the event of unexpected crashes and to store the `results` objects for future inspection (should the need arise). As the aggregation of the simulation results is often what you are interested in then this approach will ensure that the results are stored in a succinct manner for later analyses. However, if RAM is suspected to be an issue as the simulation progresses then using `save_results = TRUE` is strongly recommended to avoid memory-based storage issues.
+My general recommendation when running simulations is to supply a `filename = 'some_simulation_name'` when your simulation is finally ready for run time (particularly for simulations which take a long time to finish), and to leave the default `save = TRUE` and `store_results = TRUE` to track any temporary files in the event of unexpected crashes and to store the `results` objects for future inspection (should the need arise). As the aggregation of the simulation results is often what you are interested in then this approach will ensure that the results are stored in a succinct manner for later analyses. However, if RAM is suspected to be an issue as the simulation progresses then using `save_results = TRUE` is recommended to avoid memory-based storage issues.
+
+Note that for array simulations evaluated via `runArraySimulation()` the results will be stored within each respective `.rds` object using `store_results = TRUE` as files are independently saved on the assigned arrays, negating the implicit RAM issue that could arise when using `runSimulation()`.