Compartilhar e Scaffolding de Projetos RAP

Introdução — Formatos de Compartilhamento

Um Reproducible Analytical Pipeline (RAP) só cumpre seu propósito quando pode ser compartilhado e reexecutado por outras pessoas — em outros contextos, com outros dados, sem perda de rastreabilidade. O climasus4r oferece quatro estratégias complementares para isso, cada uma adequada a um perfil de colaborador e de caso de uso.

📄

Script .R

Arquivo completo com codigo, metadados e validacoes. Ideal para colaboradores com R avancado (RAP 1).

📋

Receita YAML

Formato compacto (<50 linhas). Facil de ler, enviar por e-mail e importar com sus_rap_from_recipe().

🖥️

GUI Shiny

Interface visual sem codigo. Ideal para pesquisadores sem experiencia em R ou para demonstracoes.

📁

Projeto Completo

Estrutura pronta com renv + targets + Quarto. Para novos projetos de analise reprodutivel de longa duracao.

A tabela a seguir resume quando usar cada abordagem:

Formato	Audiência-alvo	Tamanho do artefato	Requer R no receptor
Script `.R`	Desenvolvedor / analista avançado	Médio (100–300 linhas)	Sim
Receita YAML	Qualquer analista com `climasus4r`	Compacto (< 50 linhas)	Sim
GUI Shiny	Pesquisador sem experiência em R	Interface web	Não (para uso)
Projeto completo	Novo projeto de longa duração	Diretório estruturado	Sim

**Pré-requisito:** Este tutorial assume familiaridade com os conceitos de RAP introduzidos em RAP 1 — Exportar e Executar Pipelines e com a estrutura rap_object do climasus4r. Se você ainda não leu aquele tutorial, recomendamos começar por ele.

`sus_rap_recipe()` — Exportar como YAML Compacto

Motivação

Imagine que um analista em São Paulo desenvolveu um pipeline completo de mortalidade por causas respiratórias e quer compartilhá-lo com uma colega no Rio de Janeiro. Enviar um script .R de 200 linhas pode ser intimidante; enviar um arquivo YAML de 40 linhas é muito mais acessível. sus_rap_recipe() faz exatamente isso: serializa os parâmetros, as etapas e as versões do pacote em um formato legível por humanos e reimportável por máquinas.

Uso básico

library(climasus4r)

# Partir de um rap_object existente (criado com sus_rap_export())
rap <- sus_rap_read("analise_mortalidade_sp.R")

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

O arquivo gerado é compacto e editável diretamente em qualquer 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

Anatomia da receita

Campo	Descrição
`rap_version`	Versão do esquema de receita (controle de compatibilidade)
`created`	Timestamp de geração (ISO 8601)
`climasus4r_version`	Versão do pacote no momento da exportação
`pipeline_type`	Tipo inferido do pipeline (ex.: “Pipeline SIM-DO”)
`parameters`	Bloco editável com UF, anos, sistema e outros parâmetros
`steps`	Lista ordenada de etapas com nome da função e parâmetros-chave
`metadata`	Versão do R, plataforma e versão do pacote
`data_hash`	Hash xxhash32 dos parâmetros de entrada — garante rastreabilidade

**Dica — `data_hash`:** O campo `data_hash` é calculado a partir dos parâmetros de entrada (`uf`, `years`, `system`). Se dois analistas gerarem o mesmo hash a partir de receitas diferentes, isso indica que partiram de exatamente os mesmos dados de entrada — útil para auditorias e reprodução certificada.

Parâmetros completos

sus_rap_recipe(
  rap               = rap,        # rap_object (obrigatório)
  file_path         = NULL,       # NULL → nome com timestamp no diretório atual
  include_data_hash = TRUE,       # incluir hash para rastreabilidade
  lang              = "pt",       # idioma das mensagens ("pt", "en", "es")
  overwrite         = FALSE       # sobrescrever arquivo existente?
)

Quando file_path = NULL, o arquivo é criado no diretório de trabalho atual com nome no formato rap_recipe_YYYYMMDD_HHMMSS.yaml.

`sus_rap_from_recipe()` — Importar e Reexecutar

Importação básica

A colega no Rio de Janeiro recebe o arquivo pipeline_mortalidade.yaml e o importa com uma única função:

# Colega no RJ importa a receita
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

O parâmetro override_params permite adaptar a receita original sem editar o arquivo YAML: aqui a UF foi trocada de SP para RJ e o período foi estendido. Todos os demais parâmetros — filtros CID, agregação temporal, idioma — são herdados da receita original.

Importar e executar em uma única chamada

Para fluxos de automação, execute = TRUE encadeia a importação e a execução do 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

Quando execute = TRUE, a função retorna o resultado do pipeline (um climasus_df) em vez do rap_object.

Fluxo 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",  # caminho para o .yaml (obrigatório)
  override_params = list(),     # parâmetros a sobrescrever (lista nomeada)
  execute         = FALSE,      # TRUE = executar imediatamente após importar
  lang            = "pt",       # idioma das mensagens
  ...                           # argumentos extras para sus_rap_run() quando execute=TRUE
)

**Verificação de versão:** Se a receita foi criada com uma versão anterior do `climasus4r`, a função emite um aviso mas prossegue. Para ambientes críticos de produção, verifique o campo `climasus4r_version` na receita antes de executar.

`sus_rap_gui()` — Interface Visual Shiny

Para quem é a GUI?

A interface gráfica do climasus4r é voltada para três perfis:

Pesquisadores sem experiência em R que precisam configurar e executar um pipeline
Demonstrações e workshops onde o foco está nos resultados, não no código
Exploração rápida de combinações de parâmetros antes de formalizar o pipeline

Lançar a GUI

# Lançar com um rap_object pré-carregado
sus_rap_gui(rap = rap, launch.browser = TRUE)

A interface abre no navegador padrão do sistema. Se preferir visualizar no Viewer do RStudio, use launch.browser = FALSE.

**Pacote shiny necessário:** `sus_rap_gui()` requer o pacote `shiny` (listado em Suggests). Instale com `install.packages("shiny")` antes de usar.

A interface em três painéis

A GUI é organizada em três painéis laterais que trabalham em conjunto:

Painel esquerdo — Parâmetros:

Campo de texto para UF(s) separadas por vírgula (ex.: SP, RJ, MG)
Slider de intervalo de anos (2000–2024)
Dropdown para sistema DATASUS (SIM-DO, SIH, SINAN, SIA, CNES, SINASC)
Dropdown para unidade de agregação temporal (day, week, month, quarter, year)
Selector de idioma (pt, en, es)
Campo para diretório de saída

Painel central — Pipeline:

Cards visuais, um por etapa do RAP, listando o nome da função e os argumentos configurados
Atualizado automaticamente conforme os parâmetros são alterados

Painel direito — Console:

Log em tempo real com timestamps ([HH:MM:SS] mensagem)
Pré-visualização do código R que será executado

Botões de ação

Botão	Ação
Prévia do Código	Exibe o código R equivalente no painel direito
Executar Pipeline	Chama `sus_rap_run()` em modo `dry_run = FALSE`
Exportar RAP	Salva o pipeline como script `.R` via `sus_rap_export()`
Salvar Receita YAML	Salva o pipeline como receita `.yaml` via `sus_rap_recipe()`

Iniciar do zero

Para criar um pipeline interativamente sem ponto de partida, passe rap = NULL:

# Lançar sem RAP pré-carregado
sus_rap_gui(rap = NULL)

A GUI inicializa com um template padrão (SIM-DO, SP, 2019–2022) que pode ser editado livremente.

**Dica de workflow:** Use a GUI para explorar combinações de parâmetros rapidamente, clique em "Prévia do Código" para ver o R gerado, copie-o para o seu script, e então refine com `sus_rap_export()` para o artefato final. Isso combina o melhor dos dois mundos: velocidade da GUI e rastreabilidade do script.

`sus_rap_addin_export()` — Addin do RStudio

O que são addins do RStudio?

Addins são extensões do RStudio IDE que aparecem no menu Addins (barra de ferramentas superior) e podem ser acionadas com um atalho de teclado ou via Tools → Addins. Eles executam funções R no contexto da sessão ativa, podendo interagir com o editor de código, o ambiente e o console.

O climasus4r registra dois addins no arquivo 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

Após instalar o climasus4r, os addins ficam automaticamente disponíveis no menu Addins do RStudio — nenhuma configuração adicional é necessária.

Como usar `sus_rap_addin_export()`

O fluxo de trabalho é intuitivo:

Abra um script .R no RStudio com um pipeline climasus4r
Selecione o código do pipeline com o cursor (do sus_data_import() até o último passo)
Acesse Addins → Exportar Pipeline como RAP
O addin captura o texto selecionado via rstudioapi::getSourceEditorContext(), faz o parse da expressão, e chama sus_rap_export() para criar um arquivo .R no mesmo diretório do script ativo

O arquivo exportado terá nome no formato rap_YYYYMMDD_HHMMSS.R e conterá o pipeline completo com metadados embutidos, bloco de parâmetros editável e validações.

Exemplo de interação

# Código selecionado no 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")

# Após acionar o addin → cria: ./rap_20260618_103045.R
#> [Dialogo RStudio] Pipeline exportado com sucesso:
#>   /home/usuario/analises/rap_20260618_103045.R

**Dica:** O addin funciona apenas dentro do RStudio IDE. Para uso em linha de comando ou VS Code, use `sus_rap_export()` diretamente (ver RAP Tutorial 1).

**Seleção parcial:** O addin espera que o código selecionado seja uma expressão R válida (com pipe `|>` ou `%>%`). Se a seleção não for parseável, uma caixa de diálogo informará o erro. Selecione apenas as linhas do pipeline, sem comentários no meio.

`sus_rap_template()` — Scaffolding de Projeto Completo

O problema que ele resolve

Configurar um projeto de análise reprodutível do zero envolve uma série de decisões repetitivas: criar a estrutura de diretórios, configurar o renv para capturar dependências, escrever o _targets.R com a lógica do pipeline, criar o relatório Quarto, adicionar o .gitignore correto… sus_rap_template() automatiza tudo isso em uma única chamada.

Criando um projeto SINAN para análise de dengue no 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

Estrutura gerada

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 arquivo cumpre um papel claro na arquitetura RAP:

Arquivo	Propósito
`_targets.R`	Define o grafo de dependências do pipeline
`run.R`	Entrada única de execução: `targets::tar_make()`
`analysis.qmd`	Relatório parametrizado que carrega os resultados do `_targets`
`R/functions.R`	Funções auxiliares específicas do projeto
`data/`	Dados brutos (nunca commitados no git)
`output/`	Resultados computados (nunca commitados no git)
`renv.lock`	Snapshot exato das versões dos pacotes

Trecho do `_targets.R` gerado

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

**Dica:** Após criar o projeto, edite o campo `uf` e o intervalo `years` no bloco `tar_target(params, ...)` no topo do `_targets.R`. Em seguida, execute `targets::tar_make()` a partir do diretório do projeto para rodar o pipeline completo.

Integração contínua com GitHub Actions

Para projetos que precisam de execução automatizada — por exemplo, atualização mensal de um painel epidemiológico — use include_github_actions = TRUE:

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

O arquivo .github/workflows/rap.yml gerado tem a seguinte estrutura:

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/

O workflow é acionado em cada push para main e também pode ser disparado manualmente via workflow_dispatch. Os resultados são disponibilizados como artefato de build no GitHub Actions.

**Dados sensíveis:** O diretório `data/` está no `.gitignore` gerado automaticamente. Nunca commite dados brutos do DATASUS em repositórios públicos. Para pipelines com CI/CD, considere armazenar os dados em um bucket S3 ou equivalente e recuperá-los na etapa de CI.

Parâmetros completos

sus_rap_template(
  path                   = "~/projetos",  # diretório pai (obrigatório)
  name                   = "meu_projeto", # nome do projeto/diretório (obrigatório)
  system                 = "SIM-DO",      # sistema DATASUS para o template
  include_renv           = TRUE,          # inicializar renv?
  include_targets        = TRUE,          # criar _targets.R e run.R?
  include_quarto         = TRUE,          # criar analysis.qmd?
  include_github_actions = FALSE,         # criar .github/workflows/rap.yml?
  lang                   = "pt"           # idioma dos comentários gerados
)

Fluxo Colaborativo Completo

As cinco funções deste tutorial são projetadas para trabalhar em conjunto. O diagrama a seguir ilustra um fluxo completo: da criação do pipeline até a reprodução por outro analista.

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

Tabela resumo das funções

Função	Entrada	Saída	Caso de uso principal
`sus_rap_recipe()`	`rap_object`	arquivo `.yaml`	Compartilhar pipeline compacto com colegas
`sus_rap_from_recipe()`	arquivo `.yaml`	`rap_object`	Importar e opcionalmente reexecutar
`sus_rap_gui()`	`rap_object` ou NULL	Shiny app	Interface visual para não-programadores
`sus_rap_addin_export()`	seleção no editor RStudio	arquivo `.R`	Fluxo rápido dentro do IDE
`sus_rap_template()`	parâmetros de configuração	diretório de projeto	Scaffolding de novo projeto reprodutível

Escolhendo o formato certo:

YAML quando o receptor é analista e precisa adaptar parâmetros
GUI quando o receptor não programa em R ou para demonstrações ao vivo
Template quando está começando um projeto novo e quer a estrutura completa desde o início
Script .R (via sus_rap_export()) quando o receptor é desenvolvedor e vai modificar o código

Referências

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. Disponível em: 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.

Navegação: Anterior: RAP 2 - Pipelines com targets | Todos os tutoriais

climasus4r · Análise integrada saúde-clima-ambiente no Brasil

Encontrou um problema ou tem sugestões para este tutorial?

🐛 Reportar no GitHub

Receitas YAML, GUI Shiny, addin RStudio e scaffolding com `sus_rap_recipe()`, `sus_rap_gui()` e `sus_rap_template()`

Dr. Max Anjos

17 October, 2026

Introdução — Formatos de Compartilhamento

Script .R

Receita YAML

GUI Shiny

Projeto Completo

`sus_rap_recipe()` — Exportar como YAML Compacto

Motivação

Uso básico

Anatomia da receita

Parâmetros completos

`sus_rap_from_recipe()` — Importar e Reexecutar

Importação básica

Importar e executar em uma única chamada

Fluxo colaborativo SP → RJ

Parâmetros completos

`sus_rap_gui()` — Interface Visual Shiny

Para quem é a GUI?

Lançar a GUI

A interface em três painéis

Botões de ação

Iniciar do zero

`sus_rap_addin_export()` — Addin do RStudio

O que são addins do RStudio?

Como usar `sus_rap_addin_export()`

Exemplo de interação

`sus_rap_template()` — Scaffolding de Projeto Completo

O problema que ele resolve

Criando um projeto SINAN para análise de dengue no Amazonas

Estrutura gerada

Trecho do `_targets.R` gerado

Integração contínua com GitHub Actions

Parâmetros completos

Fluxo Colaborativo Completo

Tabela resumo das funções

Referências

Compartilhar e Scaffolding de Projetos RAP

Receitas YAML, GUI Shiny, addin RStudio e scaffolding com sus_rap_recipe(), sus_rap_gui() e sus_rap_template()

Dr. Max Anjos

17 October, 2026

Introdução — Formatos de Compartilhamento

Script .R

Receita YAML

GUI Shiny

Projeto Completo

sus_rap_recipe() — Exportar como YAML Compacto

Motivação

Uso básico

Anatomia da receita

Parâmetros completos

sus_rap_from_recipe() — Importar e Reexecutar

Importação básica

Importar e executar em uma única chamada

Fluxo colaborativo SP → RJ

Parâmetros completos

sus_rap_gui() — Interface Visual Shiny

Para quem é a GUI?

Lançar a GUI

A interface em três painéis

Botões de ação

Iniciar do zero

sus_rap_addin_export() — Addin do RStudio

O que são addins do RStudio?

Como usar sus_rap_addin_export()

Exemplo de interação

sus_rap_template() — Scaffolding de Projeto Completo

O problema que ele resolve

Criando um projeto SINAN para análise de dengue no Amazonas

Estrutura gerada

Trecho do _targets.R gerado

Integração contínua com GitHub Actions

Parâmetros completos

Fluxo Colaborativo Completo

Tabela resumo das funções

Referências

Receitas YAML, GUI Shiny, addin RStudio e scaffolding com `sus_rap_recipe()`, `sus_rap_gui()` e `sus_rap_template()`

`sus_rap_recipe()` — Exportar como YAML Compacto

`sus_rap_from_recipe()` — Importar e Reexecutar

`sus_rap_gui()` — Interface Visual Shiny

`sus_rap_addin_export()` — Addin do RStudio

Como usar `sus_rap_addin_export()`

`sus_rap_template()` — Scaffolding de Projeto Completo

Trecho do `_targets.R` gerado