trigger: Customize the decision rules for rebuilding targets...
In wlandau-lilly/drake: A Pipeline Toolkit for Reproducible Computation at Scale

trigger

R Documentation

Customize the decision rules for rebuilding targets

Description

Use this function inside a target's command in your drake_plan() or the trigger argument to make() or drake_config(). For details, see the chapter on triggers in the user manual: ⁠https://books.ropensci.org/drake/triggers.html⁠

Usage

trigger(
  command = TRUE,
  depend = TRUE,
  file = TRUE,
  seed = TRUE,
  format = TRUE,
  condition = FALSE,
  change = NULL,
  mode = c("whitelist", "blacklist", "condition")
)

Arguments

`command`	Logical, whether to rebuild the target if the `drake_plan()` command changes.
`depend`	Logical, whether to rebuild if a non-file dependency changes.
`file`	Logical, whether to rebuild the target if a `file_in()`/`file_out()`/`knitr_in()` file changes. Also applies to external data tracked with `target(format = "file")`.
`seed`	Logical, whether to rebuild the target if the seed changes. Only makes a difference if you set a custom `seed` column in your `drake_plan()` at some point in your workflow.
`format`	Logical, whether to rebuild the target if the choice of specialized data format changes: for example, if you use `target(format = "qs")` one instance and `target(format = "fst")` the next. See `⁠https://books.ropensci.org/drake/plans.html#special-data-formats-for-targets⁠` # nolint for details on formats.
`condition`	R code (expression or language object) that returns a logical. The target will rebuild if the code evaluates to `TRUE`.
`change`	R code (expression or language object) that returns any value. The target will rebuild if that value is different from last time or not already cached.
`mode`	A character scalar equal to `"whitelist"` (default) or `"blacklist"` or `"condition"`. With the `mode` argument, you can choose how the `condition` trigger factors into the decision to build or skip the target. Here are the options. `"whitelist"` (default): we rebuild the target whenever `condition` evaluates to `TRUE`. Otherwise, we defer to the other triggers. This behavior is the same as the decision rule described in the "Details" section of this help file. `"blacklist"`: we skip the target whenever `condition` evaluates to `FALSE`. Otherwise, we defer to the other triggers. `"condition"`: here, the `condition` trigger is the only decider, and we ignore all the other triggers. We rebuild target whenever `condition` evaluates to `TRUE` and skip it whenever `condition` evaluates to `FALSE`.

Details

A target always builds if it has not been built before. Triggers allow you to customize the conditions under which a pre-existing target rebuilds. By default, the target will rebuild if and only if:

Any of command, depend, or file is TRUE, or
condition evaluates to TRUE, or
change evaluates to a value different from last time. The above steps correspond to the "whitelist" decision rule. You can select other decision rules with the mode argument described in this help file. On another note, there may be a slight efficiency loss if you set complex triggers for change and/or condition because drake needs to load any required dependencies into memory before evaluating these triggers.

Value

A list of trigger specification details that drake processes internally when it comes time to decide whether to build the target.

Examples

# A trigger is just a set of decision rules
# to decide whether to build a target.
trigger()
# This trigger will build a target on Tuesdays
# and when the value of an online dataset changes.
trigger(condition = today() == "Tuesday", change = get_online_dataset())
## Not run: 
isolate_example("Quarantine side effects.", {
if (suppressWarnings(require("knitr"))) {
load_mtcars_example() # Get the code with drake_example("mtcars").
# You can use a global trigger argument:
# for example, to always run everything.
make(my_plan, trigger = trigger(condition = TRUE))
make(my_plan, trigger = trigger(condition = TRUE))
# You can also define specific triggers for each target.
plan <- drake_plan(
  x = sample.int(15),
  y = target(
    command = x + 1,
    trigger = trigger(depend = FALSE)
  )
)
# Now, when x changes, y will not.
make(plan)
make(plan)
plan$command[1] <- "sample.int(16)" # change x
make(plan)
}
})

## End(Not run)

wlandau-lilly/drake documentation built on Dec. 3, 2024, 11:09 p.m.