In cjvanlissa/worcs: Workflow for Open Reproducible Code in Science

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
library(worcs)

Code in reproducible projects is often executed much more often than in non-reproducible projects. After each change, the entire analysis is typically executed to check if its results still reproduce. While such rigorous testing is integral to reproducibility see 'Using Endpoints to Check Reproducibility', executing unchanged code can be redundant. Moreover, if the analyses take a long time, this can take the steam out of your sails if you are in the flow, working on a project. Computing also has an environmental footprint, and it is worth considering the trade-off between re-running code sufficiently frequently to ensure its reproducibility, but not needlessly beyond that [@guptaChasingCarbonElusive2021].

The targets package addresses this challenge. It facilitates defining and executing an analysis pipeline, and tracks dependencies between blocks of code to ensure that code is only re-run if it has changed, or if its input has changed. Since version 0.1.15, worcs facilitates the use of targets in worcs projects. The targets package is perfectly complementary to worcs, and this Vignette describes the two canonical ways of combining the two. Since targets requires a specific way of working though, please make sure to read the targets manual before jumping in.

Defining a Pipeline

The canonical way of using targets in worcs is to select the "Use Targets" checkbox in the "Create a Project" dialog window. Subsequently, you would define the analysis pipeline in the _targets.R script file. Running worcs::reproduce(), or targets::tar_make(), will execute the steps in this script. The script often makes use of analysis functions defined in the R/ directory. Since the worcs workflow recommends using dynamic document generation, the pipeline in the _targets.R script will often end with rendering an Rmarkdown or Quarto document. When adding targets to a worcs project, this line is automatically added to the _targets.R script. Results from the analysis pipeline can be loaded into the environment in the Rmarkdown document using the targets::tar_load(result_name) or targets::tar_load_everything() functions.

Using targets Markdown

Alternatively, is is possible to run targets entirely from within an Rmarkdown file. To this end, either select the "target_markdown" output format when creating a new worcs project, or select any other output format and manually incorporate the targets pipeline, following the manual. A word of warning however: combining the interactive execution of code chunks while writing an Rmarkdown file with programmatic execution of a pipeline using tar_make() is likely to be more prone to bugs than only programmatically executing code.

cjvanlissa/worcs documentation built on Nov. 7, 2024, 1:20 p.m.