Select targets using their descriptions.

Select a subset of targets in the _targets.R file based on their custom descriptions.

Usage

tar_described_as(
  described_as = NULL,
  tidyselect = TRUE,
  callr_function = callr::r,
  callr_arguments = targets::tar_callr_args_default(callr_function),
  envir = parent.frame(),
  script = targets::tar_config_get("script")
)

Arguments

described_as

A tidyselect expression to select targets based on their descriptions. For example, described_as = starts_with("survival model") matches all targets in the pipeline whose description arguments of tar_target() start with the text string "survival model".

tidyselect

If TRUE, return a call to tidyselect::all_of() identifying the selected targets, which can then be supplied to any tidyselect-compatible namesargument of downstream functions like [tar_make()] and [tar_manifest()]. IfFALSE`, return a simple character vector of target names.

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.

Value

If tidyselect is TRUE, then tar_described_as() returns a call to tidyselect::all_of() which can be supplied to the names argument of functions like tar_manifest() and tar_make(). This allows functions like tar_manifest() and tar_make() to focus on only the targets with the matching descriptions. If tidyselect is FALSE, then tar_described_as() returns a simple character vector of the names of all the targets in the pipeline with matching descriptions.

Details

Targets with empty descriptions are ignored.

See also

Other utilities: tar_active(), tar_backoff(), tar_call(), tar_cancel(), tar_definition(), tar_envir(), tar_format_get(), tar_group(), tar_name(), tar_path(), tar_path_script(), tar_path_script_support(), tar_path_store(), tar_path_target(), tar_source(), tar_store(), tar_unblock_process()

Examples

if (identical(Sys.getenv("TAR_EXAMPLES"), "true")) { # for CRAN
tar_dir({ # tar_dir() runs code from a temp dir for CRAN.
tar_script({
  library(targets)
  library(tarchetypes)
  list(
    tar_target(b2, TRUE, description = "blue two"),
    tar_target(b3, TRUE, description = "blue three"),
    tar_target(g2, TRUE, description = "green two"),
    tar_target(g3, TRUE, description = "green three"),
    tar_target(g4, TRUE, description = "green three")
  )
}, ask = FALSE)
tar_described_as(starts_with("green"), tidyselect = FALSE)
tar_make(names = tar_described_as(starts_with("green")))
tar_progress() # Only `g2`, `g3`, and `g4` ran.
})
}