targets (version 0.0.0.9000)

tar_cue: Declare the rules that cue a target.

Description

Declare the rules that mark a target as outdated.

Usage

tar_cue(
  mode = c("thorough", "always", "never"),
  command = TRUE,
  depend = TRUE,
  format = TRUE,
  iteration = TRUE,
  file = TRUE
)

Arguments

mode

Cue mode. If "thorough", all the cues apply unless individually suppressed. If "always", then the target always runs. If "never", then the target does not run unless the metadata does not exist or the last run errored.

command

Logical, whether to rerun the target if command changed since last time.

depend

Logical, whether to rerun the target if the value of one of the dependencies changed.

format

Logical, whether to rerun the target if the user-specified storage format changed. The storage format is user-specified through tar_target() or tar_option_set().

iteration

Logical, whether to rerun the target if the user-specified iteration method changed. The iteration method is user-specified through tar_target() or tar_option_set().

file

Logical, whether to rerun the target if the file(s) with the return value changed or at least one is missing.

Details

targets uses internal metadata and special cues to decide if a target is up to date. A target is outdated if one of the following cues is met (checked in the order given below). tar_cue() can activate or suppress many of these cues. See the user manual for details.

1. There is no metadata record of the target.

2. The target errored last run.

3. The target has a different class than it did before.

4. The cue mode equals "always".

5. The cue mode does not equal "never".

6. The command metadata field (the hash of the R command) is different from last time.

7. The depend metadata field (the hash of the immediate upstream dependency targets and global objects) is different from last time.

8. The storage format is different from last time.

9. The iteration mode is different from last time.

10. A target's file (either the one in _targets/objects/ or a dynamic file) does not exist or changed since last time.

A target's dependencies can include functions, and these functions are tracked for changes using a custom hashing procedure. When a function's hash changes, the function is considered invalidated, and so are any downstream targets with the depend cue turned on. The targets package computes the hash of a function in the following way.

1. Deparse the function with targets:::deparse_safe(). This function computes a string representation of the function that removes comments and standardizes whitespace so that trivial changes to formatting do not cue targets to rerun.

2. Manually remove any literal pointers from the function string using targets:::mask_pointers(). Such pointers arise from inline compiled C/C++ functions.

3. Compute a hash on the preprocessed string above using targets:::digest_chr64().

Those functions themselves have dependencies, and those dependencies are detected with codetools::findGlobals(). Dependencies of functions may include other global functions or global objects. If a dependency of a function is invalidated, the function itself is invalidated, and so are any dependent targets with the depend cue turned on.

Examples

# NOT RUN {
# The following target will always run when the pipeline runs.
x <- tar_target(x, download_data(), cue = tar_cue(mode = "always"))
# }