Compartir y Scaffolding de Proyectos RAP

Introducción — Formatos de Compartición

Un Reproducible Analytical Pipeline (RAP) solo cumple su propósito cuando puede ser compartido y reejecutado por otras personas — en otros contextos, con otros datos, sin pérdida de trazabilidad. climasus4r ofrece cuatro estrategias complementarias para esto, cada una adecuada a un perfil de colaborador y de caso de uso.

📄

Script .R

Archivo completo con codigo, metadatos y validaciones. Ideal para colaboradores con R avanzado (RAP 1).

📋

Receta YAML

Formato compacto (<50 lineas). Facil de leer, enviar por correo e importar con sus_rap_from_recipe().

🖥️

GUI Shiny

Interfaz visual sin codigo. Ideal para investigadores sin experiencia en R o para demostraciones.

📁

Proyecto Completo

Estructura lista con renv + targets + Quarto. Para nuevos proyectos de analisis reproducible de larga duracion.

La siguiente tabla resume cuándo usar cada enfoque:

Formato	Audiencia objetivo	Tamaño del artefacto	Requiere R en el receptor
Script `.R`	Desarrollador / analista avanzado	Mediano (100–300 líneas)	Sí
Receta YAML	Cualquier analista con `climasus4r`	Compacto (< 50 líneas)	Sí
GUI Shiny	Investigador sin experiencia en R	Interfaz web	No (para uso)
Proyecto completo	Nuevo proyecto de larga duración	Directorio estructurado	Sí

**Prerrequisito:** Este tutorial asume familiaridad con los conceptos de RAP presentados en RAP 1 — Exportar y Ejecutar Pipelines y con la estructura rap_object de climasus4r. Si aún no ha leído aquel tutorial, recomendamos comenzar por él.

`sus_rap_recipe()` — Exportar como YAML Compacto

Motivación

Imagine que un analista en São Paulo desarrolló un pipeline completo de mortalidad por causas respiratorias y quiere compartirlo con una colega en Río de Janeiro. Enviar un script .R de 200 líneas puede resultar intimidante; enviar un archivo YAML de 40 líneas es mucho más accesible. sus_rap_recipe() hace exactamente eso: serializa los parámetros, las etapas y las versiones del paquete en un formato legible por humanos y reimportable por máquinas.

Uso básico

library(climasus4r)

# Partir de un rap_object existente (creado con sus_rap_export())
rap <- sus_rap_read("analise_mortalidade_sp.R")

# Exportar como receta YAML
sus_rap_recipe(
  rap               = rap,
  file_path         = "pipeline_mortalidade.yaml",
  include_data_hash = TRUE,
  lang              = "pt"
)
#> v Receita RAP exportada: pipeline_mortalidade.yaml

El archivo generado es compacto y editable directamente en cualquier editor de texto:

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

Anatomía de la receta

Campo	Descripción
`rap_version`	Versión del esquema de la receta (control de compatibilidad)
`created`	Timestamp de generación (ISO 8601)
`climasus4r_version`	Versión del paquete en el momento de la exportación
`pipeline_type`	Tipo inferido del pipeline (ej.: “Pipeline SIM-DO”)
`parameters`	Bloque editable con UF, años, sistema y otros parámetros
`steps`	Lista ordenada de etapas con nombre de la función y parámetros clave
`metadata`	Versión de R, plataforma y versión del paquete
`data_hash`	Hash xxhash32 de los parámetros de entrada — garantiza trazabilidad

**Consejo — `data_hash`:** El campo `data_hash` se calcula a partir de los parámetros de entrada (`uf`, `years`, `system`). Si dos analistas generan el mismo hash a partir de recetas diferentes, esto indica que partieron exactamente de los mismos datos de entrada — útil para auditorías y reproducción certificada.

Parámetros completos

sus_rap_recipe(
  rap               = rap,        # rap_object (obligatorio)
  file_path         = NULL,       # NULL → nombre con timestamp en el directorio actual
  include_data_hash = TRUE,       # incluir hash para trazabilidad
  lang              = "pt",       # idioma de los mensajes ("pt", "en", "es")
  overwrite         = FALSE       # ¿sobrescribir archivo existente?
)

Cuando file_path = NULL, el archivo se crea en el directorio de trabajo actual con nombre en el formato rap_recipe_YYYYMMDD_HHMMSS.yaml.

`sus_rap_from_recipe()` — Importar y Reejecutar

Importación básica

La colega en Río de Janeiro recibe el archivo pipeline_mortalidade.yaml y lo importa con una única función:

# Colega en RJ importa la receta
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

El parámetro override_params permite adaptar la receta original sin editar el archivo YAML: aquí la UF fue cambiada de SP a RJ y el período fue extendido. Todos los demás parámetros — filtros CID, agregación temporal, idioma — se heredan de la receta original.

Importar y ejecutar en una única llamada

Para flujos de automatización, execute = TRUE encadena la importación y la ejecución del pipeline:

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

Cuando execute = TRUE, la función retorna el resultado del pipeline (un climasus_df) en lugar del rap_object.

Flujo colaborativo SP → RJ

rap_object (SP) → sus_rap_recipe() → pipeline.yaml → enviar por e-mail → sus_rap_from_recipe(uf="RJ") → resultado (RJ)

Parámetros completos

sus_rap_from_recipe(
  recipe_path     = "pipeline_mortalidade.yaml",  # ruta al .yaml (obligatorio)
  override_params = list(),     # parámetros a sobrescribir (lista nombrada)
  execute         = FALSE,      # TRUE = ejecutar inmediatamente tras importar
  lang            = "pt",       # idioma de los mensajes
  ...                           # argumentos extra para sus_rap_run() cuando execute=TRUE
)

**Verificación de versión:** Si la receta fue creada con una versión anterior de `climasus4r`, la función emite una advertencia pero continúa. Para entornos críticos de producción, verifique el campo `climasus4r_version` en la receta antes de ejecutar.

`sus_rap_gui()` — Interfaz Visual Shiny

¿Para quién es la GUI?

La interfaz gráfica de climasus4r está orientada a tres perfiles:

Investigadores sin experiencia en R que necesitan configurar y ejecutar un pipeline
Demostraciones y talleres donde el foco está en los resultados, no en el código
Exploración rápida de combinaciones de parámetros antes de formalizar el pipeline

Lanzar la GUI

# Lanzar con un rap_object precargado
sus_rap_gui(rap = rap, launch.browser = TRUE)

La interfaz se abre en el navegador predeterminado del sistema. Si prefiere visualizarla en el Viewer de RStudio, use launch.browser = FALSE.

**Paquete shiny necesario:** `sus_rap_gui()` requiere el paquete `shiny` (listado en Suggests). Instálelo con `install.packages("shiny")` antes de usarlo.

La interfaz en tres paneles

La GUI está organizada en tres paneles laterales que trabajan en conjunto:

Panel izquierdo — Parámetros:

Campo de texto para UF(s) separadas por coma (ej.: SP, RJ, MG)
Slider de intervalo de años (2000–2024)
Dropdown para sistema DATASUS (SIM-DO, SIH, SINAN, SIA, CNES, SINASC)
Dropdown para unidad de agregación temporal (day, week, month, quarter, year)
Selector de idioma (pt, en, es)
Campo para directorio de salida

Panel central — Pipeline:

Tarjetas visuales, una por etapa del RAP, listando el nombre de la función y los argumentos configurados
Actualizado automáticamente conforme se modifican los parámetros

Panel derecho — Consola:

Registro en tiempo real con timestamps ([HH:MM:SS] mensagem)
Vista previa del código R que será ejecutado

Botones de acción

Botón	Acción
Prévia do Código	Muestra el código R equivalente en el panel derecho
Executar Pipeline	Llama a `sus_rap_run()` en modo `dry_run = FALSE`
Exportar RAP	Guarda el pipeline como script `.R` vía `sus_rap_export()`
Salvar Receita YAML	Guarda el pipeline como receta `.yaml` vía `sus_rap_recipe()`

Iniciar desde cero

Para crear un pipeline interactivamente sin punto de partida, pase rap = NULL:

# Lanzar sin RAP precargado
sus_rap_gui(rap = NULL)

La GUI se inicializa con una plantilla predeterminada (SIM-DO, SP, 2019–2022) que puede editarse libremente.

**Consejo de flujo de trabajo:** Use la GUI para explorar combinaciones de parámetros rápidamente, haga clic en "Prévia do Código" para ver el R generado, cópielo a su script, y luego refine con `sus_rap_export()` para el artefacto final. Esto combina lo mejor de ambos mundos: la velocidad de la GUI y la trazabilidad del script.

`sus_rap_addin_export()` — Addin de RStudio

¿Qué son los addins de RStudio?

Los addins son extensiones del IDE de RStudio que aparecen en el menú Addins (barra de herramientas superior) y pueden accionarse con un atajo de teclado o vía Tools → Addins. Ejecutan funciones R en el contexto de la sesión activa, pudiendo interactuar con el editor de código, el entorno y la consola.

climasus4r registra dos addins en el archivo inst/rstudio/addins.dcf:

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

Después de instalar climasus4r, los addins quedan automáticamente disponibles en el menú Addins de RStudio — no se requiere configuración adicional.

Cómo usar `sus_rap_addin_export()`

El flujo de trabajo es intuitivo:

Abra un script .R en RStudio con un pipeline climasus4r
Seleccione el código del pipeline con el cursor (desde sus_data_import() hasta el último paso)
Acceda a Addins → Exportar Pipeline como RAP
El addin captura el texto seleccionado vía rstudioapi::getSourceEditorContext(), hace el parseo de la expresión, y llama a sus_rap_export() para crear un archivo .R en el mismo directorio del script activo

El archivo exportado tendrá nombre en el formato rap_YYYYMMDD_HHMMSS.R y contendrá el pipeline completo con metadatos incorporados, bloque de parámetros editable y validaciones.

Ejemplo de interacción

# Código seleccionado en el 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")

# Después de accionar el addin → crea: ./rap_20260618_103045.R
#> [Dialogo RStudio] Pipeline exportado com sucesso:
#>   /home/usuario/analises/rap_20260618_103045.R

**Consejo:** El addin funciona solo dentro del IDE de RStudio. Para uso en línea de comandos o VS Code, use `sus_rap_export()` directamente (ver RAP Tutorial 1).

**Selección parcial:** El addin espera que el código seleccionado sea una expresión R válida (con pipe `|>` o `%>%`). Si la selección no es parseable, un cuadro de diálogo informará el error. Seleccione solo las líneas del pipeline, sin comentarios en medio.

`sus_rap_template()` — Scaffolding de Proyecto Completo

El problema que resuelve

Configurar un proyecto de análisis reproducible desde cero implica una serie de decisiones repetitivas: crear la estructura de directorios, configurar renv para capturar dependencias, escribir el _targets.R con la lógica del pipeline, crear el informe Quarto, agregar el .gitignore correcto… sus_rap_template() automatiza todo esto en una única llamada.

Creando un proyecto SINAN para análisis de dengue en 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

Estructura generada

dengue_am/
|-- _targets.R          # pipeline targets (gerado automaticamente)
|-- run.R               # executor: source + tar_make()
|-- analysis.qmd        # relatorio Quarto parametrizado
|-- R/
|   `-- functions.R     # funcoes auxiliares do projeto
|-- data/               # dados brutos (git-ignorado)
|-- output/             # resultados (git-ignorado)
|-- renv/               # snapshot de dependencias
|-- renv.lock
|-- .gitignore
`-- README.md

Cada archivo cumple un rol claro en la arquitectura RAP:

Archivo	Propósito
`_targets.R`	Define el grafo de dependencias del pipeline
`run.R`	Entrada única de ejecución: `targets::tar_make()`
`analysis.qmd`	Informe parametrizado que carga los resultados de `_targets`
`R/functions.R`	Funciones auxiliares específicas del proyecto
`data/`	Datos brutos (nunca commiteados en git)
`output/`	Resultados computados (nunca commiteados en git)
`renv.lock`	Snapshot exacto de las versiones de los paquetes

Fragmento del `_targets.R` generado

# _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)
  ),

  # ... etapas adicionais
  NULL
)

**Consejo:** Después de crear el proyecto, edite el campo `uf` y el intervalo `years` en el bloque `tar_target(params, ...)` en la parte superior del `_targets.R`. A continuación, ejecute `targets::tar_make()` desde el directorio del proyecto para correr el pipeline completo.

Integración continua con GitHub Actions

Para proyectos que necesitan ejecución automatizada — por ejemplo, actualización mensual de un panel epidemiológico — use include_github_actions = TRUE:

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

El archivo .github/workflows/rap.yml generado tiene la siguiente estructura:

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/

El workflow se activa en cada push a main y también puede dispararse manualmente vía workflow_dispatch. Los resultados quedan disponibles como artefacto de build en GitHub Actions.

**Datos sensibles:** El directorio `data/` está en el `.gitignore` generado automáticamente. Nunca commitee datos brutos del DATASUS en repositorios públicos. Para pipelines con CI/CD, considere almacenar los datos en un bucket S3 o equivalente y recuperarlos en la etapa de CI.

Parámetros completos

sus_rap_template(
  path                   = "~/projetos",  # directorio padre (obligatorio)
  name                   = "meu_projeto", # nombre del proyecto/directorio (obligatorio)
  system                 = "SIM-DO",      # sistema DATASUS para la plantilla
  include_renv           = TRUE,          # ¿inicializar renv?
  include_targets        = TRUE,          # ¿crear _targets.R y run.R?
  include_quarto         = TRUE,          # ¿crear analysis.qmd?
  include_github_actions = FALSE,         # ¿crear .github/workflows/rap.yml?
  lang                   = "pt"           # idioma de los comentarios generados
)

Flujo Colaborativo Completo

Las cinco funciones de este tutorial están diseñadas para trabajar en conjunto. El siguiente diagrama ilustra un flujo completo: desde la creación del pipeline hasta la reproducción por otro analista.

Analista A: pipeline → sus_rap_recipe() → recipe.yaml → Analista B → sus_rap_from_recipe() → resultado adaptado

Tabla resumen de las funciones

Función	Entrada	Salida	Caso de uso principal
`sus_rap_recipe()`	`rap_object`	archivo `.yaml`	Compartir pipeline compacto con colegas
`sus_rap_from_recipe()`	archivo `.yaml`	`rap_object`	Importar y opcionalmente reejecutar
`sus_rap_gui()`	`rap_object` o NULL	app Shiny	Interfaz visual para no programadores
`sus_rap_addin_export()`	selección en el editor RStudio	archivo `.R`	Flujo rápido dentro del IDE
`sus_rap_template()`	parámetros de configuración	directorio de proyecto	Scaffolding de nuevo proyecto reproducible

Eligiendo el formato correcto:

YAML cuando el receptor es analista y necesita adaptar parámetros
GUI cuando el receptor no programa en R o para demostraciones en vivo
Template cuando está comenzando un proyecto nuevo y quiere la estructura completa desde el inicio
Script .R (vía sus_rap_export()) cuando el receptor es desarrollador y va a modificar el código

Referencias

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. Disponible en: 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.

Navegación: Anterior: RAP 2 - Pipelines con targets | Todos los tutoriales

climasus4r · Análisis integrado salud-clima-ambiente en Brasil

¿Encontró un problema o tiene sugerencias para este tutorial?

🐛 Reportar en GitHub

Recetas YAML, GUI Shiny, addin de RStudio y scaffolding con `sus_rap_recipe()`, `sus_rap_gui()` y `sus_rap_template()`

Dr. Max Anjos

17 October, 2026

Introducción — Formatos de Compartición

Script .R

Receta YAML

GUI Shiny

Proyecto Completo

`sus_rap_recipe()` — Exportar como YAML Compacto

Motivación

Uso básico

Anatomía de la receta

Parámetros completos

`sus_rap_from_recipe()` — Importar y Reejecutar

Importación básica

Importar y ejecutar en una única llamada

Flujo colaborativo SP → RJ

Parámetros completos

`sus_rap_gui()` — Interfaz Visual Shiny

¿Para quién es la GUI?

Lanzar la GUI

La interfaz en tres paneles

Botones de acción

Iniciar desde cero

`sus_rap_addin_export()` — Addin de RStudio

¿Qué son los addins de RStudio?

Cómo usar `sus_rap_addin_export()`

Ejemplo de interacción

`sus_rap_template()` — Scaffolding de Proyecto Completo

El problema que resuelve

Creando un proyecto SINAN para análisis de dengue en Amazonas

Estructura generada

Fragmento del `_targets.R` generado

Integración continua con GitHub Actions

Parámetros completos

Flujo Colaborativo Completo

Tabla resumen de las funciones

Referencias

Compartir y Scaffolding de Proyectos RAP

Recetas YAML, GUI Shiny, addin de RStudio y scaffolding con sus_rap_recipe(), sus_rap_gui() y sus_rap_template()

Dr. Max Anjos

17 October, 2026

Introducción — Formatos de Compartición

Script .R

Receta YAML

GUI Shiny

Proyecto Completo

sus_rap_recipe() — Exportar como YAML Compacto

Motivación

Uso básico

Anatomía de la receta

Parámetros completos

sus_rap_from_recipe() — Importar y Reejecutar

Importación básica

Importar y ejecutar en una única llamada

Flujo colaborativo SP → RJ

Parámetros completos

sus_rap_gui() — Interfaz Visual Shiny

¿Para quién es la GUI?

Lanzar la GUI

La interfaz en tres paneles

Botones de acción

Iniciar desde cero

sus_rap_addin_export() — Addin de RStudio

¿Qué son los addins de RStudio?

Cómo usar sus_rap_addin_export()

Ejemplo de interacción

sus_rap_template() — Scaffolding de Proyecto Completo

El problema que resuelve

Creando un proyecto SINAN para análisis de dengue en Amazonas

Estructura generada

Fragmento del _targets.R generado

Integración continua con GitHub Actions

Parámetros completos

Flujo Colaborativo Completo

Tabla resumen de las funciones

Referencias

Recetas YAML, GUI Shiny, addin de RStudio y scaffolding con `sus_rap_recipe()`, `sus_rap_gui()` y `sus_rap_template()`

`sus_rap_recipe()` — Exportar como YAML Compacto

`sus_rap_from_recipe()` — Importar y Reejecutar

`sus_rap_gui()` — Interfaz Visual Shiny

`sus_rap_addin_export()` — Addin de RStudio

Cómo usar `sus_rap_addin_export()`

`sus_rap_template()` — Scaffolding de Proyecto Completo

Fragmento del `_targets.R` generado