readd: Read and return a drake target/import from the cache.

Description

readd() returns an object from the cache, and loadd() loads one or more objects from the cache into your environment or session. These objects are usually targets built by make().

Usage

readd(target, character_only = FALSE, path = getwd(), search = TRUE,
  cache = drake::get_cache(path = path, search = search, verbose =
  verbose), namespace = NULL, verbose = 1L, show_source = FALSE)
loadd(..., list = character(0), imported_only = NULL, path = getwd(),
  search = TRUE, cache = drake::get_cache(path = path, search = search,
  verbose = verbose), namespace = NULL, envir = parent.frame(),
  jobs = 1, verbose = 1L, deps = FALSE, lazy = "eager",
  graph = NULL, replace = TRUE, show_source = FALSE,
  tidyselect = !deps, config = NULL)

Arguments

target

If character_only is TRUE, then target is a character string naming the object to read. Otherwise, target is an unquoted symbol with the name of the object.

character_only

Logical, whether name should be treated as a character or a symbol (just like character.only in library()).

path

Root directory of the drake project, or if search is TRUE, either the project root or a subdirectory of the project. Ignored if a cache is supplied.

Logical. If TRUE, search parent directories to find the nearest drake cache. Otherwise, look in the current working directory only. Ignored if a cache is supplied.

cache

drake cache. See new_cache(). If supplied, path and search are ignored.

namespace

Optional character string, name of the storr namespace to read from.

verbose

Integer, control printing to the console/terminal.

0: print nothing.
1: print targets, retries, and failures.
2: also show a spinner when preprocessing tasks are underway.

show_source

Logical, option to show the command that produced the target or indicate that the object was imported (using show_source()).

...

Targets to load from the cache: as names (symbols) or character strings. If the tidyselect package is installed, you can also supply dplyr-style tidyselect commands such as starts_with(), ends_with(), and one_of().

list

Character vector naming targets to be loaded from the cache. Similar to the list argument of remove().

imported_only

Logical, deprecated.

envir

Environment to load objects into. Defaults to the calling environment (current workspace).

jobs

Number of parallel jobs for loading objects. On non-Windows systems, the loading process for multiple objects can be lightly parallelized via parallel::mclapply(). just set jobs to be an integer greater than 1. On Windows, jobs is automatically demoted to 1.

deps

Logical, whether to load any cached dependencies of the targets instead of the targets themselves.

Important note: deps = TRUE disables tidyselect functionality. For example, loadd(starts_with("model_"), config = config, deps = TRUE) does not work. For the selection mechanism to work, the model_* targets to need to already be in the cache, which is not always the case when you are debugging your projects. To help drake understand what you mean, you must name the targets explicitly when deps is TRUE, e.g. loadd(model_A, model_B, config = config, deps = TRUE).

lazy

Either a string or a logical. Choices:

"eager": no lazy loading. The target is loaded right away with assign().
"promise": lazy loading with delayedAssign()
"bind": lazy loading with active bindings: bindr::populate_env().
TRUE: same as "promise".
FALSE: same as "eager".

graph

Deprecated.

replace

Logical. If FALSE, items already in your environment will not be replaced.

tidyselect

Logical, whether to enable tidyselect expressions in ... like starts_with("prefix") and ends_with("suffix").

config

Optional drake_config() object. You should supply one if deps is TRUE.

Value

The cached value of the target.

Details

There are two uses for the loadd() and readd() functions:

Exploring the results outside the drake/make() pipeline. When you call make() to run your project, drake puts the targets in a cache, usually a folder called .drake. You may want to inspect the targets afterwards, possibly in an interactive R session. However, the files in the .drake folder are organized in a special format created by the storr package, which is not exactly human-readable. To retrieve a target for manual viewing, use readd(). To load one or more targets into your session, use loadd().
In knitr / R Markdown reports. You can borrow drake targets in your active code chunks if you have the right calls to loadd() and readd(). These reports can either run outside the drake pipeline, or better yet, as part of the pipeline itself. If you call knitr_in("your_report.Rmd") inside a drake_plan() command, then make() will scan "your_report.Rmd" for calls to loadd() and readd() in active code chunks, and then treat those loaded targets as dependencies. That way, make() will automatically (re)run the report if those dependencies change.

Examples

Run this code

# NOT RUN {
isolate_example("Quarantine side effects.", {
if (suppressWarnings(require("knitr"))) {
load_mtcars_example() # Get the code with drake_example("mtcars").
make(my_plan) # Run the project, build the targets.
readd(reg1) # Return imported object 'reg1' from the cache.
readd(small) # Return targets 'small' from the cache.
readd("large", character_only = TRUE) # Return 'large' from the cache.
# For external files, only the fingerprint/hash is stored.
readd(file_store("report.md"), character_only = TRUE)
}
})
# }
# NOT RUN {
isolate_example("Quarantine side effects.", {
if (suppressWarnings(require("knitr"))) {
load_mtcars_example() # Get the code with drake_example("mtcars").
make(my_plan) # Run the projects, build the targets.
config <- drake_config(my_plan)
loadd(small) # Load target 'small' into your workspace.
small
# For many targets, you can parallelize loadd()
# using the 'jobs' argument.
loadd(list = c("small", "large"), jobs = 2)
ls()
# Load the dependencies of the target, coef_regression2_small
loadd(coef_regression2_small, deps = TRUE, config = config)
ls()
# Load all the targets listed in the workflow plan
# of the previous `make()`.
# If you do not supply any target names, `loadd()` loads all the targets.
# Be sure your computer has enough memory.
loadd()
ls()
}
})
# }

Run the code above in your browser using DataCamp Workspace