drake (version 5.1.2)

drake_plan: Create a workflow plan data frame for the plan argument of make().

Description

Turns a named collection of target/command pairs into a workflow plan data frame for make(). You can give the commands as named expressions, or you can use the list argument to supply them as character strings.

Usage

drake_plan(..., list = character(0), file_targets = NULL,
  strings_in_dots = pkgconfig::get_config("drake::strings_in_dots"),
  tidy_evaluation = TRUE)

Arguments

...

A collection of symbols/targets with commands assigned to them. See the examples for details.

list

A named character vector of commands with names as targets.

file_targets

deprecated argument. See file_out(), file_in(), and knitr_in() for the current way to work with files. In the past, this argument was a logical to indicate whether the target names should be single-quoted to denote files. But the newer interface is much better.

strings_in_dots

deprecated argument for handling strings in commands specified in the ... argument. Defaults to NULL for backward compatibility. New code should use file_out(), file_in(), and knitr_in() to specify file names and set this argument to "literals", which will at some point become the only accepted value.

To fully embrace the glorious new file API, call pkgconfig::set_config("drake::strings_in_dots" = "literals") right when you start your R session. That way, drake totally relies on file_in(), file_out(), and knitr_in() to coordinate input and output files, as opposed to deprecated features like single-quotes (and in the case of knitr reports, explicit calls to knitr::knit() and rmarkdown::render() in commands). This is why the default value of strings_in_dots is pkgconfig::get_config("drake::strings_in_dots").

In the past, this argument was a character scalar denoting how to treat quoted character strings in the commands specified through .... Set to "filenames" to treat all these strings as external file targets/imports (single-quoted), or to "literals" to treat them all as literal strings (double-quoted). Unfortunately, because of how R deparses code, you cannot simply leave literal quotes alone in the ... argument. R will either convert all these quotes to single quotes or double quotes. Literal quotes in the list argument are left alone.

tidy_evaluation

logical, whether to use tidy evaluation such as quasiquotation when evaluating commands passed through the free-form ... argument.

Value

A data frame of targets and commands. See the details for optional columns you can append manually post-hoc.

Details

A workflow plan data frame is a data frame with a target column and a command column. Targets are the objects and files that drake generates, and commands are the pieces of R code that produce them.

To use custom files in your workflow plan, use the file_in(), knitr_in(), and file_out() functions in your commands. the examples in this help file provide some guidance.

Besides the target and command columns, there are optional columns you may append to your workflow plan data frame:

• trigger: a character vector of triggers. A trigger is a rule for when to cause a target to (re)build. See triggers() for your options. For a walkthrough, see https://github.com/ropensci/drake/blob/master/vignettes/debug.Rmd#test-with-triggers. # nolint

• retries: number of times to retry a target if it fails to build the first time.

• timeout: Seconds of overall time to allow before imposing a timeout on a target. Passed to R.utils::withTimeout(). Assign target-level timeout times with an optional timeout column in plan.

• cpu: Seconds of cpu time to allow before imposing a timeout on a target. Passed to R.utils::withTimeout(). Assign target-level cpu timeout times with an optional cpu column in plan.

• elapsed: Seconds of elapsed time to allow before imposing a timeout on a target. Passed to R.utils::withTimeout(). Assign target-level elapsed timeout times with an optional elapsed column in plan.

• evaluator: An experimental column. Each entry is a function passed to the evaluator argument of future::future() for each worker in make(..., parallelism = "future").

Examples

# NOT RUN {
test_with_dir("Contain side effects", {
# Create workflow plan data frames.
mtcars_plan <- drake_plan(
  write.csv(mtcars[, c("mpg", "cyl")], file_out("mtcars.csv")),
  value = read.csv(file_in("mtcars.csv")),
  strings_in_dots = "literals"
)
mtcars_plan
make(mtcars_plan) # Makes `mtcars.csv` and then `value`
head(readd(value))
# You can use knitr inputs too. See the top command below.
load_basic_example()
head(my_plan)
# The `knitr_in("report.Rmd")` tells `drake` to dive into the active
# code chunks to find dependencies.
# There, `drake` sees that `small`, `large`, and `coef_regression2_small`
# are loaded in with calls to `loadd()` and `readd()`.
deps("report.Rmd")
# You can create your own custom columns too.
# See ?triggers for more on triggers.
drake_plan(
  website_data = target(
    command = download_data("www.your_url.com"),
    trigger = "always",
    custom_column = 5
  ),
  analysis = analyze(website_data),
  strings_in_dots = "literals"
)
# Are you a fan of tidy evaluation?
my_variable <- 1
drake_plan(
  a = !!my_variable,
  b = !!my_variable + 1,
  list = c(d = "!!my_variable")
)
drake_plan(
  a = !!my_variable,
  b = !!my_variable + 1,
  list = c(d = "!!my_variable"),
  tidy_evaluation = FALSE
)
# For instances of !! that remain unevaluated in the workflow plan,
# make() will run these commands in tidy fashion,
# evaluating the !! operator using the environment you provided.
})
# }