automatically export attached packages

Author: philchalmers

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: SimDesign
 Title: Structure for Organizing Monte Carlo Simulation Designs
-Version: 2.19.3
+Version: 2.19.4
 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")),

NAMESPACE

@@ -104,4 +104,5 @@ importFrom(utils,methods)
 importFrom(utils,object.size)
 importFrom(utils,packageVersion)
 importFrom(utils,recover)
+importFrom(utils,sessionInfo)
 importFrom(utils,tail)

NEWS.md

@@ -2,6 +2,10 @@
 
 ## Changes in SimDesign 2.20
 
+- Information provided to `runSimulation(..., packages)` now automatically adds `sessionInfo()$otherPkgs`
+  to the list. This detects and adds any explicit `library()` attachments declared before
+  the simulation execution to be exported
+
 - Add `expandReplications()` function to more naturally match the `expandDesign()`
   structure
 

R/SimDesign.R

@@ -35,7 +35,7 @@
 #' @importFrom progressr progressor
 #' @importFrom beepr beep
 # @importFrom robustbase glmrob
-#' @importFrom utils recover packageVersion head tail capture.output object.size
+#' @importFrom utils recover packageVersion head tail capture.output object.size sessionInfo
 #' @keywords package
 #' @references
 #'

R/runSimulation.R

@@ -237,13 +237,13 @@
 #'
 #' @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 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
-#'   with the \code{::} operator
-#'   (e.g., \code{extraDistr::rgumbel()}). Finally, to attach all previously loaded
-#'   packages use \code{packages = .packages()}
+#'   parallel to use non-standard functions from additional packages. Note that any previously attached
+#'   packages explicitly loaded via \code{\link{library}} or \code{\link{require}}
+#'   will be automatically added to this list, provided that they are visible
+#'   in the \code{otherPkgs} element
+#'   from \code{\link[utils]{sessionInfo}}. Alternatively, functions can be called
+#'   explicitly without attaching the package with the \code{::} operator
+#'   (e.g., \code{extraDistr::rgumbel()})
 #'
 #' @param beep logical; call the \code{beepr} package when the simulation is completed?
 #'
@@ -1260,7 +1260,7 @@ runSimulation <- function(design, replications, generate, analyse, summarise,
         parallel <- FALSE
         verbose <- FALSE
     }
-    packages <- c('SimDesign', packages)
+    packages <- unique(c(packages, 'SimDesign', names(utils::sessionInfo()$otherPkgs)))
     char_functions <- deparse(substitute(Functions[[i]]))
     if(any(grepl('browser\\(', char_functions))){
         if(verbose && parallel)

man/runSimulation.Rd

@@ -82,11 +82,30 @@ The same reasoning above applies to functions defined in the R work-space as wel
 stopCluster(cl)
 ```
 
-# Exporting objects example in `SimDesign`
+# Exporting functions for parallel computing
 
-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.
+## Exporting third-party libraries 
 
-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.
+For simulations that require third-party packages to work correctly (e.g., `rgumbel()` from the `extraDistr` package) there needs to be explicit instructions to indicate which namespace these functions originate from. For parallel computing applications there are three ways to indicate the namespace of a third-party function:
+
+1) Explicitly attach the package prior to executing the simulation via `library()` or `require()`. This must be done prior to using `runSimulation()`
+2) Explicitly pass a character vector containing the packages to be attached to `runSimulation(..., packages)` (e.g., `runSimulation(..., packages = c('extraDistr', 'copula'))`)
+3) Point to the function using the `::` operator (e.g., `extraDistr::rgumbel()`)
+
+For performance and masking related issues it is recommended to only export functions that are actually used in the simulation (e.g., attach `dplyr` and `tidy` explicitly rather than attaching the complete `tidyverse`).
+Note that 2) is technically not required if 1) or 3) is used. 
+
+As a reminder, attaching packages can result in function masking in the R session, and therefore in situations were ambiguity exists it is recommended to use the `::` operator explicitly even if these were attached. Doing so avoids makes it clear where the function originates regardless of the order with which the packages were attached to the session. 
+
+## Exporting user-defined functions
+
+Exporting user-defined functions explicitly is not required in `SimDesign`. Any previously written function that has been defined in the R work space prior to executing `runSimulation()` will automatically be exported (again, be cognizant of any potential function masking). Other R objects, on the other hand, are *not* explicitly exported. See the next section for further details.
+
+# Exporting objects 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*.
+
+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 or information.
 
 ```{r}
 library(SimDesign)
@@ -138,4 +157,4 @@ res <- runSimulation(Design, replications, verbose=FALSE, fixed_objects=fixed_ob
                      parallel = TRUE)
 ```
 
-Again, remember that this is only required for R **objects**, NOT for user-defined functions!
+Again, remember that this is only required for R **objects**, NOT for user-defined or third-party functions!

vignettes/Fixed_obj_fun.Rmd

@@ -62,7 +62,10 @@ Finally, note that all the rules about objects and object naming from the typica
 The following code is [adopted from the Wiki](http://philchalmers.github.io/SimDesign/html/03-Parameter_recovery_simulation.html), and so details about the simulation should be obtained from that source. 
 
 ```{r}
+# Note that all attached packages are automatically exported in SimDesign
 library(SimDesign)
+library(mirt)
+library(lavaan)
 # SimFunctions(nAnalyses = 2)
 
 sample_sizes <- c(250, 500, 1000)
@@ -150,7 +153,7 @@ res <- runSimulation(Design, replications=100, verbose=FALSE, parallel=TRUE,
                      generate=Generate, 
                      analyse=list(FIML=Analyse.FIML, DWLS=Analyse.DWLS), 
                      summarise=Summarise, filename = 'mirt_lavaan',
-                     packages=c('mirt', 'lavaan'), fixed_objects=pars)
+                     fixed_objects=pars)
 ```
 
 ```{r include=FALSE}
@@ -626,7 +629,7 @@ res <- runSimulation(Design, replications=100, verbose=FALSE, parallel=TRUE,
                      generate=Generate, 
                      analyse=list(Analyse.FIML, Analyse.DWLS), 
                      summarise=Summarise, filename = 'mirt_lavaan',
-                     packages=c('mirt', 'lavaan'), fixed_objects=pars)
+                     fixed_objects=pars)
 ```
 
 then only one analysis function will be applied at a time in the simulation experiment. Note that in this case there is no need to append 'MML' or 'DWLS' to the `results` objects as this becomes redundant with the `method` column in the `Design` object, and so the `analyse` list input is specified as an unnamed list (cf. earlier when the input was named, which appended `MML.` and `DWLS.` to the `results` output in `Summarise()`).