Fix #326

NEWS.md

@@ -1,5 +1,6 @@
 # Version 5.1.0
 
+- Add a `reduce_plan()` function to do pairwise reductions on collections of targets.
 - Forcibly exclude the dot (`.`) from being a dependency of any target or import. This enforces more consistent behavior in the face of the current static code analysis funcionality, which sometimes detects `.` and sometimes does not.
 - Use `ignore()` to optionally ignore pieces of workflow plan commands and/or imported functions. Use `ignore(some_code)` to
     1. Force `drake` to not track dependencies in `some_code`, and

R/basic_example.R

@@ -7,7 +7,7 @@
 #' and then analyze them with regression models.
 #' Finally, we summarize the regression models
 #' to see if there is an association.
-#' @details Use \code{\link{drake_example}('basic')} to get the code
+#' @details Use \code{\link{drake_example}("basic")} to get the code
 #' for the basic example. The included R script is a detailed,
 #' heavily-commented walkthrough. The basic example vignette at
 #' <https://github.com/ropensci/drake/blob/master/vignettes/example-basic.Rmd> # nolint
@@ -66,7 +66,7 @@
 #' # Remove the whole cache.
 #' clean(destroy = TRUE)
 #' # Clean up the imported file.
-#' unlink('report.Rmd')
+#' unlink("report.Rmd")
 #' })
 #' }
 load_basic_example <- function(

R/check.R

@@ -16,7 +16,7 @@
 #' test_with_dir("Quarantine side effects.", {
 #' load_basic_example() # Get the code with drake_example("basic").
 #' check_plan(my_plan) # Check the workflow plan dataframe for obvious errors.
-#' unlink('report.Rmd') # Remove an import file mentioned in the plan.
+#' unlink("report.Rmd") # Remove an import file mentioned in the plan.
 #' # If you un-suppress the warnings, check_plan()
 #' # will tell you that 'report.Rmd' is missing.
 #' suppressWarnings(check_plan(my_plan))

R/dependencies.R

@@ -3,14 +3,16 @@
 #' @description Intended for debugging and checking your project.
 #'   The dependency structure of the components of your analysis
 #'   decides which targets are built and when.
-#' @details If the argument is a single-quoted string that points to
+#' @details If the argument is a double-quoted string that points to
 #'   a dynamic knitr report, the dependencies of the expected compiled
-#'   output will be given. For example, `deps("'report.Rmd'")`
+#'   output will be given. For example, `deps(file_store("report.Rmd"))`
 #'   will return target names found in calls to [loadd()]
-#'   and [readd()] in active code chunks.
-#'   These targets are needed in order to run `knit('report.Rmd')`
-#'   to produce the output file `'report.md'`, so technically,
-#'   they are dependencies of `'report.md'`, not `'report.Rmd'`.
+#'   and [readd()] in active code chunks. The [file_store()] function
+#'   (alerts `drake` utility functions to file names by double-quoting them.) 
+#'   These [loadd()]/[readd()] targets are needed
+#'   in order to run `knit(knitr_in("report.Rmd"))`
+#'   to produce the output file `"report.md"`, so technically,
+#'   they are dependencies of `"report.md"`, not `"report.Rmd"`.
 #'
 #'   `Drake` takes special precautions so that a target/import
 #'   does not depend on itself. For example, `deps(f)`` might return
@@ -37,8 +39,9 @@
 #' # Define a workflow plan data frame that uses your function f().
 #' my_plan <- drake_plan(
 #'   x = 1 + some_object,
-#'   my_target = x + readRDS('tracked_input_file.rds'),
-#'   return_value = f(x, y, g(z + w))
+#'   my_target = x + readRDS(file_in("tracked_input_file.rds")),
+#'   return_value = f(x, y, g(z + w)),
+#'   strings_in_dots = "literals"
 #' )
 #' # Get the dependencies of workflow plan commands.
 #' # Here, the dependencies could be R functions/objects from your workspace

R/examples.R

@@ -1,7 +1,7 @@
 #' @title Save the source code files of a drake example.
 #' @description Copy a folder of code files for a
 #' drake example to the current working directory.
-#' Call `drake_example('basic')` to generate the code files from the
+#' Call `drake_example("basic")` to generate the code files from the
 #' basic example vignette: `vignette("example-basic")`.
 #' To see the names of all the examples, run [drake_examples()].
 #' @seealso [drake_examples()], [make()],

R/generate.R

@@ -225,18 +225,22 @@ gather_plan <- function(
 }
 
 #' @title Write commands to reduce several targets down to one.
-#' @description Creates a new workflow plan data frame with a single new
-#'   target. This target is formed by combining the targets
-#'   in the argument plan using successive applications of a binary
-#'   operator.
+#' @description Creates a new workflow plan data frame with the
+#'   commands to do a reduction (i.e. to repeatedly apply a binary
+#'   operator to pairs of targets to produce one target).
 #' @export
 #' @return A workflow plan data frame that aggregates multiple
 #'   prespecified targets into one additional target downstream.
 #' @param plan workflow plan data frame of prespecified targets
-#' @param target name of the new aggregated target
-#' @param gather function used to gather the targets. Should be
-#'   one of \code{\link{list}(...)}, \code{\link{c}(...)},
-#'   \code{\link{rbind}(...)}, or similar.
+#' @param target name of the new reduced target
+#' @param begin character, code to place at the beginning
+#'   of each step in the reduction
+#' @param op binary operator to apply in the reduction
+#' @param end character, code to place at the end
+#'   of each step in the reduction
+#' @param pairwise logical, whether to create multiple
+#'   new targets, one for each pair/step in the reduction (`TRUE`), 
+#'   or to do the reduction all in one command.
 #' @examples
 #' # Workflow plan for datasets:
 #' x_plan <- evaluate_plan(
@@ -245,10 +249,22 @@ gather_plan <- function(
 #'   values = 1:8
 #' )
 #' # Create a new target from the sum of the others.
-#' reduce_plan(x_plan, target = "x_sum")
+#' reduce_plan(x_plan, target = "x_sum", pairwise = FALSE)
 #' # For memory efficiency and parallel computing,
 #' # reduce pairwise:
 #' reduce_plan(x_plan, target = "x_sum", pairwise = TRUE)
+#' # Optionally define your own function and use it as the
+#' # binary operator in the reduction.
+#' x_plan <- evaluate_plan(
+#'   drake_plan(x = VALUE),
+#'   wildcard = "VALUE",
+#'   values = 1:9
+#' )
+#' x_plan
+#' reduce_plan(
+#'   x_plan, target = "x_sum", pairwise = TRUE,
+#'   begin = "fun(", op = ", ", end = ")"
+#' )
 reduce_plan <- function(
   plan = NULL,
   target = "target",

R/knitr.R

@@ -7,8 +7,8 @@
 #' must call [knitr::knit()] directly.
 #' In other words,
 #' the command must look something like
-#' `knit('your_report.Rmd')` or
-#' `knit('your_report.Rmd', quiet = TRUE)`.
+#' `knit("your_report.Rmd")` or
+#' `knit("your_report.Rmd", quiet = TRUE)`.
 #' @return A character vector of the names of dependencies.
 #' @details Drake looks for dependencies in the document by
 #' analyzing evaluated code chunks for other targets/imports

R/migrate.R

@@ -129,7 +129,7 @@ assert_compatible_cache <- function(cache){
     "The project at '", path, "' was previously built by drake ", old, ". ",
     "You are running drake ", current, ", which is not back-compatible. ",
     "To format your cache for the newer drake, ",
-    "try migrate_drake_project('", path, "'). ",
+    "try migrate_drake_project(\"", path, "\"). ",
     "migrate_drake_project() restructures the cache in a way that ",
     "preserves the statuses of your targets (up to date vs outdated). ",
     "But in case of errors, ",

R/zzz.R

@@ -10,7 +10,7 @@
     warning(
       "Auto-saved workspace file '.RData' detected. ",
       "This is bad for reproducible code. ",
-      "You can remove it with unlink('.RData').",
+      "You can remove it with unlink(\".RData\").",
       call. = FALSE
     )
   }

_pkgdown.yml

@@ -84,6 +84,7 @@ reference:
   - '`evaluate_plan`'
   - '`expand_plan`'
   - '`gather_plan`'
+  - '`reduce_plan`'
   - '`plan_analyses`'
   - '`plan_summaries`'
 - title: Network graphs and visualization