document and bump

Author: philchalmers

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: SimDesign
 Title: Structure for Organizing Monte Carlo Simulation Designs
-Version: 2.9.3
+Version: 2.10
 Authors@R: c(person("Phil", "Chalmers", email = "[email protected]", role = c("aut", "cre"),
                     comment = c(ORCID="0000-0001-5332-2810")),
              person("Matthew", "Sigal", role = c("ctb")),

R/runSimulation.R

@@ -4,7 +4,8 @@
 #' design conditions, and number of replications. Results can be saved as temporary files in case of
 #' interruptions and may be restored by re-running \code{runSimulation}, provided that the respective temp
 #' file can be found in the working directory. \code{runSimulation} supports parallel
-#' and cluster computing, global and local debugging, error handling (including fail-safe
+#' and cluster computing (with the \code{parallel} and \code{future} packages),
+#' global and local debugging, error handling (including fail-safe
 #' stopping when functions fail too often, even across nodes), provides bootstrap estimates of the
 #' sampling variability (optional), and automatic tracking of error and warning messages
 #' and their associated \code{.Random.seed} states.
@@ -116,7 +117,8 @@
 #'
 #' @section A note on parallel computing:
 #'
-#' When running simulations in parallel (either with \code{parallel = TRUE} or \code{MPI = TRUE})
+#' When running simulations in parallel (either with \code{parallel = TRUE} or \code{MPI = TRUE},
+#' or when using the \code{future} approach with a \code{plan()} other than sequential)
 #' R objects defined in the global environment will generally \emph{not} be visible across nodes.
 #' Hence, you may see errors such as \code{Error: object 'something' not found} if you try to use
 #' an object that is defined in the work space but is not passed to \code{runSimulation}.
@@ -182,11 +184,13 @@
 #'   constant global elements (e.g., a constant for sample size)
 #'
 #' @param parallel logical; use parallel processing from the \code{parallel}
-#'   package over each unique condition? Alternatively, if the \code{future} package has
-#'   been attached prior to executing \code{runSimulation()} then the associated
-#'   \code{plan()} will be followed
+#'   package over each unique condition?
+#'
+#'   Alternatively, if the \code{future} package has been attached prior to executing
+#'   \code{runSimulation()} then the associated \code{plan()} will be followed instead
 #'
-#' @param cl cluster object defined by \code{\link{makeCluster}} used to run code in parallel.
+#' @param cl cluster object defined by \code{\link{makeCluster}} used to run code in parallel
+#'   (ignored if using the \code{future} package approach).
 #'   If \code{NULL} and \code{parallel = TRUE}, a local cluster object will be defined which
 #'   selects the maximum number cores available
 #'   and will be stopped when the simulation is complete. Note that supplying a \code{cl}
@@ -199,8 +203,8 @@
 #'   \code{plan()} will be followed instead
 #'
 #' @param packages a character vector of external packages to be used during the simulation (e.g.,
-#'   \code{c('MASS', 'extraDistr', 'simsem')} ). Use this input when \code{parallel = TRUE} or
-#'   \code{MPI = TRUE} to use non-standard functions from additional packages,
+#'   \code{c('MASS', 'extraDistr', 'simsem')} ). Use this input when running code in
+#'   parallel to use non-standard functions from additional packages,
 #'   otherwise the functions must be made available by using explicit
 #'   \code{\link{library}} or \code{\link{require}} calls within the provided simulation functions.
 #'   Alternatively, functions can be called explicitly without attaching the package
@@ -411,7 +415,8 @@
 #'   something fatally problematic
 #'   is going wrong in the generate-analyse phases. Default is 50
 #'
-#' @param ncores number of cores to be used in parallel execution. Default uses all available
+#' @param ncores number of cores to be used in parallel execution (ignored if using the
+#'   \code{future} package approach). Default uses all available
 #'
 #' @param save logical; save the temporary simulation state to the hard-drive? This is useful
 #'   for simulations which require an extended amount of time, though for shorter simulations
@@ -769,14 +774,14 @@
 #' library(future) # future structure to be used internally
 #' # plan(multisession) # specify different plan (default is sequential)
 #'
-#' # note that parallel and cl inputs no longer used, and progressr package
-#' # used for progress reporting (disable with progress = FALSE or redefine
-#' # using progressr::handlers())
+#' # note that parallel and cl inputs no longer used, and the progressr package
+#' # is used for progress reporting (disable with progress = FALSE or redefine
+#' # using progressr::handlers(); see below)
 #' res <- runSimulation(design=Design, replications=1000,
 #'                      generate=Generate, analyse=Analyse, summarise=Summarise)
 #' head(res)
 #'
-#' # re-define progress bar
+#' # re-define progress bar (requires cli)
 #' library(progressr)
 #' handlers(handler_pbcol(
 #'    adjust = 1.0,
@@ -787,7 +792,7 @@
 #' res <- runSimulation(design=Design, replications=1000,
 #'                      generate=Generate, analyse=Analyse, summarise=Summarise)
 #'
-#' # stop using future package internally
+#' # to stop using future package internally use
 #' detach("package:future")
 #'
 #' ####################################