tar_sitrep: Show the cue-by-cue status of each target.
In targets: Dynamic Function-Oriented 'Make'-Like Declarative Pipelines

tar_sitrep

R Documentation

Show the cue-by-cue status of each target.

Description

For each target, report which cues are activated. Except for the never cue, the target will rerun in tar_make() if any cue is activated. The target is suppressed if the never cue is TRUE. See tar_cue() for details.

Usage

tar_sitrep(
  names = NULL,
  fields = NULL,
  shortcut = targets::tar_config_get("shortcut"),
  reporter = targets::tar_config_get("reporter_outdated"),
  callr_function = callr::r,
  callr_arguments = targets::tar_callr_args_default(callr_function, reporter),
  envir = parent.frame(),
  script = targets::tar_config_get("script"),
  store = targets::tar_config_get("store")
)

Arguments

`names`	Optional, names of the targets. If supplied, `tar_sitrep()` only returns metadata on these targets. The object supplied to `names` should be `NULL` or a `tidyselect` expression like `any_of()` or `starts_with()` from `tidyselect` itself, or `tar_described_as()` to select target names based on their descriptions.
`fields`	Optional, names of columns/fields to select. If supplied, `tar_sitrep()` only returns the selected metadata columns. You can supply symbols or `tidyselect` helpers like `any_of()` and `starts_with()`. The `name` column is always included first no matter what you select. Choices: `name`: name of the target or global object. `record`: Whether the `record` cue is activated: `TRUE` if the target is not in the metadata (`tar_meta()`), or if the target errored during the last `tar_make()`, or if the class of the target changed. `always`: Whether `mode` in `tar_cue()` is `"always"`. If `TRUE`, `tar_make()` always runs the target. `never`: Whether `mode` in `tar_cue()` is `"never"`. If `TRUE`, `tar_make()` will only run if the `record` cue activates. `command`: Whether the target's command changed since last time. Always `TRUE` if the `record` cue is activated. Otherwise, always `FALSE` if the `command` cue is suppressed. `depend`: Whether the data/output of at least one of the target's dependencies changed since last time. Dependencies are targets, functions, and global objects directly upstream. Call `tar_outdated(targets_only = FALSE)` or `tar_visnetwork(targets_only = FALSE)` to see exactly which dependencies are outdated. Always `NA` if the `record` cue is activated. Otherwise, always `FALSE` if the `depend` cue is suppressed. `format`: Whether the storage format of the target is different from last time. Always `NA` if the `record` cue is activated. Otherwise, always `FALSE` if the `format` cue is suppressed. `repository`: Whether the storage repository of the target is different from last time. Always `NA` if the `record` cue is activated. Otherwise, always `FALSE` if the `format` cue is suppressed. `iteration`: Whether the iteration mode of the target is different from last time. Always `NA` if the `record` cue is activated. Otherwise, always `FALSE` if the `iteration` cue is suppressed. `file`: Whether the file(s) with the target's return value are missing or different from last time. Always `NA` if the `record` cue is activated. Otherwise, always `FALSE` if the `file` cue is suppressed.
`shortcut`	Logical of length 1, how to interpret the `names` argument. If `shortcut` is `FALSE` (default) then the function checks all targets upstream of `names` as far back as the dependency graph goes. If `TRUE`, then the function only checks the targets in `names` and uses stored metadata for information about upstream dependencies as needed. `shortcut = TRUE` increases speed if there are a lot of up-to-date targets, but it assumes all the dependencies are up to date, so please use with caution. Use with caution. `shortcut = TRUE` only works if you set `names`.
`reporter`	Character of length 1, name of the reporter to user. Controls how messages are printed as targets are checked. Choices: `"silent"`: print nothing. `"forecast"`: print running totals of the checked and outdated targets found so far.
`callr_function`	A function from `callr` to start a fresh clean R process to do the work. Set to `NULL` to run in the current session instead of an external process (but restart your R session just before you do in order to clear debris out of the global environment). `callr_function` needs to be `NULL` for interactive debugging, e.g. `tar_option_set(debug = "your_target")`. However, `callr_function` should not be `NULL` for serious reproducible work.
`callr_arguments`	A list of arguments to `callr_function`.
`envir`	An environment, where to run the target R script (default: `⁠_targets.R⁠`) if `callr_function` is `NULL`. Ignored if `callr_function` is anything other than `NULL`. `callr_function` should only be `NULL` for debugging and testing purposes, not for serious runs of a pipeline, etc. The `envir` argument of `tar_make()` and related functions always overrides the current value of `tar_option_get("envir")` in the current R session just before running the target script file, so whenever you need to set an alternative `envir`, you should always set it with `tar_option_set()` from within the target script file. In other words, if you call `tar_option_set(envir = envir1)` in an interactive session and then `tar_make(envir = envir2, callr_function = NULL)`, then `envir2` will be used.
`script`	Character of length 1, path to the target script file. Defaults to `tar_config_get("script")`, which in turn defaults to `⁠_targets.R⁠`. When you set this argument, the value of `tar_config_get("script")` is temporarily changed for the current function call. See `tar_script()`, `tar_config_get()`, and `tar_config_set()` for details about the target script file and how to set it persistently for a project.
`store`	Character of length 1, path to the `targets` data store. Defaults to `tar_config_get("store")`, which in turn defaults to `⁠_targets/⁠`. When you set this argument, the value of `tar_config_get("store")` is temporarily changed for the current function call. See `tar_config_get()` and `tar_config_set()` for details about how to set the data store path persistently for a project.

Details

Caveats:

tar_cue() allows you to change/suppress cues, so the return value will depend on the settings you supply to tar_cue().
If a pattern tries to branches over a target that does not exist in storage, then the branches are omitted from the output.
tar_sitrep() is myopic. It only considers what happens to the immediate target and its immediate upstream dependencies, and it makes no attempt to propagate invalidation downstream.

Value

A data frame with one row per target/object and one column per cue. Each element is a logical to indicate whether the cue is activated for the target. See the field argument in this help file for details.

Examples

if (identical(Sys.getenv("TAR_EXAMPLES"), "true")) { # for CRAN
tar_dir({ # tar_dir() runs code from a temp dir for CRAN.
tar_script({
  list(
    tar_target(x, seq_len(2)),
    tar_target(y, 2 * x, pattern = map(x))
  )
}, ask = FALSE)
tar_make()
tar_sitrep()
tar_meta(starts_with("y_")) # see also any_of()
})
}

targets documentation built on Oct. 3, 2024, 1:11 a.m.