The tarchetypes R package is a collection of target and pipeline archetypes for the targets package. These archetypes express complicated pipelines with concise syntax, which enhances readability and thus reproducibility. Archetypes are possible because of the flexible metaprogramming capabilities of targets. In targets, one can define a target as an object outside the central pipeline, and the tar_target_raw() function completely avoids non-standard evaluation. That means anyone can write their own niche interfaces for specialized projects. tarchetypes aims to include the most common and versatile archetypes and usage patterns.

Target archetype example

Consider the following R Markdown report.

---
title: report
output: html_document
---

```{r}
library(targets)
tar_read(dataset)
```

We want to define a target to render the report. And because the report calls tar_read(dataset), this target needs to depend on dataset. Without tarchetypes, it is cumbersome to set up the pipeline correctly.

# _targets.R
library(targets)
tar_pipeline(
  tar_target(dataset, data.frame(x = letters)),
  tar_target(
    report, {
      # Explicitly mention the symbol `dataset`.
      list(data)
      # Return relative paths to keep the project portable.
      fs::path_rel(
        # Need to return/track all input/output files.
        c( 
          rmarkdown::render(
            input = "report.Rmd",
            # Always run from the project root
            # so the report can find _targets/.
            knit_root_dir = getwd(),
            quiet = TRUE
          ),
          "report.Rmd"
        )
      )
    },
    # Track the input and output files.
    format = "file",
    # Avoid building small reports on HPC.
    deployment = "main"
  )
)

With tarchetypes, we can simplify the pipeline with the tar_render() archetype.

# _targets.R
library(targets)
library(tarchetypes)
tar_pipeline(
  tar_target(dataset, data.frame(x = letters)),
  tar_render(report, "report.Rmd")
)

Above, tar_render() scans code chunks for mentions of targets in tar_load() and tar_read(), and it enforces the dependency relationships it finds. In our case, it reads report.Rmd and then forces report to depend on dataset. That way, tar_make() always processes dataset before report, and it automatically reruns report.Rmd whenever dataset changes.

Pipeline archetype example

tar_plan() is a version of tar_pipeline() that looks and feels like drake_plan(). For simple targets with no configuration, you can write target = command instead of tar_target(target, command). Ordinarily, pipelines in _targets.R are written like this:

tar_pipeline(
  tar_target(
    raw_data_file,
    "data/raw_data.csv",
    format = "file"
  ),
  tar_target(
    raw_data,
    read_csv(raw_data_file, col_types = cols())
  ),
  tar_target(
    data,
    raw_data %>%
      mutate(Ozone = replace_na(Ozone, mean(Ozone, na.rm = TRUE)))
  ),
  tar_target(hist, create_plot(data)),
  tar_target(fit, biglm(Ozone ~ Wind + Temp, data)),
  tar_render(report, "report.Rmd")
)

With tar_plan(), the simplest targets become super easy to write.

tar_plan(
  tar_file(raw_data_file, "data/raw_data.csv", format = "file"),
  # Simple drake-like syntax:
  raw_data = read_csv(raw_data_file, col_types = cols()),
  data =raw_data %>%
    mutate(Ozone = replace_na(Ozone, mean(Ozone, na.rm = TRUE))),
  hist = create_plot(data),
  fit = biglm(Ozone ~ Wind + Temp, data),
  # Needs tar_render() because it is a target archetype:
  tar_render(report, "report.Rmd")
)

Installation

Install the GitHub development version to access the latest features and patches.

library(remotes)
install_github("wlandau/tarchetypes")

Documentation

For specific documentation on tarchetypes, including the help files of all user-side functions, please visit the reference website. For documentation on targets in general, please visit the targets reference website. Many of the linked resources use tarchetypes functions such as tar_render().

Participation

Development is a community effort, and we welcome discussion and contribution. By participating in this project, you agree to abide by the code of conduct and the contributing guide.

Citation

citation("tarchetypes")
#> Warning in citation("tarchetypes"): no date field in DESCRIPTION file of package
#> 'tarchetypes'
#> Warning in citation("tarchetypes"): could not determine year for 'tarchetypes'
#> from package DESCRIPTION file
#> 
#> To cite package 'tarchetypes' in publications use:
#> 
#>   William Michael Landau (NA). tarchetypes: Archetypes for Targets.
#>   https://wlandau.github.io/tarchetypes/,
#>   https://github.com/wlandau/tarchetypes.
#> 
#> A BibTeX entry for LaTeX users is
#> 
#>   @Manual{,
#>     title = {tarchetypes: Archetypes for Targets},
#>     author = {William Michael Landau},
#>     note = {https://wlandau.github.io/tarchetypes/, https://github.com/wlandau/tarchetypes},
#>   }