Sharing and Scaffolding RAP Projects

A Reproducible Analytical Pipeline (RAP) only fulfills its purpose when it can be shared and re-run by other people — in other contexts, with other data, without losing traceability. climasus4r offers four complementary strategies for this, each suited to a different collaborator profile and use case.

📄

.R Script

Complete file with code, metadata, and validations. Ideal for collaborators with advanced R skills (RAP 1).

📋

YAML Recipe

Compact format (<50 lines). Easy to read, send by email, and import with sus_rap_from_recipe().

🖥️

Shiny GUI

Visual interface with no code. Ideal for researchers without R experience or for demonstrations.

📁

Complete Project

Ready-made structure with renv + targets + Quarto. For new long-term reproducible analysis projects.

The table below summarizes when to use each approach:

Format	Target audience	Artifact size	Requires R on the receiving end
`.R` Script	Developer / advanced analyst	Medium (100–300 lines)	Yes
YAML Recipe	Any analyst with `climasus4r`	Compact (< 50 lines)	Yes
Shiny GUI	Researcher without R experience	Web interface	No (for use)
Complete project	New long-term project	Structured directory	Yes

**Prerequisite:** This tutorial assumes familiarity with the RAP concepts introduced in RAP 1 — Exporting and Running Pipelines and with the `climasus4r` `rap_object` structure. If you have not yet read that tutorial, we recommend starting there.

`sus_rap_recipe()` — Export as a Compact YAML

Motivation

Imagine an analyst in São Paulo has developed a complete respiratory-cause mortality pipeline and wants to share it with a colleague in Rio de Janeiro. Sending a 200-line .R script can be intimidating; sending a 40-line YAML file is far more approachable. sus_rap_recipe() does exactly this: it serializes the parameters, steps, and package versions into a human-readable, machine-reimportable format.

Basic usage

library(climasus4r)

# Start from an existing rap_object (created with sus_rap_export())
rap <- sus_rap_read("analise_mortalidade_sp.R")

# Export as a YAML recipe
sus_rap_recipe(
  rap               = rap,
  file_path         = "pipeline_mortalidade.yaml",
  include_data_hash = TRUE,
  lang              = "pt"
)
#> v Receita RAP exportada: pipeline_mortalidade.yaml

The generated file is compact and directly editable in any text editor:

rap_version: '1.0'
created: '2026-06-18 10:30:00'
climasus4r_version: '1.0.0'
pipeline_type: Pipeline SIM-DO
parameters:
  uf: SP
  years:
  - 2020
  - 2021
  - 2022
  system: SIM-DO
  time_unit: month
  lang: pt
steps:
- function_name: sus_data_import
  params: ~
- function_name: sus_data_clean_encoding
  params: ~
- function_name: sus_data_standardize
  params: ~
- function_name: sus_data_filter_cid
  params:
    cid_group: respiratory
- function_name: sus_data_aggregate
  params:
    by: month
metadata:
  r_version: R version 4.4.0 (2024-04-24)
  platform: unix
  package_version: 1.0.0
data_hash: a3f9c21b

Anatomy of the recipe

Field	Description
`rap_version`	Recipe schema version (compatibility control)
`created`	Generation timestamp (ISO 8601)
`climasus4r_version`	Package version at the time of export
`pipeline_type`	Inferred pipeline type (e.g., “Pipeline SIM-DO”)
`parameters`	Editable block with UF, years, system, and other parameters
`steps`	Ordered list of steps with function name and key parameters
`metadata`	R version, platform, and package version
`data_hash`	xxhash32 hash of the input parameters — ensures traceability

**Tip — `data_hash`:** The `data_hash` field is computed from the input parameters (`uf`, `years`, `system`). If two analysts generate the same hash from different recipes, this indicates they started from exactly the same input data — useful for audits and certified reproduction.

Full parameters

sus_rap_recipe(
  rap               = rap,        # rap_object (required)
  file_path         = NULL,       # NULL → timestamped name in the current directory
  include_data_hash = TRUE,       # include hash for traceability
  lang              = "pt",       # message language ("pt", "en", "es")
  overwrite         = FALSE       # overwrite existing file?
)

When file_path = NULL, the file is created in the current working directory with a name in the format rap_recipe_YYYYMMDD_HHMMSS.yaml.

`sus_rap_from_recipe()` — Import and Re-run

Basic import

The colleague in Rio de Janeiro receives the pipeline_mortalidade.yaml file and imports it with a single function call:

# Colleague in RJ imports the recipe
rap_rj <- sus_rap_from_recipe(
  recipe_path     = "pipeline_mortalidade.yaml",
  override_params = list(uf = "RJ", years = 2021:2023),
  lang            = "pt"
)
#> i Importando receita: Pipeline SIM-DO
#> v Receita carregada: 5 etapa(s).

print(rap_rj)
#> <rap_object>
#>  - Tipo     : Pipeline SIM-DO
#>  - Formato  : recipe
#>  - Etapas   : 5
#>  - UF       : RJ
#>  - Anos     : 2021–2023
#>  - Sistema  : SIM-DO

The override_params argument allows the original recipe to be adapted without editing the YAML file: here the UF was changed from SP to RJ and the period was extended. All other parameters — CID filters, temporal aggregation, language — are inherited from the original recipe.

Import and run in a single call

For automation workflows, execute = TRUE chains the import and pipeline execution:

resultado <- sus_rap_from_recipe(
  recipe_path     = "pipeline_mortalidade.yaml",
  override_params = list(uf = "RJ"),
  execute         = TRUE,
  lang            = "pt"
)
#> i Importando receita: Pipeline SIM-DO
#> v Receita carregada: 5 etapa(s).
#> i Iniciando execucao do pipeline...
#> v Pipeline concluido em 12.3s | 2847 linhas

When execute = TRUE, the function returns the pipeline result (a climasus_df) instead of the rap_object.

SP → RJ collaborative workflow

rap_object (SP) → sus_rap_recipe() → pipeline.yaml → send by email → sus_rap_from_recipe(uf="RJ") → result (RJ)

Full parameters

sus_rap_from_recipe(
  recipe_path     = "pipeline_mortalidade.yaml",  # path to the .yaml file (required)
  override_params = list(),     # parameters to override (named list)
  execute         = FALSE,      # TRUE = execute immediately after importing
  lang            = "pt",       # message language
  ...                           # extra arguments passed to sus_rap_run() when execute=TRUE
)

**Version check:** If the recipe was created with an earlier version of `climasus4r`, the function issues a warning but proceeds. For critical production environments, check the `climasus4r_version` field in the recipe before executing.

`sus_rap_gui()` — Visual Shiny Interface

Who is the GUI for?

The climasus4r graphical interface targets three profiles:

Researchers without R experience who need to configure and run a pipeline
Demonstrations and workshops where the focus is on results, not code
Rapid exploration of parameter combinations before formalizing the pipeline

Launching the GUI

# Launch with a pre-loaded rap_object
sus_rap_gui(rap = rap, launch.browser = TRUE)

The interface opens in the system’s default browser. If you prefer to view it in the RStudio Viewer, use launch.browser = FALSE.

**Requires the shiny package:** `sus_rap_gui()` requires the `shiny` package (listed in Suggests). Install it with `install.packages("shiny")` before use.

The three-panel interface

The GUI is organized into three side-by-side panels that work together:

Left panel — Parameters:

Text field for UF(s) separated by commas (e.g., SP, RJ, MG)
Year-range slider (2000–2024)
Dropdown for the DATASUS system (SIM-DO, SIH, SINAN, SIA, CNES, SINASC)
Dropdown for the temporal aggregation unit (day, week, month, quarter, year)
Language selector (pt, en, es)
Output directory field

Center panel — Pipeline:

Visual cards, one per RAP step, listing the function name and the configured arguments
Automatically updated as parameters are changed

Right panel — Console:

Real-time log with timestamps ([HH:MM:SS] message)
Preview of the R code that will be executed

Action buttons

Button	Action
Code Preview	Displays the equivalent R code in the right panel
Run Pipeline	Calls `sus_rap_run()` in `dry_run = FALSE` mode
Export RAP	Saves the pipeline as an `.R` script via `sus_rap_export()`
Save YAML Recipe	Saves the pipeline as a `.yaml` recipe via `sus_rap_recipe()`

Starting from scratch

To create a pipeline interactively with no starting point, pass rap = NULL:

# Launch without a pre-loaded RAP
sus_rap_gui(rap = NULL)

The GUI initializes with a default template (SIM-DO, SP, 2019–2022) that can be freely edited.

**Workflow tip:** Use the GUI to quickly explore parameter combinations, click "Code Preview" to see the generated R code, copy it into your script, and then refine it with `sus_rap_export()` to produce the final artifact. This combines the best of both worlds: the speed of the GUI and the traceability of a script.

`sus_rap_addin_export()` — RStudio Addin

What are RStudio addins?

Addins are RStudio IDE extensions that appear in the Addins menu (top toolbar) and can be triggered with a keyboard shortcut or via Tools → Addins. They run R functions in the context of the active session and can interact with the code editor, the environment, and the console.

climasus4r registers two addins in the inst/rstudio/addins.dcf file:

Name: Exportar Pipeline como RAP
Description: Exporta o pipeline selecionado no editor como script reprodutivel.
Binding: sus_rap_addin_export
Interactive: false

Name: Abrir GUI de RAP
Description: Abre interface visual para editar e executar Reproducible Analytical Pipelines.
Binding: sus_rap_gui
Interactive: true

After installing climasus4r, the addins become automatically available in RStudio’s Addins menu — no additional configuration is needed.

How to use `sus_rap_addin_export()`

The workflow is intuitive:

Open an .R script in RStudio containing a climasus4r pipeline
Select the pipeline code with the cursor (from sus_data_import() to the last step)
Go to Addins → Exportar Pipeline como RAP
The addin captures the selected text via rstudioapi::getSourceEditorContext(), parses the expression, and calls sus_rap_export() to create an .R file in the same directory as the active script

The exported file is named in the format rap_YYYYMMDD_HHMMSS.R and contains the complete pipeline with embedded metadata, an editable parameter block, and validations.

Example interaction

# Code selected in the editor:
sus_data_import(uf = "SP", years = 2020:2022, system = "SIM-DO") |>
  sus_data_clean_encoding() |>
  sus_data_standardize() |>
  sus_data_filter_cid(cid_group = "respiratory") |>
  sus_data_aggregate(by = "month")

# After triggering the addin → creates: ./rap_20260618_103045.R
#> [Dialogo RStudio] Pipeline exportado com sucesso:
#>   /home/usuario/analises/rap_20260618_103045.R

**Tip:** The addin only works inside the RStudio IDE. For command-line use or VS Code, use `sus_rap_export()` directly (see RAP Tutorial 1).

**Partial selection:** The addin expects the selected code to be a valid R expression (using a pipe, `|>` or `%>%`). If the selection cannot be parsed, a dialog box will report the error. Select only the pipeline lines, without comments in between.

`sus_rap_template()` — Complete Project Scaffolding

The problem it solves

Setting up a reproducible analysis project from scratch involves a series of repetitive decisions: creating the directory structure, configuring renv to capture dependencies, writing _targets.R with the pipeline logic, creating the Quarto report, adding the correct .gitignore… sus_rap_template() automates all of this in a single call.

Creating a SINAN project for dengue analysis in Amazonas

sus_rap_template(
  path                   = "~/projetos",
  name                   = "dengue_am",
  system                 = "SINAN",
  include_renv           = TRUE,
  include_targets        = TRUE,
  include_quarto         = TRUE,
  include_github_actions = FALSE,
  lang                   = "pt"
)
#> -- Criando projeto RAP: dengue_am --
#> i Estrutura de diretorios criada.
#> i _targets.R e run.R criados.
#> i analysis.qmd criado.
#> i renv inicializado.
#> v Projeto 'dengue_am' pronto em ~/projetos/dengue_am

Generated structure

dengue_am/
|-- _targets.R          # pipeline targets (generated automatically)
|-- run.R               # runner: source + tar_make()
|-- analysis.qmd        # parameterized Quarto report
|-- R/
|   `-- functions.R     # project helper functions
|-- data/               # raw data (git-ignored)
|-- output/             # results (git-ignored)
|-- renv/               # dependency snapshot
|-- renv.lock
|-- .gitignore
`-- README.md

Each file plays a clear role in the RAP architecture:

File	Purpose
`_targets.R`	Defines the pipeline’s dependency graph
`run.R`	Single execution entry point: `targets::tar_make()`
`analysis.qmd`	Parameterized report that loads the `_targets` results
`R/functions.R`	Project-specific helper functions
`data/`	Raw data (never committed to git)
`output/`	Computed results (never committed to git)
`renv.lock`	Exact snapshot of package versions

Excerpt from the generated `_targets.R`

# _targets.R  - Generated by climasus4r::sus_rap_template()
# Project: dengue_am

library(targets)
library(climasus4r)

list(
  tar_target(params, list(
    uf         = "AM",   # edit: UF code(s)
    years      = 2019:2021,
    system     = "SINAN",
    time_unit  = "month",
    lang       = "pt"
  )),

  tar_target(raw_data,
    sus_data_import(
      uf       = params$uf,
      years    = params$years,
      system   = params$system,
      parallel = TRUE,
      lang     = params$lang
    )
  ),

  tar_target(clean_data,
    raw_data |>
      sus_data_clean_encoding(lang = params$lang) |>
      sus_data_standardize(lang = params$lang)
  ),

  tar_target(agg_data,
    clean_data |>
      sus_data_aggregate(by = params$time_unit, lang = params$lang)
  ),

  tar_target(qc_report,
    sus_data_quality_report(clean_data, lang = params$lang)
  ),

  # ... additional steps
  NULL
)

**Tip:** After creating the project, edit the `uf` field and the `years` range in the `tar_target(params, ...)` block at the top of `_targets.R`. Then run `targets::tar_make()` from the project directory to run the complete pipeline.

Continuous integration with GitHub Actions

For projects that need automated execution — for example, a monthly update of an epidemiological dashboard — use include_github_actions = TRUE:

sus_rap_template(
  path                   = "~/projetos",
  name                   = "dengue_am_ci",
  system                 = "SINAN",
  include_github_actions = TRUE
)

The generated .github/workflows/rap.yml file has the following structure:

name: Reproducible Analysis Pipeline

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:

jobs:
  pipeline:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: r-lib/actions/setup-r@v2
        with:
          r-version: '4.4'

      - uses: r-lib/actions/setup-renv@v2

      - name: Run targets pipeline
        run: Rscript run.R

      - name: Upload results
        uses: actions/upload-artifact@v4
        with:
          name: pipeline-results
          path: output/

The workflow is triggered on every push to main and can also be triggered manually via workflow_dispatch. The results are made available as a build artifact in GitHub Actions.

**Sensitive data:** The `data/` directory is included in the automatically generated `.gitignore`. Never commit raw DATASUS data to public repositories. For CI/CD pipelines, consider storing data in an S3 bucket or equivalent and retrieving it during the CI step.

Full parameters

sus_rap_template(
  path                   = "~/projetos",  # parent directory (required)
  name                   = "meu_projeto", # project/directory name (required)
  system                 = "SIM-DO",      # DATASUS system for the template
  include_renv           = TRUE,          # initialize renv?
  include_targets        = TRUE,          # create _targets.R and run.R?
  include_quarto         = TRUE,          # create analysis.qmd?
  include_github_actions = FALSE,         # create .github/workflows/rap.yml?
  lang                   = "pt"           # language of the generated comments
)

Complete Collaborative Workflow

The five functions in this tutorial are designed to work together. The diagram below illustrates a complete flow: from creating the pipeline to reproduction by another analyst.

Analyst A: pipeline → sus_rap_recipe() → recipe.yaml → Analyst B → sus_rap_from_recipe() → adapted result

Summary table of functions

Function	Input	Output	Main use case
`sus_rap_recipe()`	`rap_object`	`.yaml` file	Share a compact pipeline with colleagues
`sus_rap_from_recipe()`	`.yaml` file	`rap_object`	Import and optionally re-run
`sus_rap_gui()`	`rap_object` or NULL	Shiny app	Visual interface for non-programmers
`sus_rap_addin_export()`	RStudio editor selection	`.R` file	Quick workflow within the IDE
`sus_rap_template()`	configuration parameters	project directory	Scaffolding a new reproducible project

Choosing the right format:

YAML when the recipient is an analyst who needs to adapt parameters
GUI when the recipient does not program in R or for live demonstrations
Template when starting a new project and you want the complete structure from the outset
.R Script (via sus_rap_export()) when the recipient is a developer who will modify the code

References

Marwick B, Boettiger C, Mullen L (2018). Packaging data analytical work reproducibly using R (and friends). The American Statistician, 72(1), 80–88.
UK Government Data Science (2022). Reproducible Analytical Pipelines (RAP) Strategy. Cabinet Office. Available at: https://www.gov.uk/government/publications/better-broader-safer-using-health-data-for-research-and-analysis.
Wilson G et al. (2017). Good enough practices in scientific computing. PLOS Computational Biology, 13(6), e1005510.

Navigation: Previous: RAP 2 - Pipelines with targets | All tutorials

climasus4r · Integrated health-climate-environment analysis in Brazil

Found a problem or have suggestions for this tutorial?

🐛 Report on GitHub

YAML recipes, Shiny GUI, RStudio addin, and scaffolding with `sus_rap_recipe()`, `sus_rap_gui()` and `sus_rap_template()`

Dr. Max Anjos

17 October, 2026

.R Script

YAML Recipe

Shiny GUI

Complete Project

`sus_rap_recipe()` — Export as a Compact YAML

Motivation

Basic usage

Anatomy of the recipe

Full parameters

`sus_rap_from_recipe()` — Import and Re-run

Basic import

Import and run in a single call

SP → RJ collaborative workflow

Full parameters

`sus_rap_gui()` — Visual Shiny Interface

Who is the GUI for?

Launching the GUI

The three-panel interface

Action buttons

Starting from scratch

`sus_rap_addin_export()` — RStudio Addin

What are RStudio addins?

How to use `sus_rap_addin_export()`

Example interaction

`sus_rap_template()` — Complete Project Scaffolding

The problem it solves

Creating a SINAN project for dengue analysis in Amazonas

Generated structure

Excerpt from the generated `_targets.R`

Continuous integration with GitHub Actions

Full parameters

Complete Collaborative Workflow

Summary table of functions

References

Sharing and Scaffolding RAP Projects

YAML recipes, Shiny GUI, RStudio addin, and scaffolding with sus_rap_recipe(), sus_rap_gui() and sus_rap_template()

Dr. Max Anjos

17 October, 2026

Introduction — Sharing Formats

.R Script

YAML Recipe

Shiny GUI

Complete Project

sus_rap_recipe() — Export as a Compact YAML

Motivation

Basic usage

Anatomy of the recipe

Full parameters

sus_rap_from_recipe() — Import and Re-run

Basic import

Import and run in a single call

SP → RJ collaborative workflow

Full parameters

sus_rap_gui() — Visual Shiny Interface

Who is the GUI for?

Launching the GUI

The three-panel interface

Action buttons

Starting from scratch

sus_rap_addin_export() — RStudio Addin

What are RStudio addins?

How to use sus_rap_addin_export()

Example interaction

sus_rap_template() — Complete Project Scaffolding

The problem it solves

Creating a SINAN project for dengue analysis in Amazonas

Generated structure

Excerpt from the generated _targets.R

Continuous integration with GitHub Actions

Full parameters

Complete Collaborative Workflow

Summary table of functions

References

YAML recipes, Shiny GUI, RStudio addin, and scaffolding with `sus_rap_recipe()`, `sus_rap_gui()` and `sus_rap_template()`

`sus_rap_recipe()` — Export as a Compact YAML

`sus_rap_from_recipe()` — Import and Re-run

`sus_rap_gui()` — Visual Shiny Interface

`sus_rap_addin_export()` — RStudio Addin

How to use `sus_rap_addin_export()`

`sus_rap_template()` — Complete Project Scaffolding

Excerpt from the generated `_targets.R`