Title:	Dynamic Function-Oriented 'Make'-Like Declarative Pipelines
Description:	Pipeline tools coordinate the pieces of computationally demanding analysis projects. The 'targets' package is a 'Make'-like pipeline tool for statistics and data science in R. The package skips costly runtime for tasks that are already up to date, orchestrates the necessary computation with implicit parallel computing, and abstracts files as R objects. If all the current output matches the current upstream code and data, then the whole pipeline is up to date, and the results are more trustworthy than otherwise. The methodology in this package borrows from GNU 'Make' (2015, ISBN:978-9881443519) and 'drake' (2018, <doi:10.21105/joss.00550>).
Version:	1.11.3
License:	MIT + file LICENSE
URL:	https://docs.ropensci.org/targets/, https://github.com/ropensci/targets
BugReports:	https://github.com/ropensci/targets/issues
Depends:	R (≥ 3.5.0)
Imports:	base64url (≥ 1.4), callr (≥ 3.7.0), cli (≥ 2.0.2), codetools (≥ 0.2.16), data.table (≥ 1.12.8), igraph (≥ 2.0.0), knitr (≥ 1.34), prettyunits (≥ 1.1.0), ps (≥ 1.8.0), R6 (≥ 2.4.1), rlang (≥ 1.0.0), secretbase (≥ 0.5.0), stats, tibble (≥ 3.0.1), tidyselect (≥ 1.1.0), tools, utils, vctrs (≥ 0.2.4), yaml (≥ 2.2.1)
Suggests:	autometric (≥ 0.1.0), bslib, clustermq (≥ 0.9.2), crew (≥ 0.9.0), curl (≥ 4.3), DT (≥ 0.14), dplyr (≥ 1.0.0), fst (≥ 0.9.2), future (≥ 1.19.1), future.batchtools (≥ 0.9.0), future.callr (≥ 0.6.0), gargle (≥ 1.2.0), googleCloudStorageR (≥ 0.7.0), gt (≥ 0.2.2), keras (≥ 2.2.5.0), markdown (≥ 1.1), nanonext (≥ 0.12.0), rmarkdown (≥ 2.4), parallelly (≥ 1.35.0), paws.common (≥ 0.6.4), paws.storage (≥ 0.4.0), pkgload (≥ 1.1.0), processx (≥ 3.4.3), qs2, reprex (≥ 2.0.0), rstudioapi (≥ 0.11), R.utils (≥ 2.6.0), shiny (≥ 1.5.0), shinybusy (≥ 0.2.2), shinyWidgets (≥ 0.5.4), tarchetypes, testthat (≥ 3.0.0), torch (≥ 0.1.0), usethis (≥ 1.6.3), visNetwork (≥ 2.1.2)
Encoding:	UTF-8
Language:	en-US
VignetteBuilder:	knitr
Config/testthat/edition:	3
RoxygenNote:	7.3.2
NeedsCompilation:	no
Packaged:	2025-05-08 16:59:05 UTC; C240390
Author:	William Michael Landau [aut, cre], Matthew T. Warkentin [ctb], Mark Edmondson [ctb], Samantha Oliver [rev], Tristan Mahr [rev], Eli Lilly and Company [cph, fnd]
Maintainer:	William Michael Landau <will.landau.oss@gmail.com>
Repository:	CRAN
Date/Publication:	2025-05-08 17:40:02 UTC

targets: Dynamic Function-Oriented Make-Like Declarative Pipelines for R

Description

A pipeline toolkit for Statistics and data science in R, the targets package brings function-oriented programming to Make-like declarative pipelines. targets orchestrates a pipeline as a graph of dependencies, skips steps that are already up to date, runs the necessary computations with optional parallel workers, abstracts files as R objects, and provides tangible evidence that the results are reproducible given the underlying code and data. The methodology in this package borrows from GNU Make (2015, ISBN:978-9881443519) and drake (2018, doi:10.21105/joss.00550).

See Also

Other help: tar_reprex(), use_targets(), use_targets_rmd()

Deprecated: callr arguments.

Description

Deprecated on 2022-08-05 (targets version 0.13.1). Please use tar_callr_args_default() instead.

Usage

callr_args_default(callr_function, reporter = NULL)

Arguments

Details

Not a user-side function. Do not invoke directly. Exported for internal purposes only.

Value

A list of arguments to callr_function.

Examples

tar_callr_args_default(callr::r)

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

tidyselect

all_of, any_of, contains, ends_with, everything, last_col, matches, num_range, one_of, starts_with

RStudio addin to call tar_glimpse().

Description

For internal use only. Not a user-side function.

Usage

rstudio_addin_tar_glimpse()

RStudio addin to call tar_load() on the symbol at the cursor.

Description

For internal use only. Not a user-side function.

Usage

rstudio_addin_tar_load(context = NULL)

Arguments

RStudio addin to run tar_make() in the background.

Description

For internal use only. Not a user-side function.

Usage

rstudio_addin_tar_make_bg()

RStudio addin to call tar_outdated().

Description

For internal use only. Not a user-side function.

Usage

rstudio_addin_tar_outdated()

RStudio addin to print tail(tar_progress()).

Description

For internal use only. Not a user-side function.

Usage

rstudio_addin_tar_progress()

RStudio addin to call tar_read() on the symbol at the cursor.

Description

For internal use only. Not a user-side function.

Usage

rstudio_addin_tar_read(context = NULL)

Arguments

RStudio addin to insert "tar_target()" at the cursor.

Description

For internal use only. Not a user-side function.

Usage

rstudio_addin_tar_target(context = NULL)

Arguments

RStudio addin to call tar_visnetwork().

Description

For internal use only. Not a user-side function.

Usage

rstudio_addin_tar_visnetwork()

Show if the pipeline is running.

Description

Return TRUE if called in a target or ⁠_targets.R⁠ and the pipeline is running.

Usage

tar_active()

Value

Logical of length 1, TRUE if called in a target or ⁠_targets.R⁠ and the pipeline is running (FALSE otherwise).

See Also

Other utilities: tar_backoff(), tar_call(), tar_cancel(), tar_definition(), tar_described_as(), 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_active() # FALSE
tar_script({
  library(targets)
  library(tarchetypes)
  message("Pipeline running? ", tar_active())
  tar_target(x, tar_active())
})
tar_manifest() # prints "Pipeline running? FALSE"
tar_make() # prints "pipeline running? TRUE"
tar_read(x) # TRUE
})
}

Assertions

Description

These functions assert the correctness of user inputs and generate custom error conditions as needed. Useful for writing packages built on top of targets.

Usage

tar_assert_chr(x, msg = NULL)

tar_assert_dbl(x, msg = NULL)

tar_assert_df(x, msg = NULL)

tar_assert_equal_lengths(x, msg = NULL)

tar_assert_envir(x, msg = NULL)

tar_assert_expr(x, msg = NULL)

tar_assert_flag(x, choices, msg = NULL)

tar_assert_file(x)

tar_assert_finite(x, msg = NULL)

tar_assert_function(x, msg = NULL)

tar_assert_function_arguments(x, args, msg = NULL)

tar_assert_ge(x, threshold, msg = NULL)

tar_assert_identical(x, y, msg = NULL)

tar_assert_in(x, choices, msg = NULL)

tar_assert_not_dirs(x, msg = NULL)

tar_assert_not_dir(x, msg = NULL)

tar_assert_not_in(x, choices, msg = NULL)

tar_assert_inherits(x, class, msg = NULL)

tar_assert_int(x, msg = NULL)

tar_assert_internet(msg = NULL)

tar_assert_lang(x, msg = NULL)

tar_assert_le(x, threshold, msg = NULL)

tar_assert_list(x, msg = NULL)

tar_assert_lgl(x, msg = NULL)

tar_assert_name(x)

tar_assert_named(x, msg = NULL)

tar_assert_names(x, msg = NULL)

tar_assert_nonempty(x, msg = NULL)

tar_assert_null(x, msg = NULL)

tar_assert_not_expr(x, msg = NULL)

tar_assert_nzchar(x, msg = NULL)

tar_assert_package(package, msg = NULL)

tar_assert_path(path, msg = NULL)

tar_assert_match(x, pattern, msg = NULL)

tar_assert_nonmissing(x, msg = NULL)

tar_assert_positive(x, msg = NULL)

tar_assert_scalar(x, msg = NULL)

tar_assert_store(store)

tar_assert_target(x, msg = NULL)

tar_assert_target_list(x)

tar_assert_true(x, msg = NULL)

tar_assert_unique(x, msg = NULL)

tar_assert_unique_targets(x)

Arguments

See Also

Other utilities to extend targets: tar_condition, tar_language, tar_test()

Examples

tar_assert_chr("123")
try(tar_assert_chr(123))

Superseded: exponential backoff

Description

Superseded: configure exponential backoff while polling for tasks during the pipeline.

Usage

tar_backoff(min = 0.001, max = 0.1, rate = 1.5)

Arguments

Details

This function is superseded and is now only relevant to other superseded functions tar_make_clustermq() and tar_make_future(). tar_make() uses crew in an efficient non-polling way, making exponential backoff unnecessary.

Backoff

In high-performance computing it can be expensive to repeatedly poll the priority queue if no targets are ready to process. The number of seconds between polls is runif(1, min, max(max, min * rate ^ index)), where index is the number of consecutive polls so far that found no targets ready to skip or run, and min, max, and rate are arguments to tar_backoff(). (If no target is ready, index goes up by 1. If a target is ready, index resets to 0. For more information on exponential, backoff, visit https://en.wikipedia.org/wiki/Exponential_backoff). Raising min or max is kinder to the CPU etc. but may incur delays in some instances.

See Also

Other utilities: tar_active(), tar_call(), tar_cancel(), tar_definition(), tar_described_as(), 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_option_set(backoff = tar_backoff(min = 0.001, max = 0.1, rate = 1.5))
})
}

Combine pipeline objects (deprecated).

Description

Functions tar_pipeline() and tar_bind() are deprecated. Instead, simply end your target script file (default: ⁠_targets.R⁠) file with a list of target objects. You can nest these objects however you like.

Usage

tar_bind(...)

Arguments

Details

Deprecated on 2021-01-03.

Examples

# In your target script file (default: _targets.R):
library(targets)
list( # You no longer need tar_pipeline() here.
  tar_target(data_file, "data.csv", format = "file"),
  list( # Target lists can be arbitrarily nested.
    tar_target(data_object, read.csv(data_file)),
    tar_target(analysis, analyze(data_object))
  )
)

Integer branch indexes

Description

Get the integer indexes of individual branch names within their corresponding dynamic branching targets.

Usage

tar_branch_index(names, store = targets::tar_config_get("store"))

Arguments

Value

A named integer vector of branch indexes.

See Also

Other branching: tar_branch_names(), tar_branches(), tar_pattern()

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(x, seq_len(4)),
    tar_target(y, 2 * x, pattern = map(x)),
    tar_target(z, y, pattern = map(y))
  )
}, ask = FALSE)
tar_make()
names <- c(
  tar_meta(y, children)$children[[1]][c(2, 3)],
  tar_meta(z, children)$children[[1]][2]
)
names
tar_branch_index(names) # c(2, 3, 2)
})
}

Branch names

Description

Get the branch names of a dynamic branching target using numeric indexes. tar_branch_names() expects an unevaluated symbol for the name argument, whereas tar_branch_names_raw() expects a character string for name.

Usage

tar_branch_names(name, index, store = targets::tar_config_get("store"))

tar_branch_names_raw(name, index, store = targets::tar_config_get("store"))

Arguments

Value

A character vector of branch names.

See Also

Other branching: tar_branch_index(), tar_branches(), tar_pattern()

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(x, seq_len(4)),
    tar_target(y, 2 * x, pattern = map(x)),
    tar_target(z, y, pattern = map(y))
  )
}, ask = FALSE)
tar_make()
tar_branch_names(z, c(2, 3))
})
}

Reconstruct the branch names and the names of their dependencies.

Description

Given a branching pattern, use available metadata to reconstruct branch names and the names of each branch's dependencies. The metadata of each target must already exist and be consistent with the metadata of the other targets involved.

Usage

tar_branches(
  name,
  pattern = NULL,
  script = targets::tar_config_get("script"),
  store = targets::tar_config_get("store")
)

Arguments

Details

The results from this function can help you retroactively figure out correspondences between upstream branches and downstream branches. However, it does not always correctly predict what the names of the branches will be after the next run of the pipeline. Dynamic branching happens while the pipeline is running, so we cannot always know what the names of the branches will be in advance (or even how many there will be).

Value

A tibble with one row per branch and one column for each target (including the branched-over targets and the target with the pattern.)

See Also

Other branching: tar_branch_index(), tar_branch_names(), tar_pattern()

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(x, seq_len(2)),
    tar_target(y, head(letters, 2)),
    tar_target(z, head(LETTERS, 2)),
    tar_target(dynamic, c(x, y, z), pattern = cross(z, map(x, y)))
  )
}, ask = FALSE)
tar_make()
tar_branches(dynamic)
tar_branches(dynamic, pattern = cross(z, map(x, y)))
})
}

Deprecated: list built targets.

Description

Deprecated in favor of tar_completed() on 2023-12-04 (targets version 1.3.2.9004).

Usage

tar_built(names = NULL, store = targets::tar_config_get("store"))

Arguments

Value

A character vector of completed targets.

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(x, seq_len(2)),
    tar_target(y, 2 * x, pattern = map(x))
  )
}, ask = FALSE)
tar_make()
tar_completed()
tar_completed(starts_with("y_")) # see also any_of()
})
}

Identify the called targets function.

Description

Get the name of the currently running targets interface function. Returns NULL if not invoked inside a target or ⁠_targets.R⁠ (i.e. if not directly invoked by tar_make(), tar_visnetwork(), etc.).

Usage

tar_call()

Value

Character of length 1, name of the currently running targets interface function. For example, suppose you have a call to tar_call() inside a target or ⁠_targets.R⁠. Then if you run tar_make(), tar_call() will return "tar_make".

See Also

Other utilities: tar_active(), tar_backoff(), tar_cancel(), tar_definition(), tar_described_as(), 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_call() # NULL
tar_script({
  library(targets)
  library(tarchetypes)
  message("called function: ", tar_call())
  tar_target(x, tar_call())
})
tar_manifest() # prints "called function: tar_manifest"
tar_make() # prints "called function: tar_make"
tar_read(x) # "tar_make"
})
}

Default callr arguments.

Description

Default callr arguments for the callr_arguments argument of tar_make() and related functions.

Usage

tar_callr_args_default(callr_function, reporter = NULL)

Arguments

Details

Not a user-side function. Do not invoke directly. Exported for internal purposes only.

Value

A list of arguments to callr_function.

Examples

tar_callr_args_default(callr::r)

Invoke a targets task from inside a callr function (without error handling).

Description

Not a user-side function. Do not invoke directly. Exported for internal purposes only.

Usage

tar_callr_inner_try(
  targets_function,
  targets_arguments,
  options,
  envir = NULL,
  parent,
  script,
  store,
  fun,
  pid_parent
)

Arguments

Value

The output of a call to a targets function that uses callr for reproducibility.

Examples

# See the examples of tar_make().

Cancel a target mid-execution under a custom condition.

Description

Cancel a target while its command is running if a condition is met.

Usage

tar_cancel(condition = TRUE)

Arguments

Details

Must be invoked by the target itself. tar_cancel() cannot interrupt a target from another process.

See Also

Other utilities: tar_active(), tar_backoff(), tar_call(), tar_definition(), tar_described_as(), 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(tar_target(x, tar_cancel(1 > 0)))
tar_make() # Should cancel target x.
})
}

List canceled targets.

Description

List targets whose progress is "canceled".

Usage

tar_canceled(names = NULL, store = targets::tar_config_get("store"))

Arguments

Value

A character vector of canceled targets.

See Also

Other progress: tar_completed(), tar_dispatched(), tar_errored(), tar_poll(), tar_progress(), tar_progress_branches(), tar_progress_summary(), tar_skipped(), tar_watch(), tar_watch_server(), tar_watch_ui()

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(x, seq_len(2)),
    tar_target(y, 2 * x, pattern = map(x))
  )
}, ask = FALSE)
tar_make()
tar_canceled()
tar_canceled(starts_with("y_")) # see also any_of()
})
}

Local CAS download.

Description

For internal use only.

Usage

tar_cas_d(cas, key, path)

Arguments

Value

Called for its side effects.

Check existence in local CAS.

Description

For internal use only.

Usage

tar_cas_e(cas, key)

Arguments

Details

The short function name helps reduce the size of the tar_repository_cas() format string and save space in the metadata.

Value

Character vector of keys (metadata hashes) found in the CAS system.

List keys in local CAS.

Description

For internal use only.

Usage

tar_cas_l(cas, keys)

Arguments

Details

The short function name helps reduce the size of the tar_repository_cas() format string and save space in the metadata.

Value

Character vector of keys (metadata hashes) found in the CAS system.

Local CAS upload.

Description

For internal use only.

Usage

tar_cas_u(cas, key, path)

Arguments

Details

The short function name helps reduce the size of the tar_repository_cas() format string and save space in the metadata.

Value

Called for its side effects.

List completed targets.

Description

List targets whose progress is "completed".

Usage

tar_completed(names = NULL, store = targets::tar_config_get("store"))

Arguments

Value

A character vector of completed targets.

See Also

Other progress: tar_canceled(), tar_dispatched(), tar_errored(), tar_poll(), tar_progress(), tar_progress_branches(), tar_progress_summary(), tar_skipped(), tar_watch(), tar_watch_server(), tar_watch_ui()

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(x, seq_len(2)),
    tar_target(y, 2 * x, pattern = map(x))
  )
}, ask = FALSE)
tar_make()
tar_completed()
tar_completed(starts_with("y_")) # see also any_of()
})
}

Conditions

Description

These functions throw custom targets-specific error conditions. Useful for error handling in packages built on top of targets.

Usage

tar_message_run(...)

tar_throw_file(...)

tar_throw_run(..., class = character(0))

tar_throw_validate(...)

tar_warn_deprecate(...)

tar_warn_run(...)

tar_warn_validate(...)

tar_message_validate(...)

tar_print(...)

tar_error(message, class)

tar_warning(message, class)

tar_message(message, class)

Arguments

See Also

Other utilities to extend targets: tar_assert, tar_language, tar_test()

Examples

try(tar_throw_validate("something is not valid"))

Contain an error condition and formatted traceback.

Description

Not a user-side function.

Usage

tar_condition_traced(condition, trace)

Arguments

Value

Contain an error condition and formatted traceback.

Get configuration settings.

Description

Read the custom settings for the current project in the optional YAML configuration file.

Usage

tar_config_get(
  name,
  config = Sys.getenv("TAR_CONFIG", "_targets.yaml"),
  project = Sys.getenv("TAR_PROJECT", "main")
)

Arguments

Value

The value of the configuration setting from the YAML configuration file (default: ⁠_targets.yaml⁠) or the default value if the setting is not available. The data type of the return value depends on your choice of name.

Storage access

Several functions like tar_make(), tar_read(), tar_load(), tar_meta(), and tar_progress() read or modify the local data store of the pipeline. The local data store is in flux while a pipeline is running, and depending on how distributed computing or cloud computing is set up, not all targets can even reach it. So please do not call these functions from inside a target as part of a running pipeline. The only exception is literate programming target factories in the tarchetypes package such as tar_render() and tar_quarto().

Configuration

For several key functions like tar_make(), the default values of arguments are controlled though tar_config_get(). tar_config_get() retrieves data from an optional YAML configuration file. You can control the settings in the YAML file programmatically with tar_config_set(). The default file path of this YAML file is ⁠_targets.yaml⁠, and you can set another path globally using the TAR_CONFIG environment variable. The YAML file can store configuration settings for multiple projects, and you can globally set the default project with the TAR_PROJECT environment variable. The structure of the YAML file follows rules similar to the config R package, e.g. projects can inherit settings from one another using the inherits field. Exceptions include:

1. There is no requirement to have a configuration named "default".

2. Other projects do not inherit from the default project' automatically.

3. Not all fields need values because targets already has defaults.

targets does not actually invoke the config package. The implementation in targets was written from scratch without viewing or copying any part of the source code of config.

See Also

Other configuration: tar_config_projects(), tar_config_set(), tar_config_unset(), tar_config_yaml(), tar_envvars(), tar_option_get(), tar_option_reset(), tar_option_set(), tar_option_with()

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, 1 + 1)))
tar_config_get("store") # "_targets"
store_path <- tempfile()
tar_config_set(store = store_path)
tar_config_get("store") # Shows a temp file.
tar_make() # Writes to the custom data store identified in _targets.yaml.
tar_read(x) # tar_read() knows about _targets.yaml too.
file.exists("_targets") # FALSE
file.exists(store_path) # TRUE
})
}

List projects.

Description

List the names of projects defined in ⁠_targets.yaml⁠.

Usage

tar_config_projects(config = Sys.getenv("TAR_CONFIG", "_targets.yaml"))

Arguments

Value

Character vector of names of projects defined in ⁠_targets.yaml⁠.

Storage access

Several functions like tar_make(), tar_read(), tar_load(), tar_meta(), and tar_progress() read or modify the local data store of the pipeline. The local data store is in flux while a pipeline is running, and depending on how distributed computing or cloud computing is set up, not all targets can even reach it. So please do not call these functions from inside a target as part of a running pipeline. The only exception is literate programming target factories in the tarchetypes package such as tar_render() and tar_quarto().

Configuration

For several key functions like tar_make(), the default values of arguments are controlled though tar_config_get(). tar_config_get() retrieves data from an optional YAML configuration file. You can control the settings in the YAML file programmatically with tar_config_set(). The default file path of this YAML file is ⁠_targets.yaml⁠, and you can set another path globally using the TAR_CONFIG environment variable. The YAML file can store configuration settings for multiple projects, and you can globally set the default project with the TAR_PROJECT environment variable. The structure of the YAML file follows rules similar to the config R package, e.g. projects can inherit settings from one another using the inherits field. Exceptions include:

1. There is no requirement to have a configuration named "default".

2. Other projects do not inherit from the default project' automatically.

3. Not all fields need values because targets already has defaults.

targets does not actually invoke the config package. The implementation in targets was written from scratch without viewing or copying any part of the source code of config.

See Also

Other configuration: tar_config_get(), tar_config_set(), tar_config_unset(), tar_config_yaml(), tar_envvars(), tar_option_get(), tar_option_reset(), tar_option_set(), tar_option_with()

Examples

yaml <- tempfile()
tar_config_set(store = "my_store_a", config = yaml, project = "project_a")
tar_config_set(store = "my_store_b", config = yaml, project = "project_b")
tar_config_projects(config = yaml)

Set configuration settings.

Description

tar_config_set() writes special custom settings for the current project to an optional YAML configuration file.

Usage

tar_config_set(
  inherits = NULL,
  as_job = NULL,
  garbage_collection = NULL,
  label = NULL,
  label_width = NULL,
  level_separation = NULL,
  reporter_make = NULL,
  reporter_outdated = NULL,
  script = NULL,
  seconds_meta_append = NULL,
  seconds_meta_upload = NULL,
  seconds_reporter = NULL,
  seconds_reporter_outdated = NULL,
  seconds_interval = NULL,
  store = NULL,
  shortcut = NULL,
  use_crew = NULL,
  workers = NULL,
  config = Sys.getenv("TAR_CONFIG", "_targets.yaml"),
  project = Sys.getenv("TAR_PROJECT", "main")
)

Arguments

Value

NULL (invisibly)

Configuration

For several key functions like tar_make(), the default values of arguments are controlled though tar_config_get(). tar_config_get() retrieves data from an optional YAML configuration file. You can control the settings in the YAML file programmatically with tar_config_set(). The default file path of this YAML file is ⁠_targets.yaml⁠, and you can set another path globally using the TAR_CONFIG environment variable. The YAML file can store configuration settings for multiple projects, and you can globally set the default project with the TAR_PROJECT environment variable. The structure of the YAML file follows rules similar to the config R package, e.g. projects can inherit settings from one another using the inherits field. Exceptions include:

1. There is no requirement to have a configuration named "default".

2. Other projects do not inherit from the default project' automatically.

3. Not all fields need values because targets already has defaults.

targets does not actually invoke the config package. The implementation in targets was written from scratch without viewing or copying any part of the source code of config.

Storage access

Several functions like tar_make(), tar_read(), tar_load(), tar_meta(), and tar_progress() read or modify the local data store of the pipeline. The local data store is in flux while a pipeline is running, and depending on how distributed computing or cloud computing is set up, not all targets can even reach it. So please do not call these functions from inside a target as part of a running pipeline. The only exception is literate programming target factories in the tarchetypes package such as tar_render() and tar_quarto().

See Also

Other configuration: tar_config_get(), tar_config_projects(), tar_config_unset(), tar_config_yaml(), tar_envvars(), tar_option_get(), tar_option_reset(), tar_option_set(), tar_option_with()

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, 1 + 1)))
tar_config_get("store") # NULL (data store defaults to "_targets/")
store_path <- tempfile()
tar_config_set(store = store_path)
tar_config_get("store") # Shows a temp file.
tar_make() # Writes to the custom data store identified in _targets.yaml.
tar_read(x) # tar_read() knows about _targets.yaml too.
file.exists("_targets") # FALSE
file.exists(store_path) # TRUE
})
}

Unset configuration settings.

Description

Unset (i.e. delete) one or more custom settings for the current project from the optional YAML configuration file. After that, tar_option_get() will return the original default values for those settings for the project.

Usage

tar_config_unset(
  names = character(0),
  config = Sys.getenv("TAR_CONFIG", "_targets.yaml"),
  project = Sys.getenv("TAR_PROJECT", "main")
)

Arguments

Value

NULL (invisibly)

Storage access

Several functions like tar_make(), tar_read(), tar_load(), tar_meta(), and tar_progress() read or modify the local data store of the pipeline. The local data store is in flux while a pipeline is running, and depending on how distributed computing or cloud computing is set up, not all targets can even reach it. So please do not call these functions from inside a target as part of a running pipeline. The only exception is literate programming target factories in the tarchetypes package such as tar_render() and tar_quarto().

Configuration

For several key functions like tar_make(), the default values of arguments are controlled though tar_config_get(). tar_config_get() retrieves data from an optional YAML configuration file. You can control the settings in the YAML file programmatically with tar_config_set(). The default file path of this YAML file is ⁠_targets.yaml⁠, and you can set another path globally using the TAR_CONFIG environment variable. The YAML file can store configuration settings for multiple projects, and you can globally set the default project with the TAR_PROJECT environment variable. The structure of the YAML file follows rules similar to the config R package, e.g. projects can inherit settings from one another using the inherits field. Exceptions include:

1. There is no requirement to have a configuration named "default".

2. Other projects do not inherit from the default project' automatically.

3. Not all fields need values because targets already has defaults.

targets does not actually invoke the config package. The implementation in targets was written from scratch without viewing or copying any part of the source code of config.

See Also

Other configuration: tar_config_get(), tar_config_projects(), tar_config_set(), tar_config_yaml(), tar_envvars(), tar_option_get(), tar_option_reset(), tar_option_set(), tar_option_with()

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, 1 + 1)))
tar_config_get("store") # "_targets"
store_path <- tempfile()
tar_config_set(store = store_path)
tar_config_get("store") # Shows a temp file.
tar_config_unset("store")
tar_config_get("store") # _targets
})
}

Read ⁠_targets.yaml⁠.

Description

Read the YAML content of ⁠_targets.yaml⁠.

Usage

tar_config_yaml(config = Sys.getenv("TAR_CONFIG", "_targets.yaml"))

Arguments

Value

Nested list of fields defined in ⁠_targets.yaml⁠.

Storage access

Several functions like tar_make(), tar_read(), tar_load(), tar_meta(), and tar_progress() read or modify the local data store of the pipeline. The local data store is in flux while a pipeline is running, and depending on how distributed computing or cloud computing is set up, not all targets can even reach it. So please do not call these functions from inside a target as part of a running pipeline. The only exception is literate programming target factories in the tarchetypes package such as tar_render() and tar_quarto().

Configuration

For several key functions like tar_make(), the default values of arguments are controlled though tar_config_get(). tar_config_get() retrieves data from an optional YAML configuration file. You can control the settings in the YAML file programmatically with tar_config_set(). The default file path of this YAML file is ⁠_targets.yaml⁠, and you can set another path globally using the TAR_CONFIG environment variable. The YAML file can store configuration settings for multiple projects, and you can globally set the default project with the TAR_PROJECT environment variable. The structure of the YAML file follows rules similar to the config R package, e.g. projects can inherit settings from one another using the inherits field. Exceptions include:

1. There is no requirement to have a configuration named "default".

2. Other projects do not inherit from the default project' automatically.

3. Not all fields need values because targets already has defaults.

targets does not actually invoke the config package. The implementation in targets was written from scratch without viewing or copying any part of the source code of config.

See Also

Other configuration: tar_config_get(), tar_config_projects(), tar_config_set(), tar_config_unset(), tar_envvars(), tar_option_get(), tar_option_reset(), tar_option_set(), tar_option_with()

Examples

yaml <- tempfile()
tar_config_set(store = "my_store_a", config = yaml, project = "project_a")
tar_config_set(store = "my_store_b", config = yaml, project = "project_b")
str(tar_config_yaml(config = yaml))

Create a counter object.

Description

Internal function. Not for users.

Usage

tar_counter(names = NULL)

Arguments

Examples

tar_counter(names = "x")

Get crew worker info.

Description

For the most recent run of the pipeline with tar_make() where a crew controller was started, get summary-level information of the workers.

Usage

tar_crew(store = targets::tar_config_get("store"))

Arguments

Value

A data frame one row per crew controller (potentially multiple rows if tar_option_get("controller") is a controller group) and the following columns:

• controller: name of the crew controller.

• targets: number of times the controller attempted to run a target.

• seconds: number of seconds the workers spent running tasks.

Storage access

Several functions like tar_make(), tar_read(), tar_load(), tar_meta(), and tar_progress() read or modify the local data store of the pipeline. The local data store is in flux while a pipeline is running, and depending on how distributed computing or cloud computing is set up, not all targets can even reach it. So please do not call these functions from inside a target as part of a running pipeline. The only exception is literate programming target factories in the tarchetypes package such as tar_render() and tar_quarto().

See Also

Other data: tar_pid(), tar_process()

Examples

if (identical(Sys.getenv("TAR_EXAMPLES"), "true")) { # for CRAN
tar_dir({ # tar_dir() runs code from a temp dir for CRAN.
if (requireNamespace("crew", quietly = TRUE)) {
tar_script({
  library(targets)
  library(tarchetypes)
  tar_option_set(controller = crew::crew_controller_local())
  list(
    tar_target(x, seq_len(2)),
    tar_target(y, 2 * x, pattern = map(x))
  )
}, ask = FALSE)
tar_make()
tar_process()
tar_process(pid)
}
})
}

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,
  repository = TRUE,
  iteration = TRUE,
  file = TRUE,
  seed = TRUE
)

Arguments

Target invalidation rules

targets uses internal metadata and special cues to decide whether a target is up to date (can skip) or is outdated/invalidated (needs to rerun). By default, targets moves through the following list of cues and declares a target outdated if at least one is cue activated.

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 file target) does not exist or changed since last time.

The user can suppress many of the above cues using the tar_cue() function, which creates the cue argument of tar_target(). Cues objects also constitute more nuanced target invalidation rules. The tarchetypes package has many such examples, including tar_age(), tar_download(), tar_cue_age(), tar_cue_force(), and tar_cue_skip().

Dependency-based invalidation and user-defined functions

If the cue of a target has depend = TRUE (default) then the target is marked invalidated/outdated when its upstream dependencies change. A target's dependencies include upstream targets, user-defined functions, and other global objects populated in the target script file (default: ⁠_targets.R⁠). To determine if a given dependency changed since the last run of the pipeline, targets computes hashes. The hash of a target is computed on its files in storage (usually a file in ⁠_targets/objects/⁠). The hash of a non-function global object dependency is computed directly on its in-memory data. User-defined functions are hashed in the following way:

1. Deparse the function with targets:::tar_deparse_safe(). This function computes a string representation of the function body and arguments. This string representation is invariant to changes in comments and whitespace, which means 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. Using static code analysis (i.e. tar_deps(), which is based on codetools::findGlobals()) identify any user-defined functions and global objects that the current function depends on. Append the hashes of those dependencies to the string representation of the current function.

4. Compute the hash of the final string representation using targets:::hash_object().

Above, (3) is important because user-defined functions have dependencies of their own, such as other user-defined functions and other global objects. (3) ensures that a change to a function's dependencies invalidates the function itself, which in turn invalidates any calling functions and any targets downstream with the depend cue turned on.

See Also

Other targets: tar_target()

Examples

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

Print instructions for debugging a target.

Description

Not a user-side function. Do not call directly.

Usage

tar_debug_instructions()

Value

NULL (invisibly). Messages are printed out.

Examples

tar_debug_instructions()

Deduplicate meta and progress databases (deprecated).

Description

Deprecated in targets version 0.3.0 (2020-03-06). Deduplication happens automatically before and after the pipeline runs.

Usage

tar_deduplicate(
  meta = TRUE,
  progress = TRUE,
  store = targets::tar_config_get("store")
)

Arguments

Details

Removes duplicated entries in the meta and progress databases in order to lighten storage. These databases are located in the ⁠_targets/meta/meta⁠ and ⁠_targets/meta/progress⁠ files, where ⁠_targets⁠ is the a folder at the project root. No essential data is removed, so this is simply a form of garbage collection.

Value

Nothing.

For developers only: get the definition of the current target.

Description

For developers only: get the full definition of the target currently running. This target definition is the same kind of object produced by tar_target().

Usage

tar_definition(
  default = targets::tar_target_raw("target_name", quote(identity()))
)

Arguments

Details

Most users should not use tar_definition() because accidental modifications could break the pipeline. tar_definition() only exists in order to support third-party interface packages, and even then the returned target definition is not modified..

Value

If called from a running target, tar_definition() returns the target object of the currently running target. See the "Target objects" section for details.

Target objects

Functions like tar_target() produce target objects, special objects with specialized sets of S3 classes. Target objects represent skippable steps of the analysis pipeline as described at https://books.ropensci.org/targets/. Please read the walkthrough at https://books.ropensci.org/targets/walkthrough.html to understand the role of target objects in analysis pipelines.

For developers, https://wlandau.github.io/targetopia/contributing.html#target-factories explains target factories (functions like this one which generate targets) and the design specification at https://books.ropensci.org/targets-design/ details the structure and composition of target objects.

See Also

Other utilities: tar_active(), tar_backoff(), tar_call(), tar_cancel(), tar_described_as(), 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

class(tar_definition())
tar_definition()$name
if (identical(Sys.getenv("TAR_EXAMPLES"), "true")) { # for CRAN
tar_dir({ # tar_dir() runs code from a temp dir for CRAN.
tar_script(
  tar_target(x, tar_definition()$settings$memory, memory = "transient")
)
tar_make(x)
tar_read(x)
})
}

Delete target output values.

Description

Delete the output values of targets in ⁠_targets/objects/⁠ (or the cloud if applicable) but keep the records in the metadata.

Usage

tar_delete(
  names,
  cloud = TRUE,
  batch_size = 1000L,
  verbose = TRUE,
  store = targets::tar_config_get("store")
)

Arguments

Details

If you have a small number of data-heavy targets you need to discard to conserve storage, this function can help. Local external files files (i.e. format = "file" and repository = "local") are not deleted. For targets with repository not equal "local", tar_delete() attempts to delete the file and errors out if the deletion is unsuccessful. If deletion fails, either log into the cloud platform and manually delete the file (e.g. the AWS web console in the case of repository = "aws") or call tar_invalidate() on that target so that targets does not try to delete the object. For patterns recorded in the metadata, all the branches will be deleted. For patterns no longer in the metadata, branches are left alone.

Storage access

Several functions like tar_make(), tar_read(), tar_load(), tar_meta(), and tar_progress() read or modify the local data store of the pipeline. The local data store is in flux while a pipeline is running, and depending on how distributed computing or cloud computing is set up, not all targets can even reach it. So please do not call these functions from inside a target as part of a running pipeline. The only exception is literate programming target factories in the tarchetypes package such as tar_render() and tar_quarto().

Cloud target data versioning

Some buckets in Amazon S3 or Google Cloud Storage are "versioned", which means they track historical versions of each data object. If you use targets with cloud storage (https://books.ropensci.org/targets/cloud-storage.html) and versioning is turned on, then targets will record each version of each target in its metadata.

Functions like tar_read() and tar_load() load the version recorded in the local metadata, which may not be the same as the "current" version of the object in the bucket. Likewise, functions tar_delete() and tar_destroy() only remove the version ID of each target as recorded in the local metadata.

If you want to interact with the latest version of an object instead of the version ID recorded in the local metadata, then you will need to delete the object from the metadata.

1. Make sure your local copy of the metadata is current and up to date. You may need to run tar_meta_download() or tar_meta_sync() first.

2. Run tar_unversion() to remove the recorded version IDs of your targets in the local metadata.

3. With the version IDs gone from the local metadata, functions like tar_read() and tar_destroy() will use the latest version of each target data object.

4. Optional: to back up the local metadata file with the version IDs deleted, use tar_meta_upload().

See Also

Other clean: tar_destroy(), tar_invalidate(), tar_prune(), tar_prune_list(), tar_unversion()

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(y1, 1 + 1),
    tar_target(y2, 1 + 1),
    tar_target(z, y1 + y2)
  )
}, ask = FALSE)
tar_make()
tar_delete(starts_with("y")) # Only deletes y1 and y2.
tar_make() # y1 and y2 rerun but return the same values, so z is up to date.
})
}

Code dependencies

Description

List the dependencies of a function or expression. tar_deps() expects the expr argument to be an unevaluated expression, whereas tar_deps_raw() expects expr to be an evaluated expression object. Functions can be passed normally in either case.

Usage

tar_deps(expr)

tar_deps_raw(expr)

Arguments

Details

targets detects the dependencies of commands using static code analysis. Use tar_deps() to run the code analysis and see the dependencies for yourself.

Value

Character vector of the dependencies of a function or expression.

See Also

tar_branches(), tar_network()

Other inspect: tar_manifest(), tar_network(), tar_outdated(), tar_sitrep(), tar_validate()

Examples

tar_deps(x <- y + z)
tar_deps(quote(x <- y + z))
tar_deps({
  x <- 1
  x + a
})
tar_deps(function(a = b) map_dfr(data, ~do_row(.x)))
tar_deps_raw(function(a = b) map_dfr(data, ~do_row(.x)))

Select targets using their descriptions.

Description

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

Details

Targets with empty descriptions are ignored.

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.

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.
})
}

Destroy the data store.

Description

Destroy the data store written by the pipeline.

Usage

tar_destroy(
  destroy = c("all", "cloud", "local", "meta", "process", "progress", "objects",
    "scratch", "workspaces", "user"),
  batch_size = 1000L,
  verbose = TRUE,
  ask = NULL,
  script = targets::tar_config_get("script"),
  store = targets::tar_config_get("store")
)

Arguments

Details

The data store is a folder created by tar_make() (or tar_make_future() or tar_make_clustermq()). The details of the data store are explained at https://books.ropensci.org/targets/data.html#local-data-store. The data store folder contains the output data and metadata of the targets in the pipeline. Usually, the data store is a folder called ⁠_targets/⁠ (see tar_config_set() to customize), and it may link to data on the cloud if you used AWS or GCP buckets. By default, tar_destroy() deletes the entire ⁠_targets/⁠ folder (or wherever the data store is located), including custom user-supplied files in ⁠_targets/user/⁠, as well as any cloud data that the pipeline uploaded. See the destroy argument to customize this behavior and only delete part of the data store, and see functions like tar_invalidate(), tar_delete(), and tar_prune() to remove information pertaining to some but not all targets in the pipeline. After calling tar_destroy() with default arguments, the entire data store is gone, which means all the output data from previous runs of the pipeline is gone (except for input/output files tracked with tar_target(..., format = "file")). The next run of the pipeline will start from scratch, and it will not skip any targets.

Value

NULL (invisibly).

Storage access

Several functions like tar_make(), tar_read(), tar_load(), tar_meta(), and tar_progress() read or modify the local data store of the pipeline. The local data store is in flux while a pipeline is running, and depending on how distributed computing or cloud computing is set up, not all targets can even reach it. So please do not call these functions from inside a target as part of a running pipeline. The only exception is literate programming target factories in the tarchetypes package such as tar_render() and tar_quarto().

Cloud target data versioning

Some buckets in Amazon S3 or Google Cloud Storage are "versioned", which means they track historical versions of each data object. If you use targets with cloud storage (https://books.ropensci.org/targets/cloud-storage.html) and versioning is turned on, then targets will record each version of each target in its metadata.

Functions like tar_read() and tar_load() load the version recorded in the local metadata, which may not be the same as the "current" version of the object in the bucket. Likewise, functions tar_delete() and tar_destroy() only remove the version ID of each target as recorded in the local metadata.

If you want to interact with the latest version of an object instead of the version ID recorded in the local metadata, then you will need to delete the object from the metadata.

1. Make sure your local copy of the metadata is current and up to date. You may need to run tar_meta_download() or tar_meta_sync() first.

2. Run tar_unversion() to remove the recorded version IDs of your targets in the local metadata.

3. With the version IDs gone from the local metadata, functions like tar_read() and tar_destroy() will use the latest version of each target data object.

4. Optional: to back up the local metadata file with the version IDs deleted, use tar_meta_upload().

See Also

Other clean: tar_delete(), tar_invalidate(), tar_prune(), tar_prune_list(), tar_unversion()

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(x, 1 + 1))
})
tar_make() # Creates the _targets/ data store.
tar_destroy()
print(file.exists("_targets")) # Should be FALSE.
})
}

Execute code in a temporary directory.

Description

Not a user-side function. Just for CRAN.

Usage

tar_dir(code)

Arguments

Details

Runs code inside a new tempfile() directory in order to avoid writing to the user's file space. Used in examples and tests in order to comply with CRAN policies.

Value

Return value of the user-defined code.

Examples

tar_dir(file.create("only_exists_in_tar_dir"))
file.exists("only_exists_in_tar_dir")

List dispatched targets.

Description

List the targets with progress status "dispatched".

Usage

tar_dispatched(names = NULL, store = targets::tar_config_get("store"))

Arguments

Details

A target is "dispatched" if it is sent off to be run. Depending on your high-performance computing configuration via the crew package, the may not actually start right away. This may happen if the target is ready to start but all available parallel workers are busy.

Value

A character vector of dispatched targets.

See Also

Other progress: tar_canceled(), tar_completed(), tar_errored(), tar_poll(), tar_progress(), tar_progress_branches(), tar_progress_summary(), tar_skipped(), tar_watch(), tar_watch_server(), tar_watch_ui()

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(x, seq_len(2)),
    tar_target(y, 2 * x, pattern = map(x))
  )
}, ask = FALSE)
tar_make()
tar_dispatched()
tar_dispatched(starts_with("y_")) # see also any_of()
})
}

Open the target script file for editing.

Description

Open the target script file for editing. Requires the usethis package.

Usage

tar_edit(script = targets::tar_config_get("script"))

Arguments

Details

The target script file is an R code file that defines the pipeline. The default path is ⁠_targets.R⁠, but the default for the current project can be configured with tar_config_set()

See Also

Other scripts: tar_github_actions(), tar_helper(), tar_renv(), tar_script()

Target Markdown knitr engine

Description

knitr language engine that runs targets code chunks in Target Markdown.

Usage

tar_engine_knitr(options)

Arguments

Value

Character, output generated from knitr::engine_output().

Target Markdown interactive mode

Target Markdown has two modes:

1. Non-interactive mode. This is the default when you run knitr::knit() or rmarkdown::render(). Here, the code in targets code chunks gets written to special script files in order to set up a targets pipeline to run later.

2. Interactive mode: here, no scripts are written to set up a pipeline. Rather, the globals or targets in question are run in the current environment and the values are assigned to that environment.

The mode is interactive if !isTRUE(getOption("knitr.in.progress")), is TRUE. The knitr.in.progress option is TRUE when you run knitr::knit() or rmarkdown::render() and NULL if you are running one chunk at a time interactively in an integrated development environment, e.g. the notebook interface in RStudio: https://bookdown.org/yihui/rmarkdown/notebook.html. You can choose the mode with the tar_interactive chunk option. (In targets 0.6.0, tar_interactive defaults to interactive() instead of !isTRUE(getOption("knitr.in.progress")).)

Target Markdown chunk options

Target Markdown introduces the following knitr code chunk options. Most other standard knitr code chunk options should just work in non-interactive mode. In interactive mode, not all

• tar_globals: Logical of length 1, whether to define globals or targets. If TRUE, the chunk code defines functions, objects, and options common to all the targets. If FALSE or NULL (default), then the chunk returns formal targets for the pipeline.

• tar_interactive: Logical of length 1, whether to run in interactive mode or non-interactive mode. See the "Target Markdown interactive mode" section of this help file for details.

• tar_name: name to use for writing helper script files (e.g. ⁠_targets_r/targets/target_script.R⁠) and specifying target names if the tar_simple chunk option is TRUE. All helper scripts and target names must have unique names, so please do not set this option globally with knitr::opts_chunk$set().

• tar_script: Character of length 1, where to write the target script file in non-interactive mode. Most users can skip this option and stick with the default ⁠_targets.R⁠ script path. Helper script files are always written next to the target script in a folder with an "_r" suffix. The tar_script path must either be absolute or be relative to the project root (where you call tar_make() or similar). If not specified, the target script path defaults to tar_config_get("script") (default: ⁠_targets.R⁠; helpers default: ⁠_targets_r/⁠). When you run tar_make() etc. with a non-default target script, you must select the correct target script file either with the script argument or with tar_config_set(script = ...). The function will source() the script file from the current working directory (i.e. with chdir = FALSE in source()).

• tar_simple: Logical of length 1. Set to TRUE to define a single target with a simplified interface. In code chunks with tar_simple equal to TRUE, the chunk label (or the tar_name chunk option if you set it) becomes the name, and the chunk code becomes the command. In other words, a code chunk with label targetname and command mycommand() automatically gets converted to tar_target(name = targetname, command = mycommand()). All other arguments of tar_target() remain at their default values (configurable with tar_option_set() in a tar_globals = TRUE chunk).

See Also

https://books.ropensci.org/targets/literate-programming.html

Other Target Markdown: tar_interactive(), tar_noninteractive(), tar_toggle()

Examples

if (identical(Sys.getenv("TAR_EXAMPLES"), "true")) { # for CRAN
# Register the engine.
if (requireNamespace("knitr", quietly = TRUE)) {
  knitr::knit_engines$set(targets = targets::tar_engine_knitr)
}
# Then, `targets` code chunks in a knitr report will run
# as described at
# <https://books.ropensci.org/targets/literate-programming.html>.
}

For developers only: get the environment of the current target.

Description

For developers only: get the environment where a target runs its command. Designed to be called while the target is running. The environment inherits from tar_option_get("envir").

Usage

tar_envir(default = parent.frame())

Arguments

Details

Most users should not use tar_envir() because accidental modifications to parent.env(tar_envir()) could break the pipeline. tar_envir() only exists in order to support third-party interface packages, and even then the returned environment is not modified.

Value

If called from a running target, tar_envir() returns the environment where the target runs its command. If called outside a pipeline, the return value is whatever the user supplies to default (which defaults to parent.frame()).

See Also

Other utilities: tar_active(), tar_backoff(), tar_call(), tar_cancel(), tar_definition(), tar_described_as(), 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

tar_envir()
tar_envir(default = new.env(parent = emptyenv()))
if (identical(Sys.getenv("TAR_EXAMPLES"), "true")) { # for CRAN
tar_dir({ # tar_dir() runs code from a temp dir for CRAN.
tar_script(tar_target(x, tar_envir(default = parent.frame())))
tar_make(x)
tar_read(x)
})
}

Show targets environment variables.

Description

Show all the special environment variables available for customizing targets.

Usage

tar_envvars(unset = "")

Arguments

Details

You can customize the behavior of targets with special environment variables. The sections in this help file describe each environment variable, and the tar_envvars() function lists their current values.

If you modify environment variables, please set them in project-level .Renviron file so you do not lose your configuration when you restart your R session. Modify the project-level .Renviron file with usethis::edit_r_environ(scope = "project"). Restart your R session after you are done editing.

For targets that run on parallel workers created by tar_make_clustermq() or tar_make_future(), only the environment variables listed by tar_envvars() are specifically exported to the targets. For all other environment variables, you will have to set the values manually, e.g. a project-level .Renviron file (for workers that have access to the local file system).

Value

A data frame with one row per environment variable and columns with the name and current value of each. An unset environment variable will have a value of "" by default. (Customize with the unset argument).

TAR_ASK

The TAR_ASK environment variable accepts values "true" and "false". If TAR_ASK is not set, or if it is set to "true", then targets asks permission in a menu before overwriting certain files, such as the target script file (default: ⁠_targets.R⁠) in tar_script(). If TAR_ASK is "false", then targets overwrites the old files with the new ones without asking. Once you are comfortable with tar_script(), tar_github_actions(), and similar functions, you can safely set TAR_ASK to "false" in either a project-level or user-level .Renviron file.

TAR_CONFIG

The TAR_CONFIG environment variable controls the file path to the optional YAML configuration file with project settings. See the help file of tar_config_set() for details.

TAR_PROJECT

The TAR_PROJECT environment variable sets the name of project to set and get settings when working with the YAML configuration file. See the help file of tar_config_set() for details.

TAR_WARN

The TAR_WARN environment variable accepts values "true" and "false". If TAR_WARN is not set, or if it is set to "true", then targets throws warnings in certain edge cases, such as target/global name conflicts and dangerous use of devtools::load_all(). If TAR_WARN is "false", then targets does not throw warnings in these cases. These warnings can detect potentially serious issues with your pipeline, so please do not set TAR_WARN unless your use case absolutely requires it.

See Also

Other configuration: tar_config_get(), tar_config_projects(), tar_config_set(), tar_config_unset(), tar_config_yaml(), tar_option_get(), tar_option_reset(), tar_option_set(), tar_option_with()

Examples

tar_envvars()

List errored targets.

Description

List targets whose progress is "errored".

Usage

tar_errored(names = NULL, store = targets::tar_config_get("store"))

Arguments

Value

A character vector of errored targets.

Storage access

Several functions like tar_make(), tar_read(), tar_load(), tar_meta(), and tar_progress() read or modify the local data store of the pipeline. The local data store is in flux while a pipeline is running, and depending on how distributed computing or cloud computing is set up, not all targets can even reach it. So please do not call these functions from inside a target as part of a running pipeline. The only exception is literate programming target factories in the tarchetypes package such as tar_render() and tar_quarto().

See Also

Other progress: tar_canceled(), tar_completed(), tar_dispatched(), tar_poll(), tar_progress(), tar_progress_branches(), tar_progress_summary(), tar_skipped(), tar_watch(), tar_watch_server(), tar_watch_ui()

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(x, seq_len(2)),
    tar_target(y, 2 * x, pattern = map(x))
  )
}, ask = FALSE)
tar_make()
tar_errored()
tar_errored(starts_with("y_")) # see also any_of()
})
}

Check if target metadata exists.

Description

Check if the target metadata file ⁠_targets/meta/meta⁠ exists for the current project.

Usage

tar_exist_meta(store = targets::tar_config_get("store"))

Arguments

Details

To learn more about data storage in targets, visit https://books.ropensci.org/targets/data.html.

Value

Logical of length 1, whether the current project's metadata exists.

See Also

Other existence: tar_exist_objects(), tar_exist_process(), tar_exist_progress(), tar_exist_script()

Examples

tar_exist_meta()

Check if local output data exists for one or more targets.

Description

Check if output target data exists in either ⁠_targets/objects/⁠ or the cloud for one or more targets.

Usage

tar_exist_objects(
  names,
  cloud = TRUE,
  store = targets::tar_config_get("store")
)

Arguments

Details

If a target has no metadata or if the repository argument of tar_target() was set to "local", then the ⁠_targets/objects/⁠ folder is checked. Otherwise, if there is metadata and repsitory is not "local", then tar_exist_objects() checks the cloud repository selected.

Value

Logical of length length(names), whether each given target has an existing file in either ⁠_targets/objects/⁠ or the cloud.

See Also

Other existence: tar_exist_meta(), tar_exist_process(), tar_exist_progress(), tar_exist_script()

Examples

tar_exist_objects(c("target1", "target2"))

Check if process metadata exists.

Description

Check if the process metadata file ⁠_targets/meta/process⁠ exists for the current project.

Usage

tar_exist_process(store = targets::tar_config_get("store"))

Arguments

Details

To learn more about data storage in targets, visit https://books.ropensci.org/targets/data.html.

Value

Logical of length 1, whether the current project's metadata exists.

See Also

Other existence: tar_exist_meta(), tar_exist_objects(), tar_exist_progress(), tar_exist_script()

Examples

tar_exist_process()

Check if progress metadata exists.

Description

Check if the progress metadata file ⁠_targets/meta/progress⁠ exists for the current project.

Usage

tar_exist_progress(store = targets::tar_config_get("store"))

Arguments

Details

To learn more about data storage in targets, visit https://books.ropensci.org/targets/data.html.

Value

Logical of length 1, whether the current project's metadata exists.

See Also

Other existence: tar_exist_meta(), tar_exist_objects(), tar_exist_process(), tar_exist_script()

Examples

tar_exist_progress()

Check if the target script file exists.

Description

Check if the target script file exists for the current project. The target script is ⁠_targets.R⁠ by default, but the path can be configured for the current project using tar_config_set().

Usage

tar_exist_script(script = targets::tar_config_get("script"))

Arguments

Value

Logical of length 1, whether the current project's metadata exists.

See Also

Other existence: tar_exist_meta(), tar_exist_objects(), tar_exist_process(), tar_exist_progress()

Examples

tar_exist_script()

Define a custom target storage format.

Description

Define a custom target storage format for the format argument of tar_target() or tar_option_set().

Usage

tar_format(
  read = NULL,
  write = NULL,
  marshal = NULL,
  unmarshal = NULL,
  convert = NULL,
  copy = NULL,
  substitute = list(),
  repository = NULL
)

Arguments

Value

A character string of length 1 encoding the custom format. You can supply this string directly to the format argument of tar_target() or tar_option_set().

Marshalling

If an object can only be used in the R session where it was created, it is called "non-exportable". Examples of non-exportable R objects are Keras models, Torch objects, xgboost matrices, xml2 documents, rstan model objects, sparklyr data objects, and database connection objects. These objects cannot be exported to parallel workers (e.g. for tar_make_future()) without special treatment. To send an non-exportable object to a parallel worker, the object must be marshalled: converted into a form that can be exported safely (similar to serialization but not always the same). Then, the worker must unmarshal the object: convert it into a form that is usable and valid in the current R session. Arguments marshal and unmarshal of tar_format() let you control how marshalling and unmarshalling happens.

Format functions

In tar_format(), functions like read, write, marshal, and unmarshal must be perfectly pure and perfectly self-sufficient. They must load or namespace all their own packages, and they must not depend on any custom user-defined functions or objects in the global environment of your pipeline. targets converts each function to and from text, so it must not rely on any data in the closure. This disqualifies functions produced by Vectorize(), for example.

The write function must write only a single file, and the file it writes must not be a directory.

The functions to read and write the object should not do any conversions on the object. That is the job of the convert argument. The convert argument is a function that accepts the object returned by the command of the target and changes it into an acceptable format (e.g. can be saved with the read function). Working with the convert function is best because it ensures the in-memory copy of an object during the running pipeline session is the same as the copy of the object that is saved to disk.

See Also

Other storage: tar_load(), tar_load_everything(), tar_objects(), tar_read()

Examples

# The following target is equivalent to the current superseded
# tar_target(name, command(), format = "keras").
# An improved version of this would supply a `convert` argument
# to handle NULL objects, which are returned by the target if it
# errors and the error argument of tar_target() is "null".
tar_target(
  name = keras_target,
  command = your_function(),
  format = tar_format(
    read = function(path) {
      keras::load_model_hdf5(path)
    },
    write = function(object, path) {
      keras::save_model_hdf5(object = object, filepath = path)
    },
    marshal = function(object) {
      keras::serialize_model(object)
    },
    unmarshal = function(object) {
      keras::unserialize_model(object)
    }
  )
)
# And the following is equivalent to the current superseded
# tar_target(name, torch::torch_tensor(seq_len(4)), format = "torch"),
# except this version has a `convert` argument to handle
# cases when `NULL` is returned (e.g. if the target errors out
# and the `error` argument is "null" in tar_target()
# or tar_option_set())
tar_target(
  name = torch_target,
  command = torch::torch_tensor(),
  format = tar_format(
    read = function(path) {
      torch::torch_load(path)
    },
    write = function(object, path) {
      torch::torch_save(obj = object, path = path)
    },
    marshal = function(object) {
      con <- rawConnection(raw(), open = "wr")
      on.exit(close(con))
      torch::torch_save(object, con)
      rawConnectionValue(con)
    },
    unmarshal = function(object) {
      con <- rawConnection(object, open = "r")
      on.exit(close(con))
      torch::torch_load(con)
    }
  )
)

Current storage format.

Description

Get the storage format of the target currently running.

Usage

tar_format_get()

Details

This function is meant to be called inside a target in a running pipeline. If it is called outside a target in the running pipeline, it will return the default format given by tar_option_get("format").

Value

A character string, storage format of the target currently running in the pipeline. If called outside a target in the running pipeline, tar_format_get() will return the default format given by tar_option_get("format").

See Also

Other utilities: tar_active(), tar_backoff(), tar_call(), tar_cancel(), tar_definition(), tar_described_as(), tar_envir(), 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

tar_target(x, tar_format_get(), format = "qs")

Set up GitHub Actions to run a targets pipeline

Description

Writes a GitHub Actions workflow file so the pipeline runs on every push to GitHub. Historical runs accumulate in the targets-runs branch, and the latest output is restored before tar_make() so up-to-date targets do not rerun.

Usage

tar_github_actions(
  path = file.path(".github", "workflows", "targets.yaml"),
  ask = NULL
)

Arguments

Details

Steps to set up continuous deployment:

1. Ensure your pipeline stays within the resource limitations of GitHub Actions and repositories, both for storage and compute. For storage, you may wish to reduce the burden with an alternative repository (e.g. tar_target(..., repository = "aws")).

2. Ensure Actions are enabled in your GitHub repository. You may have to visit the Settings tab.

3. Call targets::tar_renv(extras = character(0)) to expose hidden package dependencies.

4. Set up renv for your project (with renv::init() or renv::snapshot()). Details at https://rstudio.github.io/renv/articles/ci.html.

5. Commit the renv.lock file to the main (recommended) or master Git branch.

6. Run tar_github_actions() to create the workflow file. Commit this file to main (recommended) or master in Git.

7. Push your project to GitHub. Verify that a GitHub Actions workflow runs and pushes results to targets-runs. Subsequent runs will only recompute the outdated targets.

Value

Nothing (invisibly). This function writes a GitHub Actions workflow file as a side effect.

See Also

Other scripts: tar_edit(), tar_helper(), tar_renv(), tar_script()

Examples

tar_github_actions(tempfile())

Visualize an abridged fast dependency graph.

Description

Analyze the pipeline defined in the target script file (default: ⁠_targets.R⁠) and visualize the directed acyclic graph of targets. Unlike tar_visnetwork(), tar_glimpse() does not account for metadata or progress information, which means the graph renders faster. Also, tar_glimpse() omits functions and other global objects by default (but you can include them with targets_only = FALSE).

Usage

tar_glimpse(
  targets_only = TRUE,
  names = NULL,
  shortcut = FALSE,
  allow = NULL,
  exclude = ".Random.seed",
  label = targets::tar_config_get("label"),
  label_width = targets::tar_config_get("label_width"),
  level_separation = targets::tar_config_get("level_separation"),
  degree_from = 1L,
  degree_to = 1L,
  zoom_speed = 1,
  physics = FALSE,
  callr_function = callr::r,
  callr_arguments = targets::tar_callr_args_default(callr_function),
  envir = parent.frame(),
  script = targets::tar_config_get("script"),
  store = targets::tar_config_get("store")
)

Arguments

Value

A visNetwork HTML widget object.

Dependency graph

The dependency graph of a pipeline is a directed acyclic graph (DAG) where each node indicates a target or global object and each directed edge indicates where a downstream node depends on an upstream node. The DAG is not always a tree, but it never contains a cycle because no target is allowed to directly or indirectly depend on itself. The dependency graph should show a natural progression of work from left to right. targets uses static code analysis to create the graph, so the order of tar_target() calls in the ⁠_targets.R⁠ file does not matter. However, targets does not support self-referential loops or other cycles. For more information on the dependency graph, please read https://books.ropensci.org/targets/targets.html#dependencies.

Storage access

Several functions like tar_make(), tar_read(), tar_load(), tar_meta(), and tar_progress() read or modify the local data store of the pipeline. The local data store is in flux while a pipeline is running, and depending on how distributed computing or cloud computing is set up, not all targets can even reach it. So please do not call these functions from inside a target as part of a running pipeline. The only exception is literate programming target factories in the tarchetypes package such as tar_render() and tar_quarto().

See Also

Other visualize: tar_mermaid(), tar_visnetwork()

Examples

if (identical(Sys.getenv("TAR_INTERACTIVE_EXAMPLES"), "true")) {
tar_dir({ # tar_dir() runs code from a temp dir for CRAN.
tar_script({
  library(targets)
  library(tarchetypes)
  tar_option_set()
  list(
    tar_target(y1, 1 + 1),
    tar_target(y2, 1 + 1),
    tar_target(z, y1 + y2)
  )
}, ask = FALSE)
tar_glimpse()
tar_glimpse(allow = starts_with("y")) # see also any_of()
})
}

Group a data frame to iterate over subsets of rows.

Description

Like dplyr::group_by(), but for patterns. tar_group() allows you to map or cross over subsets of data frames. Requires iteration = "group" on the target. See the example.

Usage

tar_group(x)

Arguments

Details

The goal of tar_group() is to post-process the return value of a data frame target to allow downstream targets to branch over subsets of rows. It takes the groups defined by dplyr::group_by() and translates that information into a special tar_group is a column. tar_group is a vector of positive integers from 1 to the number of groups. Rows with the same integer in tar_group belong to the same group, and branches are arranged in increasing order with respect to the integers in tar_group. The assignment of tar_group integers to group levels depends on the orderings inside the grouping variables and not the order of rows in the dataset. dplyr::group_keys() on the grouped data frame shows how the grouping variables correspond to the integers in the tar_group column.

Value

A data frame with a special tar_group column that targets will use to find subsets of your data frame.

See Also

Other utilities: tar_active(), tar_backoff(), tar_call(), tar_cancel(), tar_definition(), tar_described_as(), tar_envir(), tar_format_get(), 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
# The tar_group() function simply creates
# a tar_group column to partition the rows
# of a data frame.
data.frame(
  x = seq_len(6),
  id = rep(letters[seq_len(3)], each = 2)
) %>%
  dplyr::group_by(id) %>%
  tar_group()
# We use tar_group() below to branch over
# subsets of a data frame defined with dplyr::group_by().
tar_dir({ # tar_dir() runs code from a temp dir for CRAN.
tar_script({
library(dplyr)
library(targets)
library(tarchetypes)
list(
  tar_target(
    data,
    data.frame(
      x = seq_len(6),
      id = rep(letters[seq_len(3)], each = 2)
    ) %>%
      group_by(id) %>%
      tar_group(),
    iteration = "group"
  ),
  tar_target(
    sums,
    sum(data$x),
    pattern = map(data),
    iteration = "vector"
  )
)
})
tar_make()
tar_read(sums) # Should be c(3, 7, 11).
})
}

Write a helper R script.

Description

Write a helper R script for a targets pipeline. Could be supporting functions or the target script file (default: ⁠_targets.R⁠) itself.

tar_helper() expects an unevaluated expression for the code argument, whereas tar_helper_raw() expects an evaluated expression object.

Usage

tar_helper(path = NULL, code = NULL, tidy_eval = TRUE, envir = parent.frame())

tar_helper_raw(path = NULL, code = NULL)

Arguments

Details

tar_helper() is a specialized version of tar_script() with flexible paths and tidy evaluation.

Value

NULL (invisibly)

See Also

Other scripts: tar_edit(), tar_github_actions(), tar_renv(), tar_script()

Examples

# Without tidy evaluation:
path <- tempfile()
tar_helper(path, code = x <- 1)
tar_helper_raw(path, code = quote(x <- 1)) # equivalent
writeLines(readLines(path))
# With tidy evaluation:
y <- 123
tar_helper(path, x <- !!y)
writeLines(readLines(path))

Run if Target Markdown interactive mode is on.

Description

In Target Markdown, run the enclosed code only if interactive mode is activated. Otherwise, do not run the code.

Usage

tar_interactive(code)

Arguments

Details

Visit <books.ropensci.org/targets/literate-programming.html> to learn about Target Markdown and interactive mode.

Value

If Target Markdown interactive mode is turned on, the function returns the result of running the code. Otherwise, the function invisibly returns NULL.

See Also

Other Target Markdown: tar_engine_knitr(), tar_noninteractive(), tar_toggle()

Examples

tar_interactive(message("In interactive mode."))

Delete one or more metadata records (e.g. to rerun a target).

Description

Delete the metadata of records in ⁠_targets/meta/meta⁠ but keep the return values of targets in ⁠_targets/objects/⁠.

Usage

tar_invalidate(names, store = targets::tar_config_get("store"))

Arguments

Details

This function forces one or more targets to rerun on the next tar_make(), regardless of the cues and regardless of how those targets are stored. After tar_invalidate(), you will still be able to locate the data files with tar_path_target() and manually salvage them in an emergency. However, tar_load() and tar_read() will not be able to read the data into R, and subsequent calls to tar_make() will attempt to rerun those targets. For patterns recorded in the metadata, all the branches will be invalidated. For patterns no longer in the metadata, branches are left alone.

Value

NULL (invisibly).

Storage access

Several functions like tar_make(), tar_read(), tar_load(), tar_meta(), and tar_progress() read or modify the local data store of the pipeline. The local data store is in flux while a pipeline is running, and depending on how distributed computing or cloud computing is set up, not all targets can even reach it. So please do not call these functions from inside a target as part of a running pipeline. The only exception is literate programming target factories in the tarchetypes package such as tar_render() and tar_quarto().

See Also

Other clean: tar_delete(), tar_destroy(), tar_prune(), tar_prune_list(), tar_unversion()

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(y1, 1 + 1),
    tar_target(y2, 1 + 1),
    tar_target(z, y1 + y2)
  )
}, ask = FALSE)
tar_make()
tar_invalidate(starts_with("y")) # Only invalidates y1 and y2.
tar_make() # y1 and y2 rerun but return same values, so z is up to date.
})
}

Language

Description

These functions help with metaprogramming in packages built on top of targets.

Usage

tar_deparse_language(expr)

tar_deparse_safe(expr, collapse = "\n", backtick = TRUE)

tar_tidy_eval(expr, envir, tidy_eval)

tar_tidyselect_eval(names_quosure, choices)

Arguments

Details

• tar_deparse_language() is a wrapper around tar_deparse_safe() which leaves character vectors and NULL objects alone, which helps with subsequent user input validation.

• tar_deparse_safe() is a wrapper around base::deparse() with a custom set of fast default settings and guardrails to ensure the output always has length 1.

• tar_tidy_eval() applies tidy evaluation to a language object and returns another language object.

• tar_tidyselect_eval() applies tidyselect selection with some special guardrails around NULL inputs.

See Also

Other utilities to extend targets: tar_assert, tar_condition, tar_test()

Examples

tar_deparse_language(quote(run_model()))

Load the values of targets.

Description

Load the return values of targets into the current environment (or the environment of your choosing). For a typical target, the return value lives in a file in ⁠_targets/objects/⁠. For file targets (i.e. format = "file") the paths loaded in place of the values. tar_load_everything() is shorthand for tar_load(everything()) to load all targets.

tar_load() uses non-standard evaluation in the names argument (example: tar_load(names = everything())), whereas tar_load_raw() uses standard evaluation for names (example: tar_load_raw(names = quote(everything()))).

Usage

tar_load(
  names,
  branches = NULL,
  meta = targets::tar_meta(targets_only = TRUE, store = store),
  strict = TRUE,
  silent = FALSE,
  envir = parent.frame(),
  store = targets::tar_config_get("store")
)

tar_load_raw(
  names,
  branches = NULL,
  meta = tar_meta(store = store),
  strict = TRUE,
  silent = FALSE,
  envir = parent.frame(),
  store = targets::tar_config_get("store")
)

Arguments

Value

Nothing.

Storage access

Several functions like tar_make(), tar_read(), tar_load(), tar_meta(), and tar_progress() read or modify the local data store of the pipeline. The local data store is in flux while a pipeline is running, and depending on how distributed computing or cloud computing is set up, not all targets can even reach it. So please do not call these functions from inside a target as part of a running pipeline. The only exception is literate programming target factories in the tarchetypes package such as tar_render() and tar_quarto().

Cloud target data versioning

Some buckets in Amazon S3 or Google Cloud Storage are "versioned", which means they track historical versions of each data object. If you use targets with cloud storage (https://books.ropensci.org/targets/cloud-storage.html) and versioning is turned on, then targets will record each version of each target in its metadata.

Functions like tar_read() and tar_load() load the version recorded in the local metadata, which may not be the same as the "current" version of the object in the bucket. Likewise, functions tar_delete() and tar_destroy() only remove the version ID of each target as recorded in the local metadata.

If you want to interact with the latest version of an object instead of the version ID recorded in the local metadata, then you will need to delete the object from the metadata.

1. Make sure your local copy of the metadata is current and up to date. You may need to run tar_meta_download() or tar_meta_sync() first.

2. Run tar_unversion() to remove the recorded version IDs of your targets in the local metadata.

3. With the version IDs gone from the local metadata, functions like tar_read() and tar_destroy() will use the latest version of each target data object.

4. Optional: to back up the local metadata file with the version IDs deleted, use tar_meta_upload().

See Also

Other storage: tar_format(), tar_load_everything(), tar_objects(), tar_read()

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(y1, 1 + 1),
    tar_target(y2, 1 + 1),
    tar_target(z, y1 + y2)
  )
}, ask = FALSE)
tar_make()
ls() # Does not have "y1", "y2", or "z".
tar_load(starts_with("y"))
ls() # Has "y1" and "y2" but not "z".
tar_load_raw(quote(any_of("z")))
ls() # Has "y1", "y2", and "z".
})
}

Load the values of all available targets.

Description

Shorthand for tar_load(everything()) to load all targets with entries in the metadata.

Usage

tar_load_everything(
  branches = NULL,
  meta = tar_meta(targets_only = TRUE, store = store),
  strict = TRUE,
  silent = FALSE,
  envir = parent.frame(),
  store = targets::tar_config_get("store")
)

Arguments

Value

Nothing.

See Also

Other storage: tar_format(), tar_load(), tar_objects(), tar_read()

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(y1, 1 + 1),
    tar_target(y2, 1 + 1),
    tar_target(z, y1 + y2)
  )
}, ask = FALSE)
tar_make()
ls() # Does not have "y1", "y2", or "z".
tar_load_everything()
ls() # Has "y1", "y2", and "z".
})
}

Load globals for debugging, testing, and prototyping

Description

Load user-defined packages, functions, global objects, and settings defined in the target script file (default: ⁠_targets.R⁠). This function is for debugging, testing, and prototyping only. It is not recommended for use inside a serious pipeline or to report the results of a serious pipeline.

Usage

tar_load_globals(
  envir = parent.frame(),
  script = targets::tar_config_get("script")
)

Arguments

Details

This function first sources the target script file (default: ⁠_targets.R⁠) to loads all user-defined functions, global objects, and settings into the current R process. Then, it loads all the packages defined in tar_option_get("packages") (default: (.packages())) using library() with lib.loc defined in tar_option_get("library") (default: NULL).

Value

NULL (invisibly).

Storage access

Several functions like tar_make(), tar_read(), tar_load(), tar_meta(), and tar_progress() read or modify the local data store of the pipeline. The local data store is in flux while a pipeline is running, and depending on how distributed computing or cloud computing is set up, not all targets can even reach it. So please do not call these functions from inside a target as part of a running pipeline. The only exception is literate programming target factories in the tarchetypes package such as tar_render() and tar_quarto().

See Also

Other debug: tar_traceback(), tar_workspace(), tar_workspace_download(), tar_workspaces()

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)
  tar_option_set(packages = "callr")
  analyze_data <- function(data) {
    summary(data)
  }
  list(
    tar_target(x, 1 + 1),
    tar_target(y, 1 + 1)
  )
}, ask = FALSE)
tar_load_globals()
print(analyze_data)
print("callr" %in% (.packages()))
})
}

Run a pipeline of targets.

Description

Run the pipeline you defined in the targets script file (default: ⁠_targets.R⁠). tar_make() runs the correct targets in the correct order and stores the return values in ⁠_targets/objects/⁠. Use tar_read() to read a target back into R, and see https://docs.ropensci.org/targets/reference/index.html#clean to manage output files.

Usage

tar_make(
  names = NULL,
  shortcut = targets::tar_config_get("shortcut"),
  reporter = targets::tar_config_get("reporter_make"),
  seconds_meta_append = targets::tar_config_get("seconds_meta_append"),
  seconds_meta_upload = targets::tar_config_get("seconds_meta_upload"),
  seconds_reporter = targets::tar_config_get("seconds_reporter"),
  seconds_interval = targets::tar_config_get("seconds_interval"),
  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"),
  garbage_collection = NULL,
  use_crew = targets::tar_config_get("use_crew"),
  terminate_controller = TRUE,
  as_job = targets::tar_config_get("as_job")
)

Arguments

Value

NULL except if callr_function = callr::r_bg(), in which case a handle to the callr background process is returned. Either way, the value is invisibly returned.

Storage access

Several functions like tar_make(), tar_read(), tar_load(), tar_meta(), and tar_progress() read or modify the local data store of the pipeline. The local data store is in flux while a pipeline is running, and depending on how distributed computing or cloud computing is set up, not all targets can even reach it. So please do not call these functions from inside a target as part of a running pipeline. The only exception is literate programming target factories in the tarchetypes package such as tar_render() and tar_quarto().

See Also

Other pipeline: tar_make_clustermq(), tar_make_future()

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(y1, 1 + 1),
    tar_target(y2, 1 + 1),
    tar_target(z, y1 + y2)
  )
}, ask = FALSE)
tar_make(starts_with("y")) # Only processes y1 and y2.
# Distributed computing with crew:
if (requireNamespace("crew", quietly = TRUE)) {
tar_script({
  library(targets)
  library(tarchetypes)
  tar_option_set(controller = crew::controller_local())
  list(
    tar_target(y1, 1 + 1),
    tar_target(y2, 1 + 1),
    tar_target(z, y1 + y2)
  )
}, ask = FALSE)
tar_make()
}
})
}

Superseded. Run a pipeline with persistent clustermq workers.

Description

Superseded. Use tar_make() with crew: https://books.ropensci.org/targets/crew.html.

Usage

tar_make_clustermq(
  names = NULL,
  shortcut = targets::tar_config_get("shortcut"),
  reporter = targets::tar_config_get("reporter_make"),
  seconds_meta_append = targets::tar_config_get("seconds_meta_append"),
  seconds_meta_upload = targets::tar_config_get("seconds_meta_upload"),
  seconds_reporter = targets::tar_config_get("seconds_reporter"),
  seconds_interval = targets::tar_config_get("seconds_interval"),
  workers = targets::tar_config_get("workers"),
  log_worker = FALSE,
  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"),
  garbage_collection = NULL
)

Arguments

Details

tar_make_clustermq() is like tar_make() except that targets run in parallel on persistent workers. A persistent worker is an R process that runs for a long time and runs multiple targets during its lifecycle. Persistent workers launch as soon as the pipeline reaches an outdated target with deployment = "worker", and they keep running until the pipeline starts to wind down.

To configure tar_make_clustermq(), you must configure the clustermq package. To do this, set global options clustermq.scheduler and clustermq.template inside the target script file (default: ⁠_targets.R⁠). To read more about configuring clustermq for your scheduler, visit https://mschubert.github.io/clustermq/articles/userguide.html#configuration # nolint or https://books.ropensci.org/targets/hpc.html. clustermq is not a strict dependency of targets, so you must install clustermq yourself.

Value

NULL except if callr_function = callr::r_bg(), in which case a handle to the callr background process is returned. Either way, the value is invisibly returned.

Storage access

Several functions like tar_make(), tar_read(), tar_load(), tar_meta(), and tar_progress() read or modify the local data store of the pipeline. The local data store is in flux while a pipeline is running, and depending on how distributed computing or cloud computing is set up, not all targets can even reach it. So please do not call these functions from inside a target as part of a running pipeline. The only exception is literate programming target factories in the tarchetypes package such as tar_render() and tar_quarto().

See Also

Other pipeline: tar_make(), tar_make_future()

Examples

if (!identical(tolower(Sys.info()[["sysname"]]), "windows")) {
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)
  options(clustermq.scheduler = "multiprocess") # Does not work on Windows.
  tar_option_set()
  list(tar_target(x, 1 + 1))
}, ask = FALSE)
tar_make_clustermq()
})
}
}

Superseded. Run a pipeline of targets in parallel with transient future workers.

Description

Superseded. Use tar_make() with crew: https://books.ropensci.org/targets/crew.html.

Usage

tar_make_future(
  names = NULL,
  shortcut = targets::tar_config_get("shortcut"),
  reporter = targets::tar_config_get("reporter_make"),
  seconds_meta_append = targets::tar_config_get("seconds_meta_append"),
  seconds_meta_upload = targets::tar_config_get("seconds_meta_upload"),
  seconds_reporter = targets::tar_config_get("seconds_reporter"),
  seconds_interval = targets::tar_config_get("seconds_interval"),
  workers = targets::tar_config_get("workers"),
  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"),
  garbage_collection = NULL
)

Arguments

Details

This function is like tar_make() except that targets run in parallel with transient future workers. It requires that you declare your future::plan() inside the target script file (default: ⁠_targets.R⁠). future is not a strict dependency of targets, so you must install future yourself.

To configure tar_make_future() with a computing cluster, see the future.batchtools package documentation.

Value

NULL except if callr_function = callr::r_bg(), in which case a handle to the callr background process is returned. Either way, the value is invisibly returned.

Storage access

Several functions like tar_make(), tar_read(), tar_load(), tar_meta(), and tar_progress() read or modify the local data store of the pipeline. The local data store is in flux while a pipeline is running, and depending on how distributed computing or cloud computing is set up, not all targets can even reach it. So please do not call these functions from inside a target as part of a running pipeline. The only exception is literate programming target factories in the tarchetypes package such as tar_render() and tar_quarto().

See Also

Other pipeline: tar_make(), tar_make_clustermq()

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)
  future::plan(future::multisession, workers = 2)
  list(
    tar_target(x, 1 + 1),
    tar_target(y, 1 + 1)
  )
}, ask = FALSE)
tar_make_future()
})
}

Interactive mode pipeline

Description

Not a user-side function. Do not invoke directly. Only exported to on a technicality.

Usage

tar_make_interactive(code)

Arguments

Value

NULL (invisibly).

Examples

if (identical(Sys.getenv("TAR_INTERACTIVE_EXAMPLES"), "true")) {
tar_make_interactive("library(targets); tar_target(x, 123)")
message(x)
}

Produce a data frame of information about your targets.

Description

Along with tar_visnetwork() and tar_glimpse(), tar_manifest() helps check that you constructed your pipeline correctly.

Usage

tar_manifest(
  names = NULL,
  fields = tidyselect::any_of(c("name", "command", "pattern", "description")),
  drop_missing = TRUE,
  callr_function = callr::r,
  callr_arguments = targets::tar_callr_args_default(callr_function),
  envir = parent.frame(),
  script = targets::tar_config_get("script")
)

Arguments

Value

A data frame of information about the targets in the pipeline. Rows appear in topological order (the order they will run without any influence from parallel computing or priorities).

Storage access

Several functions like tar_make(), tar_read(), tar_load(), tar_meta(), and tar_progress() read or modify the local data store of the pipeline. The local data store is in flux while a pipeline is running, and depending on how distributed computing or cloud computing is set up, not all targets can even reach it. So please do not call these functions from inside a target as part of a running pipeline. The only exception is literate programming target factories in the tarchetypes package such as tar_render() and tar_quarto().

See Also

Other inspect: tar_deps(), tar_network(), tar_outdated(), tar_sitrep(), tar_validate()

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)
  tar_option_set()
  list(
    tar_target(y1, 1 + 1),
    tar_target(y2, 1 + 1),
    tar_target(z, y1 + y2),
    tar_target(m, z, pattern = map(z), description = "branching over z"),
    tar_target(c, z, pattern = cross(z))
  )
}, ask = FALSE)
tar_manifest()
tar_manifest(fields = any_of(c("name", "command")))
tar_manifest(fields = any_of("command"))
tar_manifest(fields = starts_with("cue"))
})
}

mermaid.js dependency graph.

Description

Visualize the dependency graph with a static mermaid.js graph.

Usage

tar_mermaid(
  targets_only = FALSE,
  names = NULL,
  shortcut = FALSE,
  allow = NULL,
  exclude = ".Random.seed",
  outdated = TRUE,
  label = targets::tar_config_get("label"),
  label_width = targets::tar_config_get("label_width"),
  legend = TRUE,
  color = TRUE,
  reporter = targets::tar_config_get("reporter_outdated"),
  seconds_reporter = targets::tar_config_get("seconds_reporter_outdated"),
  callr_function = callr::r,
  callr_arguments = targets::tar_callr_args_default(callr_function),
  envir = parent.frame(),
  script = targets::tar_config_get("script"),
  store = targets::tar_config_get("store")
)

Arguments

* `"balanced"`: a reporter that balances efficiency
  with informative detail.
  Uses a `cli` progress bar instead of printing messages
  for individual dynamic branches.
  To the right of the progress bar is a text string like
  "22.6s, 4510+, 124-" (22.6 seconds elapsed, 4510 targets
  detected as outdated so far,
  124 targets detected as up to date so far).

  For best results with the balanced reporter, you may need to
  adjust your `cli` settings. See global options `cli.num_colors`
  and `cli.dynamic` at
  <https://cli.r-lib.org/reference/cli-config.html>.
  On that page is also the `CLI_TICK_TIME` environment variable
  which controls the time delay between progress bar updates.
  If the delay is too low, then overhead from printing to the console
  may slow down the pipeline.
* `"terse"`: like `"balanced"`, except without a progress bar.
* `"silent"`: print nothing.

Details

mermaid.js is a JavaScript library for constructing static visualizations of graphs.

Value

A character vector of lines of code of the mermaid.js graph. You can visualize the graph by copying the text into a public online mermaid.js editor or a mermaid GitHub code chunk (⁠https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/⁠). Alternatively, you can render it inline in an R Markdown or Quarto document using a results = "asis" code chunk like so:

  ```{r, results = "asis", echo = FALSE}
  cat(c("```{mermaid}", targets::tar_mermaid(), "```"), sep = "\n")
  ```

Dependency graph

The dependency graph of a pipeline is a directed acyclic graph (DAG) where each node indicates a target or global object and each directed edge indicates where a downstream node depends on an upstream node. The DAG is not always a tree, but it never contains a cycle because no target is allowed to directly or indirectly depend on itself. The dependency graph should show a natural progression of work from left to right. targets uses static code analysis to create the graph, so the order of tar_target() calls in the ⁠_targets.R⁠ file does not matter. However, targets does not support self-referential loops or other cycles. For more information on the dependency graph, please read https://books.ropensci.org/targets/targets.html#dependencies.

Storage access

Several functions like tar_make(), tar_read(), tar_load(), tar_meta(), and tar_progress() read or modify the local data store of the pipeline. The local data store is in flux while a pipeline is running, and depending on how distributed computing or cloud computing is set up, not all targets can even reach it. So please do not call these functions from inside a target as part of a running pipeline. The only exception is literate programming target factories in the tarchetypes package such as tar_render() and tar_quarto().

See Also

Other visualize: tar_glimpse(), tar_visnetwork()

Examples

if (identical(Sys.getenv("TAR_INTERACTIVE_EXAMPLES"), "true")) {
tar_dir({ # tar_dir() runs code from a temp dir for CRAN.
tar_script({
  library(targets)
  library(tarchetypes)
  tar_option_set()
  list(
    tar_target(y1, 1 + 1),
    tar_target(y2, 1 + 1),
    tar_target(z, y1 + y2, description = "sum of two other sums")
  )
})
# Copy the text into a mermaid.js online editor
# or a mermaid GitHub code chunk:
tar_mermaid()
})
}

Read a project's metadata.

Description

Read the metadata of all recorded targets and global objects.

Usage

tar_meta(
  names = NULL,
  fields = NULL,
  targets_only = FALSE,
  complete_only = FALSE,
  store = targets::tar_config_get("store")
)

Arguments

Details

A metadata row only updates when the target completes. tar_progress() shows information on targets that are running. That is why the number of branches may disagree between tar_meta() and tar_progress() for actively running pipelines.

Value

A data frame with one row per target/object and the selected fields.

Storage access

Several functions like tar_make(), tar_read(), tar_load(), tar_meta(), and tar_progress() read or modify the local data store of the pipeline. The local data store is in flux while a pipeline is running, and depending on how distributed computing or cloud computing is set up, not all targets can even reach it. So please do not call these functions from inside a target as part of a running pipeline. The only exception is literate programming target factories in the tarchetypes package such as tar_render() and tar_quarto().

Cloud metadata

Metadata files help targets read data objects and decide if the pipeline is up to date. Usually, these metadata files live in files in the local ⁠_targets/meta/⁠ folder in your project, e.g. ⁠_targets/meta/meta⁠. But in addition, if you set repository to anything other than "local" in tar_option_set() in ⁠_targets.R⁠, then tar_make() continuously uploads the metadata files to the bucket you specify in resources. tar_meta_delete() will delete those files from the cloud, and so will tar_destroy() if destroy is set to either "all" or "cloud".

Other functions in targets, such as tar_meta(), tar_visnetwork(), tar_outdated(), and tar_invalidate(), use the local metadata only and ignore the copies on the cloud. So if you are working on a different computer than the one running the pipeline, you will need to download the cloud metadata to your current machine using tar_meta_download(). Other functions tar_meta_upload(), tar_meta_sync(), and tar_meta_delete() also manage metadata across the cloud and the local file system.

Remarks:

• The repository_meta option in tar_option_set() is actually what controls where the metadata lives in the cloud, but it defaults to repository.

• Like tar_make(), tar_make_future() and tar_make_clustermq() also continuously upload metadata files to the cloud bucket specified in resources.

• tar_meta_download() and related functions need to run ⁠_targets.R⁠ to detect tar_option_set() options repository_meta and resources, so please be aware of side effects that may happen running your custom ⁠_targets.R⁠ file.

See Also

Other metadata: tar_meta_delete(), tar_meta_download(), tar_meta_sync(), tar_meta_upload()

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(x, seq_len(2)),
    tar_target(y, 2 * x, pattern = map(x))
  )
}, ask = FALSE)
tar_make()
tar_meta()
tar_meta(starts_with("y_")) # see also any_of()
})
}

Delete metadata.

Description

Delete the project metadata files from the local file system, the cloud, or both.

Usage

tar_meta_delete(
  meta = TRUE,
  progress = TRUE,
  process = TRUE,
  crew = TRUE,
  verbose = TRUE,
  delete = "all",
  script = targets::tar_config_get("script"),
  store = targets::tar_config_get("store")
)

Arguments

See Also

Other metadata: tar_meta(), tar_meta_download(), tar_meta_sync(), tar_meta_upload()

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)
  tar_option_set(
    resources = tar_resources(
      aws = tar_resources_aws(
        bucket = "YOUR_BUCKET_NAME",
        prefix = "YOUR_PROJECT_NAME"
      )
    ),
    repository = "aws"
  )
  list(
    tar_target(x, data.frame(x = seq_len(2), y = seq_len(2)))
  )
})
tar_make()
tar_meta_delete()
})
}

download local metadata to the cloud.

Description

download local metadata files to the cloud location (repository, bucket, and prefix) you set in tar_option_set() in ⁠_targets.R⁠.

Usage

tar_meta_download(
  meta = TRUE,
  progress = TRUE,
  process = TRUE,
  crew = TRUE,
  verbose = TRUE,
  strict = FALSE,
  script = targets::tar_config_get("script"),
  store = targets::tar_config_get("store")
)

Arguments

See Also

Other metadata: tar_meta(), tar_meta_delete(), tar_meta_sync(), tar_meta_upload()

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)
  tar_option_set(
    resources = tar_resources(
      aws = tar_resources_aws(
        bucket = "YOUR_BUCKET_NAME",
        prefix = "YOUR_PROJECT_NAME"
      )
    ),
    repository = "aws"
  )
  list(
    tar_target(x, data.frame(x = seq_len(2), y = seq_len(2)))
  )
})
tar_make()
tar_meta_download()
})
}

Synchronize cloud metadata.

Description

Synchronize metadata in a cloud bucket with metadata in the local data store.

Usage

tar_meta_sync(
  meta = TRUE,
  progress = TRUE,
  process = TRUE,
  crew = TRUE,
  verbose = TRUE,
  prefer_local = TRUE,
  script = targets::tar_config_get("script"),
  store = targets::tar_config_get("store")
)

Arguments

Details

tar_meta_sync() synchronizes the local and cloud copies of all the metadata files of the pipeline so that both have the most recent copy. For each metadata file, if the local file does not exist or is older than the cloud file, then the cloud file is downloaded to the local file path. Conversely, if the cloud file is older or does not exist, then the local file is uploaded to the cloud. If the time stamps of these files are equal, use the prefer_local argument to determine which copy takes precedence.

See Also

Other metadata: tar_meta(), tar_meta_delete(), tar_meta_download(), tar_meta_upload()

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)
  tar_option_set(
    resources = tar_resources(
      aws = tar_resources_aws(
        bucket = "YOUR_BUCKET_NAME",
        prefix = "YOUR_PROJECT_NAME"
      )
    ),
    repository = "aws"
  )
  list(
    tar_target(x, data.frame(x = seq_len(2), y = seq_len(2)))
  )
}, ask = FALSE)
tar_make()
tar_meta_sync()
})
}

Upload local metadata to the cloud.

Description

Upload local metadata files to the cloud location (repository, bucket, and prefix) you set in tar_option_set() in ⁠_targets.R⁠.

Usage

tar_meta_upload(
  meta = TRUE,
  progress = TRUE,
  process = TRUE,
  crew = TRUE,
  verbose = TRUE,
  strict = FALSE,
  script = targets::tar_config_get("script"),
  store = targets::tar_config_get("store")
)

Arguments

See Also

Other metadata: tar_meta(), tar_meta_delete(), tar_meta_download(), tar_meta_sync()

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)
  tar_option_set(
    resources = tar_resources(
      aws = tar_resources_aws(
        bucket = "YOUR_BUCKET_NAME",
        prefix = "YOUR_PROJECT_NAME"
      )
    ),
    repository = "aws"
  )
  list(
    tar_target(x, data.frame(x = seq_len(2), y = seq_len(2)))
  )
}, ask = FALSE)
tar_make()
tar_meta_upload()
})
}

Get the name of the target currently running.

Description

Get the name of the target currently running.

Usage

tar_name(default = "target")

Arguments

Value

Character of length 1. If called inside a pipeline, tar_name() returns name of the target currently running. Otherwise, the return value is default.

See Also

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

Examples

tar_name()
tar_name(default = "custom_target_name")
if (identical(Sys.getenv("TAR_EXAMPLES"), "true")) { # for CRAN
tar_dir({ # tar_dir() runs code from a temp dir for CRAN.
tar_script(tar_target(x, tar_name()), ask = FALSE)
tar_make()
tar_read(x)
})
}

Return the vertices and edges of a pipeline dependency graph.

Description

Analyze the pipeline defined in the target script file (default: ⁠_targets.R⁠) and return the vertices and edges of the directed acyclic graph of dependency relationships.

Usage

tar_network(
  targets_only = FALSE,
  names = NULL,
  shortcut = FALSE,
  allow = NULL,
  exclude = NULL,
  outdated = TRUE,
  reporter = targets::tar_config_get("reporter_outdated"),
  seconds_reporter = targets::tar_config_get("seconds_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

* `"balanced"`: a reporter that balances efficiency
  with informative detail.
  Uses a `cli` progress bar instead of printing messages
  for individual dynamic branches.
  To the right of the progress bar is a text string like
  "22.6s, 4510+, 124-" (22.6 seconds elapsed, 4510 targets
  detected as outdated so far,
  124 targets detected as up to date so far).

  For best results with the balanced reporter, you may need to
  adjust your `cli` settings. See global options `cli.num_colors`
  and `cli.dynamic` at
  <https://cli.r-lib.org/reference/cli-config.html>.
  On that page is also the `CLI_TICK_TIME` environment variable
  which controls the time delay between progress bar updates.
  If the delay is too low, then overhead from printing to the console
  may slow down the pipeline.
* `"terse"`: like `"balanced"`, except without a progress bar.
* `"silent"`: print nothing.

Value

A list with two data frames: vertices and edges. The vertices data frame has one row per target and columns with the the type of the target or object (stem, branch, map, cross, function, or object), each target's description, and each target's status (up to date, outdated, dispatched, completed, canceled, or errored), as well as metadata if available (seconds of runtime, bytes of storage, and number of dynamic branches). The edges data frame has one row for every edge and columns to and from to mark the starting and terminating vertices.

Dependency graph

The dependency graph of a pipeline is a directed acyclic graph (DAG) where each node indicates a target or global object and each directed edge indicates where a downstream node depends on an upstream node. The DAG is not always a tree, but it never contains a cycle because no target is allowed to directly or indirectly depend on itself. The dependency graph should show a natural progression of work from left to right. targets uses static code analysis to create the graph, so the order of tar_target() calls in the ⁠_targets.R⁠ file does not matter. However, targets does not support self-referential loops or other cycles. For more information on the dependency graph, please read https://books.ropensci.org/targets/targets.html#dependencies.

See Also

Other inspect: tar_deps(), tar_manifest(), tar_outdated(), tar_sitrep(), tar_validate()

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)
  tar_option_set()
  list(
    tar_target(y1, 1 + 1),
    tar_target(y2, 1 + 1, description = "y2 info"),
    tar_target(z, y1 + y2, description = "z info")
  )
}, ask = FALSE)
tar_network(targets_only = TRUE)
})
}

List new targets

Description

List all the targets whose last successful run occurred after a certain point in time.

Usage

tar_newer(
  time,
  names = NULL,
  inclusive = FALSE,
  store = targets::tar_config_get("store")
)

Arguments

Details

Only applies to targets with recorded time stamps: just non-branching targets and individual dynamic branches. As of targets version 0.6.0, these time stamps are available for these targets regardless of storage format. Earlier versions of targets do not record time stamps for remote storage such as format = "url" or repository = "aws" in tar_target().

Value

A character vector of names of old targets with recorded timestamp metadata.

See Also

Other time: tar_older(), tar_timestamp()

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(x, seq_len(2)))
}, ask = FALSE)
tar_make()
# targets newer than 1 week ago
tar_newer(Sys.time() - as.difftime(1, units = "weeks"))
# targets newer than 1 week from now
tar_newer(Sys.time() + as.difftime(1, units = "weeks"))
# Everything is still up to date.
tar_make()
# Invalidate all targets targets newer than 1 week ago
# so they run on the next tar_make().
invalidate_these <- tar_newer(Sys.time() - as.difftime(1, units = "weeks"))
tar_invalidate(any_of(invalidate_these))
tar_make()
})
}

Run if Target Markdown interactive mode is not on.

Description

In Target Markdown, run the enclosed code only if interactive mode is not activated. Otherwise, do not run the code.

Usage

tar_noninteractive(code)

Arguments

Details

Visit <books.ropensci.org/targets/literate-programming.html> to learn about Target Markdown and interactive mode.

Value

If Target Markdown interactive mode is not turned on, the function returns the result of running the code. Otherwise, the function invisibly returns NULL.

See Also

Other Target Markdown: tar_engine_knitr(), tar_interactive(), tar_toggle()

Examples

tar_noninteractive(message("Not in interactive mode."))

List saved targets

Description

List targets currently saved to ⁠_targets/objects/⁠ or the cloud. Does not include local files with tar_target(..., format = "file", repository = "local").

Usage

tar_objects(
  names = NULL,
  cloud = TRUE,
  store = targets::tar_config_get("store")
)

Arguments

Value

Character vector of targets saved to ⁠_targets/objects/⁠.

Storage access

Several functions like tar_make(), tar_read(), tar_load(), tar_meta(), and tar_progress() read or modify the local data store of the pipeline. The local data store is in flux while a pipeline is running, and depending on how distributed computing or cloud computing is set up, not all targets can even reach it. So please do not call these functions from inside a target as part of a running pipeline. The only exception is literate programming target factories in the tarchetypes package such as tar_render() and tar_quarto().

See Also

Other storage: tar_format(), tar_load(), tar_load_everything(), tar_read()

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(x, "value"))
}, ask = FALSE)
tar_make()
tar_objects()
tar_objects(starts_with("x")) # see also any_of()
})
}

List old targets

Description

List all the targets whose last successful run occurred before a certain point in time. Combine with tar_invalidate(), you can use tar_older() to automatically rerun targets at regular intervals. See the examples for a demonstration.

Usage

tar_older(
  time,
  names = NULL,
  inclusive = FALSE,
  store = targets::tar_config_get("store")
)

Arguments

Details

Only applies to targets with recorded time stamps: just non-branching targets and individual dynamic branches. As of targets version 0.6.0, these time stamps are available for these targets regardless of storage format. Earlier versions of targets do not record time stamps for remote storage such as format = "url" or repository = "aws" in tar_target().

Value

A character vector of names of old targets with recorded timestamp metadata.

See Also

Other time: tar_newer(), tar_timestamp()

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(x, seq_len(2)))
}, ask = FALSE)
tar_make()
# targets older than 1 week ago
tar_older(Sys.time() - as.difftime(1, units = "weeks"))
# targets older than 1 week from now
tar_older(Sys.time() + as.difftime(1, units = "weeks"))
# Everything is still up to date.
tar_make()
# Invalidate all targets targets older than 1 week from now
# so they run on the next tar_make().
invalidate_these <- tar_older(Sys.time() + as.difftime(1, units = "weeks"))
tar_invalidate(any_of(invalidate_these))
tar_make()
})
}

Export options.

Description

Internal function. Not for users.

Usage

tar_option_export()

Value

A list of options from tar_option_set().

Get a target option.

Description

Get a target option. These options include default arguments to tar_target() such as packages, storage format, iteration type, and cue. Needs to be called before any calls to tar_target() in order to take effect.

Usage

tar_option_get(name = NULL, option = NULL)

Arguments

Details

This function goes well with tar_target_raw() when it comes to defining external interfaces on top of the targets package to create pipelines.

Value

Value of a target option.

See Also

Other configuration: tar_config_get(), tar_config_projects(), tar_config_set(), tar_config_unset(), tar_config_yaml(), tar_envvars(), tar_option_reset(), tar_option_set(), tar_option_with()

Examples

tar_option_get("format") # default format before we set anything
tar_target(x, 1)$settings$format
tar_option_set(format = "fst_tbl") # new default format
tar_option_get("format")
tar_target(x, 1)$settings$format
tar_option_reset() # reset the format
tar_target(x, 1)$settings$format
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)
  tar_option_set(cue = tar_cue(mode = "always")) # All targets always run.
  list(tar_target(x, 1), tar_target(y, 2))
})
tar_make()
tar_make()
})
}

Reset all target options.

Description

Reset all target options you previously chose with tar_option_set(). These options are mostly configurable default arguments to tar_target() and tar_target_raw().

Usage

tar_option_reset()

Value

NULL (invisibly).

See Also

Other configuration: tar_config_get(), tar_config_projects(), tar_config_set(), tar_config_unset(), tar_config_yaml(), tar_envvars(), tar_option_get(), tar_option_set(), tar_option_with()

Examples

tar_option_get("format") # default format before we set anything
tar_target(x, 1)$settings$format
tar_option_set(format = "fst_tbl") # new default format
tar_option_get("format")
tar_target(x, 1)$settings$format
tar_option_reset() # reset all options
tar_target(x, 1)$settings$format
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)
  tar_option_set(cue = tar_cue(mode = "always"))
  tar_option_reset() # Undo option above.
  list(tar_target(x, 1), tar_target(y, 2))
})
tar_make()
tar_make()
})
}

Set target options.

Description

Set target options, including default arguments to tar_target() such as packages, storage format, iteration type, and cue. Only the non-null arguments are actually set as options. See currently set options with tar_option_get(). To use tar_option_set() effectively, put it in your workflow's target script file (default: ⁠_targets.R⁠) before calls to tar_target() or tar_target_raw().

Usage

tar_option_set(
  tidy_eval = NULL,
  packages = NULL,
  imports = NULL,
  library = NULL,
  envir = NULL,
  format = NULL,
  repository = NULL,
  repository_meta = NULL,
  iteration = NULL,
  error = NULL,
  memory = NULL,
  garbage_collection = NULL,
  deployment = NULL,
  priority = NULL,
  backoff = NULL,
  resources = NULL,
  storage = NULL,
  retrieval = NULL,
  cue = NULL,
  description = NULL,
  debug = NULL,
  workspaces = NULL,
  workspace_on_error = NULL,
  seed = NULL,
  controller = NULL,
  trust_timestamps = NULL,
  trust_object_timestamps = NULL
)

Arguments

Value

NULL (invisibly).

Storage formats

targets has several built-in storage formats to control how return values are saved and loaded from disk:

• "rds": Default, uses saveRDS() and readRDS(). Should work for most objects, but slow.

• "auto": either "file" or "qs", depending on the return value of the target. If the return value is a character vector of existing files (and/or directories), then the format becomes "file" before tar_make() saves the target. Otherwise, the format becomes "qs".

  NOTE: format = "auto" slows down pipelines with 10000+ targets because it creates deep copies of 20000+ internal data objects. Pipelines of this size should use a more explicit format instead of "auto".

• "qs": Uses qs2::qs_save() and qs2::qs_read(). Should work for most objects, much faster than "rds". Optionally configure settings through tar_resources() and tar_resources_qs().

  Prior to targets version 1.8.0.9014, format = "qs" used the qs package. qs has since been superseded in favor of qs2, and so later versions of targets use qs2 to save new data. To read existing data, targets first attempts qs2::qs_read(), and then if that fails, it falls back on qs::qread().

• "feather": Uses arrow::write_feather() and arrow::read_feather() (version 2.0). Much faster than "rds", but the value must be a data frame. Optionally set compression and compression_level in arrow::write_feather() through tar_resources() and tar_resources_feather(). Requires the arrow package (not installed by default).

• "parquet": Uses arrow::write_parquet() and arrow::read_parquet() (version 2.0). Much faster than "rds", but the value must be a data frame. Optionally set compression and compression_level in arrow::write_parquet() through tar_resources() and tar_resources_parquet(). Requires the arrow package (not installed by default).

• "fst": Uses fst::write_fst() and fst::read_fst(). Much faster than "rds", but the value must be a data frame. Optionally set the compression level for fst::write_fst() through tar_resources() and tar_resources_fst(). Requires the fst package (not installed by default).

• "fst_dt": Same as "fst", but the value is a data.table. Deep copies are made as appropriate in order to protect against the global effects of in-place modification. Optionally set the compression level the same way as for "fst".

• "fst_tbl": Same as "fst", but the value is a tibble. Optionally set the compression level the same way as for "fst".

• "keras": superseded by tar_format() and incompatible with error = "null" (in tar_target() or tar_option_set()). Uses keras::save_model_hdf5() and keras::load_model_hdf5(). The value must be a Keras model. Requires the keras package (not installed by default).

• "torch": superseded by tar_format() and incompatible with error = "null" (in tar_target() or tar_option_set()). Uses torch::torch_save() and torch::torch_load(). The value must be an object from the torch package such as a tensor or neural network module. Requires the torch package (not installed by default).

• "file": A file target. To use this format, the target needs to manually identify or save some data and return a character vector of paths to the data (must be a single file path if repository is not "local"). (These paths must be existing files and nonempty directories.) Then, targets automatically checks those files and cues the appropriate run/skip decisions if those files are out of date. Those paths must point to files or directories, and they must not contain characters | or *. All the files and directories you return must actually exist, or else targets will throw an error. (And if storage is "worker", targets will first stall out trying to wait for the file to arrive over a network file system.) If the target does not create any files, the return value should be character(0).

  If repository is not "local" and format is "file", then the character vector returned by the target must be of length 1 and point to a single file. (Directories and vectors of multiple file paths are not supported for file targets on the cloud.) That output file is uploaded to the cloud and tracked for changes where it exists in the cloud. As of targets version >= 1.11.0, the physical file is retained locally after the target runs. (Previous versions of targets deleted the file locally.)

• "url": An input URL. For this storage format, repository is implicitly "local", URL format is like format = "file" except the return value of the target is a URL that already exists and serves as input data for downstream targets. Optionally supply a custom curl handle through tar_resources() and tar_resources_url(). in new_handle(), nobody = TRUE is important because it ensures targets just downloads the metadata instead of the entire data file when it checks time stamps and hashes. The data file at the URL needs to have an ETag or a Last-Modified time stamp, or else the target will throw an error because it cannot track the data. Also, use extreme caution when trying to use format = "url" to track uploads. You must be absolutely certain the ETag and Last-Modified time stamp are fully updated and available by the time the target's command finishes running. targets makes no attempt to wait for the web server.

• A custom format can be supplied with tar_format(). For this choice, it is the user's responsibility to provide methods for (un)serialization and (un)marshaling the return value of the target.

• The formats starting with "aws_" are deprecated as of 2022-03-13 (targets version > 0.10.0). For cloud storage integration, use the repository argument instead.

Formats "rds", "file", and "url" are general-purpose formats that belong in the targets package itself. Going forward, any additional formats should be implemented with tar_format() in third-party packages like tarchetypes and geotargets (for example: tarchetypes::tar_format_nanoparquet()). Formats "qs", "fst", etc. are legacy formats from before the existence of tar_format(), and they will continue to remain in targets without deprecation.

See Also

Other configuration: tar_config_get(), tar_config_projects(), tar_config_set(), tar_config_unset(), tar_config_yaml(), tar_envvars(), tar_option_get(), tar_option_reset(), tar_option_with()

Examples

tar_option_get("format") # default format before we set anything
tar_target(x, 1)$settings$format
tar_option_set(format = "fst_tbl") # new default format
tar_option_get("format")
tar_target(x, 1)$settings$format
tar_option_reset() # reset the format
tar_target(x, 1)$settings$format
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)
  tar_option_set(cue = tar_cue(mode = "always")) # All targets always run.
  list(tar_target(x, 1), tar_target(y, 2))
})
tar_make()
tar_make()
})
}

Locally set target options.

Description

Locally set target options for the duration of an expression, without permanently modifying the global state.

Usage

tar_option_with(expression, ..., envir_with = parent.frame())

Arguments

Value

NULL (invisibly).

See Also

Other configuration: tar_config_get(), tar_config_projects(), tar_config_set(), tar_config_unset(), tar_config_yaml(), tar_envvars(), tar_option_get(), tar_option_reset(), tar_option_set()

Examples

  tar_option_with(
    tar_target(data, get_data()),
    packages = "dplyr",
    cue = tar_cue(mode = "never")
  )

Check which targets are outdated.

Description

Checks for outdated targets in the pipeline, targets that will be rerun automatically if you call tar_make() or similar. See tar_cue() for the rules that decide whether a target needs to rerun.

Usage

tar_outdated(
  names = NULL,
  shortcut = targets::tar_config_get("shortcut"),
  branches = FALSE,
  targets_only = TRUE,
  reporter = targets::tar_config_get("reporter_outdated"),
  seconds_reporter = targets::tar_config_get("seconds_reporter_outdated"),
  seconds_interval = targets::tar_config_get("seconds_interval"),
  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