use SimRead instead

Author: philchalmers

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: SimDesign
 Title: Structure for Organizing Monte Carlo Simulation Designs
-Version: 2.24.1
+Version: 2.24.2
 Authors@R: c(person("Phil", "Chalmers", email = "rphilip.chalmers@gmail.com", role = c("aut", "cre"),
                     comment = c(ORCID="0000-0001-5332-2810")),
              person("Matthew", "Sigal", role = c("ctb")),

NAMESPACE

@@ -42,6 +42,7 @@ export(SimClean)
 export(SimCollect)
 export(SimExtract)
 export(SimFunctions)
+export(SimRead)
 export(SimResults)
 export(SimShiny)
 export(SimSolve)

NEWS.md

@@ -2,7 +2,10 @@
 
 ## Changes in SimDesign 2.25
 
-- Temp files now stored using `qs2` package to reduce overhead (see #83)
+- Temp files and other frequently hard-drive written objects 
+  now stored using `qs2` package to reduce overhead (see #83). Relatedly,
+  the function `SimRead()` has been included to read in the stored object,
+  switching between `qs2::qd_read()` and `readRDS()` where applicable
 
 
 ## Changes in SimDesign 2.24

R/SimResults.R

@@ -2,10 +2,11 @@
 #'
 #' If \code{\link{runSimulation}} was passed the flag \code{save_results = TRUE} then the
 #' row results corresponding to the \code{design} object will be stored to a suitable
-#' sub-directory as individual \code{.rds} files. While users could use \code{\link{readRDS}} directly
+#' sub-directory as individual \code{.rds} or \code{qs2} files.
+#' While users could use \code{\link{readRDS}} and \code{qs2} directly
 #' to read these files in themselves, this convenience function will read the desired rows in
 #' automatically given the returned object
-#' from the simulation. Can be used to read in 1 or more \code{.rds} files at once (if more than 1 file
+#' from the simulation. Can be used to read in 1 or more files at once (if more than 1 file
 #' is read in then the result will be stored in a list).
 #'
 #' @param obj object returned from \code{\link{runSimulation}} where \code{save_results = TRUE}
@@ -56,7 +57,7 @@
 #'
 #' @author Phil Chalmers \email{rphilip.chalmers@@gmail.com}
 #'
-#' @seealso \code{\link{descript}}
+#' @seealso \code{\link{descript}}, \code{\link{SimRead}}
 #'
 #' @examples
 #'

R/runArraySimulation.R

@@ -127,7 +127,7 @@
 #' \doi{10.20982/tqmp.16.4.p248}
 #'
 #' @seealso \code{\link{runSimulation}}, \code{\link{expandDesign}},
-#'   \code{\link{genSeeds}}, \code{\link{SimCheck}},
+#'   \code{\link{genSeeds}}, \code{\link{SimCheck}}, \code{\link{SimRead}},
 #'   \code{\link{SimCollect}}, \code{\link{getArrayID}}
 #'
 #' @examples
@@ -202,7 +202,7 @@
 #'                    summarise=Summarise, iseed=iseed,
 #'                    filename='mylongsim', arrayID=arrayID)
 #'
-#' res <- readRDS('mylongsim-14.rds')
+#' res <- SimRead('mylongsim-14.rds')
 #' res
 #' SimResults(res) # condition and replication count stored
 #'
@@ -235,7 +235,7 @@
 #' # check that all files saved (warnings will be raised if missing files)
 #' SimCheck('sim/')
 #'
-#' condition14 <- readRDS('sim/condition-14.rds')
+#' condition14 <- SimRead('sim/condition-14.rds')
 #' condition14
 #' SimResults(condition14)
 #'
@@ -286,7 +286,7 @@
 #'
 #' # note that all row conditions are still stored separately, though note that
 #' #  arrayID is now 2 instead
-#' condition14 <- readRDS('sim/condition-14.rds')
+#' condition14 <- SimRead('sim/condition-14.rds')
 #' condition14
 #' SimResults(condition14)
 #'

R/runSimulation.R

@@ -345,7 +345,8 @@
 #'   Each saved object will contain a list of three elements containing the
 #'   condition (row from \code{design}),
 #'   results (as a \code{list} or \code{matrix}), and try-errors.
-#'   See \code{\link{SimResults}} for an example of how to read these \code{.rds} files back into R
+#'   See \code{\link{SimResults}} and \code{\link{SimRead}}
+#'   for an example of how to read these \code{.rds} files back into R
 #'   after the simulation is complete. Default is \code{FALSE}.
 #'
 #'   WARNING: saving results to your hard-drive can fill up space very quickly for
@@ -564,7 +565,7 @@
 #'       in the current working directory then a unique one will be created automatically. Default is
 #'       \code{'SimDesign-results_'} with the associated \code{compname} appended if no
 #'       \code{filename} is defined, otherwise the filename is used to replace 'SimDesign'
-#'       in the string}
+#'       in the string. See \code{\link{SimRead}} to read in the individual files}
 #'
 #'     \item{\code{save_results_filename}}{a string indicating the name file to store, where the
 #'       \code{Design} row ID will be appended to ensure uniqueness across rows. Specifying
@@ -575,7 +576,8 @@
 #'       for HPC structures that allow asynchronous file storage).
 #'       WARNING: the uniqueness of the file names are not checked using
 #'       this approach, therefore please ensure that each generated name will be unique a priori,
-#'       such as naming the file based on the supplied row condition information}
+#'       such as naming the file based on the supplied row condition information.
+#'       See \code{\link{SimRead}} to read in the individual files}
 #'
 #'     \item{\code{save_seeds_dirname}}{a string indicating the name of the folder to save
 #'       \code{.Random.seed} objects to when \code{save_seeds = TRUE}. If a directory/folder
@@ -617,7 +619,8 @@
 #'   To recover your simulation at the last known location (having patched the issues in the
 #'   previous execution code) simply re-run the code you used to
 #'   initially define the simulation and the external file will automatically be detected and read-in.
-#'   Default is \code{TRUE} when \code{replications > 10} and \code{FALSE} otherwise
+#'   Default is \code{TRUE} when \code{replications > 10} and \code{FALSE} otherwise.
+#'   See also \code{\link{SimRead}} to read and inspect the stored files
 #'
 #' @param resume logical; if a temporary \code{SimDesign} file is detected should
 #'   the simulation resume from this location? Keeping this \code{TRUE} is generally recommended,
@@ -735,7 +738,7 @@
 #'   \code{\link{Generate}}, \code{\link{Analyse}}, \code{\link{Summarise}},
 #'   \code{\link{SimExtract}},
 #'   \code{\link{reSummarise}}, \code{\link{SimClean}}, \code{\link{SimAnova}}, \code{\link{SimResults}},
-#'   \code{\link{SimCollect}}, \code{\link{Attach}}, \code{\link{AnalyseIf}},
+#'   \code{\link{SimCollect}}, \code{\link{SimRead}}, \code{\link{Attach}}, \code{\link{AnalyseIf}},
 #'   \code{\link{SimShiny}}, \code{\link{manageWarnings}}, \code{\link{runArraySimulation}}
 #'
 #' @export runSimulation

R/util.R

@@ -1052,6 +1052,20 @@ add_cbind <- function(lst){
     dplyr::as_tibble(ret)
 }
 
+
+#' Read simulation files
+#'
+#' Convenience function that switches between \code{readRDS()} and
+#' \code{qs2::qs_read()} for functions saved with \code{SimDesign}.
+#' By convention, objects saved with the extension \code{.rds} are read
+#' as R binary files and typically reflect the final object from
+#' \code{\link{runSimulation}} or \code{\link{runArraySimulation}},
+#' while files without an extension are read using \code{qs2} (most often
+#' temporary files or results written to an associated sub-directory).
+#'
+#' @export
+#' @return the R binary object
+#' @param filename name of the file to read in
 SimRead <- function(filename){
     file_ext <- tools::file_ext(filename)
     tmp <- if(tolower(file_ext) == 'rds')