targets-r

Imported from statzhero/targets-r-skill (SKILL.md). Install upstream with npx skills add statzhero/targets-r-skill. Copyright stays with the author (CC-BY-4.0).

Building Pipelines with targets

A target is a pipeline step that runs R code and caches its result. tar_make() hashes each target's code, arguments, and upstream dependencies, then skips anything still up to date.

Reference files

Consult the appropriate reference file for detailed patterns and examples:

For requests that span multiple topics (e.g. "set up a parallel pipeline that renders a Quarto report"), read several files.

Core principles

1. Functions live in R/, targets live in _targets.R. Source with tar_source().
2. Targets return one saveable value and avoid side effects (unless format = "file").
3. Track every input file. Use tar_file_read() rather than reading a literal path inside a target.
4. Prefer tarchetypes factories (tar_qs(), tar_file(), tar_parquet()) to passing format = "..." manually.
5. Read the NEWS before relying on any behavior — targets ships breaking-ish default changes roughly every minor release.

Quick reference

Minimum viable pipeline

library(targets)
library(tarchetypes)

tar_source()
tar_option_set(packages = "tidyverse", format = "qs")

list(
  tar_file_read(raw, "data/raw.csv", read = readr::read_csv(!!.x)),
  tar_target(clean, clean_data(raw)),
  tar_target(model, fit_model(clean)),
  tar_quarto(report, "report.qmd")
)

Directory layout

project/
├── _targets.R          # Pipeline (required)
├── _targets.yaml       # Optional config, multi-project support
├── R/                  # Functions sourced by tar_source()
│   ├── clean.R
│   ├── model.R
│   └── report.R
├── data/               # Input data
├── report.qmd          # Literate document
└── _targets/           # Auto-generated store (gitignore _targets/objects/)
    ├── meta/meta       # Metadata; commit this if you want teammates to share skip state
    └── objects/        # Target outputs

Essential commands

Running targets safely

Preview before running anything:

tar_manifest()          # list every target and its command
tar_outdated()          # what would rerun

Scope tar_make() to specific targets instead of rebuilding everything:

tar_make(names = c("clean_data", "model"))
tar_make(names = starts_with("plot_"))        # tidyselect helpers work
tar_make(names = "report", shortcut = TRUE)   # rebuild report only, skip upstream

shortcut = TRUE rebuilds only the named targets even if upstream is invalidated. Handy for rerunning a downstream report without recomputing expensive ancestors.

Scope invalidation and deletion the same way:

tar_invalidate(names = "model")                 # force rerun, keep stored value
tar_delete(names = c("model", "fit"))           # drop stored value
tar_prune()                                     # drop only stale targets no longer in pipeline

Never pass everything() to tar_invalidate() or tar_delete() reflexively. Use a name vector.

Protect expensive targets with a cue that only invalidates on demand:

tar_target(
  slow_model,
  fit_slow(data),
  cue = tar_cue(mode = "never")   # runs only when manually invalidated
)

Avoid tar_destroy() when a scoped command will do:

tar_destroy() prompts interactively by default. Do not pass ask = FALSE casually.

Error strategies

Memory options (targets >= 1.11)

Best practices

1. Name targets as nouns (clean_data), functions as verbs (clean_data()). The collision is fine because one is a value and the other is a callable.
2. Pass data as function arguments, never via globals. targets hashes function bodies, not the calling environment.
3. Wrap closures. purrr::safely(), Vectorize(), and Rcpp::cppFunction() hide code from static analysis; wrap them in named R functions so changes get tracked.
4. Batch tiny work. A hundred branches of 100 items beats 10,000 targets.
5. Keep the store small. Use butcher::butcher() or lean = TRUE (fixest) to slim model objects before returning.
6. Compile external docs last. Put Typst/LaTeX targets at the tail with cue = tar_cue(mode = "always"). Ordering is guaranteed and the skip logic rarely pays off for fast compiles.
7. Verify before running. tar_validate() + tar_outdated() catches most mistakes before you spend CPU time.

Anti-patterns

Example

library(targets)
library(tarchetypes)

tar_source()
tar_option_set(
  packages = "tidyverse",
  format = "qs",
  controller = crew::crew_controller_local(workers = 4)
)

list(
  tar_file_read(
    raw_data,
    "data/penguins.csv",
    read = readr::read_csv(!!.x, show_col_types = FALSE)
  ),
  tar_target(clean_data, clean_penguins(raw_data)),
  tar_target(species, unique(clean_data$species)),
  tar_target(
    species_model,
    fit_species_model(clean_data, species),
    pattern = map(species),
    iteration = "list"
  ),
  tar_target(
    coefs,
    purrr::map_dfr(species_model, broom::tidy, .id = "species")
  ),
  tar_quarto(report, "report.qmd")
)