Target descriptions

[wlandau]

Prework

• [x] I understand and agree to the code of conduct and the contributing guidelines.
• [x] I have already submitted a discussion topic or issue to discuss my idea with the maintainer.

Related GitHub issues and pull requests

• Ref: #1136, #1196, #1230, #1235

Summary

tar_target() gains a new description argument for free-form text to describe what the target is about.

# _targets.R
library(targets)
list(
  tar_target(
    name = data,
    command = airquality,
    description = "airquality dataset from base R"
  ),
  tar_target(
    name = model1,
    command = broom::tidy(lm(Ozone ~ Temp, data = data)),
    description = "model of ozone against temperature (degrees F)"
  ),
  tar_target(
    name = model2,
    command = broom::tidy(lm(Ozone ~ Wind, data = data)),
    description = "model of ozone against wind speed (mph)"
  )
)

The descriptions show up in tar_manifest(), tar_network(), tar_glimpse(), tar_visnetwork(), and tar_mermaid().

library(targets)
tar_mermaid()

graph LR
  style Legend fill:#FFFFFF00,stroke:#000000;
  style Graph fill:#FFFFFF00,stroke:#000000;
  subgraph Legend
    direction LR
    x0a52b03877696646([""Outdated""]):::outdated --- xbf4603d6c2c2ad6b([""Stem""]):::none
  end
  subgraph Graph
    direction LR
    xb7119b48552d1da3(["data<br>airquality dataset from base R"]):::outdated --> xd2415809dfccb1c9(["model1<br>model of ozone against temperature (degrees F)"]):::outdated
    xb7119b48552d1da3(["data<br>airquality dataset from base R"]):::outdated --> x5e90f77e4394a7c0(["model2<br>model of ozone against wind speed (mph)"]):::outdated
  end
  classDef outdated stroke:#000000,color:#000000,fill:#78B7C5;
  classDef none stroke:#000000,color:#000000,fill:#94a4ac;
  linkStyle 0 stroke-width:0px;

tar_described_as() is a wrapper around tidyselect::any_of() to allow grouping of different targets based on the description rather than the name.

tar_manifest(names = tar_described_as(starts_with("model"))) # Does not show the dataset.
#> # A tibble: 2 × 3
#>   name   command                                    description                               
#>   <chr>  <chr>                                      <chr>                                     
#> 1 model1 broom::tidy(lm(Ozone ~ Temp, data = data)) model of ozone against temperature (degre…
#> 2 model2 broom::tidy(lm(Ozone ~ Wind, data = data)) model of ozone against wind speed (mph) 

tar_make(names = tar_described_as(contains("dataset"))) # Does not run the models.
#> ▶ dispatched target data
#> ● completed target data [0.001 seconds]
#> ▶ ended pipeline [0.055 seconds]

FYI @tjmahr, @noamross, @mattmoo