
Exportar e Executar Pipelines Reprodutiveis
Serializar, ler,
inspecionar e reexecutar analises com sus_rap_export(),
sus_rap_read(), sus_rap_run() e
sus_rap_update()
Dr. Max Anjos
17 October, 2026
Source:vignettes/rap-01-exportar-executar.Rmd
rap-01-exportar-executar.RmdIntroducao — O que e um RAP?
O problema da reproducibilidade na epidemiologia ambiental
A pesquisa em saude publica e epidemiologia ambiental no Brasil enfrenta um desafio crescente: como garantir que uma analise realizada hoje — sobre mortalidade por doencas respiratorias em Sao Paulo no inverno de 2022 — possa ser reproduzida, atualizada e auditada por outro pesquisador daqui a tres anos? Com diferentes versoes de pacotes, bases de dados atualizadas, novos municipios a incluir?
Os Pipelines Analiticos Reprodutiveis (Reproducible Analytical Pipelines — RAPs) sao a resposta da ciencia de dados governamental e academica a esse problema. O conceito foi formalizado pela UK Government Data Science (2022) para garantir que analises publicadas por agencias publicas sejam auditaveis, atualizaveis e executaveis por qualquer colaborador com acesso ao ambiente correto.
No climasus4r, o modulo RAP serializa todo o pipeline de
analise — desde a importacao dos dados do DATASUS ate a agregacao
temporal — em um arquivo de texto portatil (.R,
.Rmd ou .qmd), com metadados de
rastreabilidade embarcados. Isso significa que voce pode:
- Arquivar a analise junto ao artigo como material suplementar
- Reexecutar o mesmo pipeline para novas unidades federativas ou periodos com um unico comando
- Comparar duas versoes do pipeline para identificar divergencias
- Atualizar parametros sem reabrir e editar o arquivo manualmente
Portabilidade
O pipeline exportado e um arquivo-texto padrao R. Qualquer colaborador com o climasus4r instalado pode reexecuta-lo.
Rastreabilidade
Metadados automaticos registram versao do R, pacotes, data/hora e plataforma no momento da exportacao.
Atualizabilidade
Parametros como UF, periodo e sistema DATASUS podem ser sobrescritos sem editar o arquivo exportado.
Comparabilidade
Duas versoes do pipeline podem ser comparadas lado a lado para identificar o que mudou entre revisoes.
A classe rap_object
O sus_rap_export() retorna um objeto da classe S3
rap_object, que e uma lista nomeada com sete campos:
| Campo | Tipo | Descricao |
|---|---|---|
metadata |
lista | Versao do R, pacotes, timestamp, plataforma, semente aleatoria |
params |
lista | Parametros detectados no pipeline (uf, years, system, etc.) |
steps |
lista | Cada etapa do pipeline com sua funcao e argumentos |
structure |
lista | Formato, tipo de output, numero total de etapas |
source |
character | Caminho do arquivo exportado em disco |
format |
character | Formato da exportacao ("script",
"rmarkdown", etc.) |
raw |
character | Linhas do arquivo exportado (para inspecao direta) |
Pre-requisitos
Construindo o pipeline de exemplo
Neste tutorial usaremos como caso condutor uma analise de
mortalidade por doencas respiratorias no estado de Sao Paulo,
2020-2022, importada do SIM-DO (Sistema de Informacoes sobre
Mortalidade). O pipeline e definido com quote(), que
captura a expressao sem avalia-la:
pipeline <- quote(
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", lang = "pt")
)Verificando a estrutura do pipeline
# O objeto 'pipeline' e um objeto de linguagem do tipo 'call'
class(pipeline)
#> [1] "call"
# Visualizando a arvore de chamadas
lobstr::ast(!!pipeline)
#> o-`|>`
#> +-o-`|>`
#> | +-o-`|>`
#> | | +-o-`|>`
#> | | | +-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", lang = "pt")
sus_rap_export() — Serializar o Pipeline
Assinatura completa
sus_rap_export(
pipeline = NULL,
file_path = NULL,
format = c("script", "rmarkdown", "quarto", "function"),
include_metadata = TRUE,
include_validation = TRUE,
include_documentation = c("standard", "minimal", "comprehensive"),
output_type = c("analysis", "dashboard", "report"),
lang = "pt",
overwrite = FALSE
)Exportar como script R (formato padrao)
O formato "script" gera um arquivo .R
auto-contido, com cabecalho de metadados, bloco de parametros, bloco de
validacao e o pipeline em si. E o formato recomendado para arquivamento
e reexecucao via linha de comando.
rap <- sus_rap_export(
pipeline = pipeline,
file_path = "analise_respiratoria_sp.R",
format = "script",
include_metadata = TRUE,
include_validation = TRUE,
include_documentation = "standard",
lang = "pt"
)
#> v Pipeline exportado para 'analise_respiratoria_sp.R'
#> i Formato : script
#> i Etapas : 5
#> i Parametros : uf, years, system, cid_group, by, lang
#> i Metadados : R 4.4.1 | climasus4r 0.1.0 | 2026-06-18 09:32:14Estrutura do arquivo gerado
O arquivo analise_respiratoria_sp.R exportado tem a
seguinte estrutura:
# ============================================================
# RAP gerado por climasus4r::sus_rap_export()
# Timestamp : 2026-06-18 09:32:14 BRT
# R version : 4.4.1 (2024-06-14)
# climasus4r: 0.1.0
# Plataforma: aarch64-apple-darwin20
# ============================================================
# -- PARAMETROS (edite aqui para reutilizar o pipeline) ------
params <- list(
uf = "SP",
years = 2020:2022,
system = "SIM-DO",
cid_group = "respiratory",
by = "month",
lang = "pt"
)
# -- VALIDACAO -----------------------------------------------
stopifnot(
is.character(params$uf),
all(params$years >= 1979),
params$system %in% c("SIM-DO", "SIH", "SINAN", "SIA", "CNES", "SINASC")
)
# -- PIPELINE ------------------------------------------------
resultado <- sus_data_import(
uf = params$uf, years = params$years, system = params$system
) |>
sus_data_clean_encoding() |>
sus_data_standardize() |>
sus_data_filter_cid(cid_group = params$cid_group) |>
sus_data_aggregate(by = params$by, lang = params$lang)Estrutura do rap_object retornado
str(rap)
#> List of 7
#> $ metadata : list [r_version, packages, timestamp, platform, seed]
#> $ params : list [uf, years, system, cid_group, by, lang]
#> $ steps : list [5 pipeline steps]
#> $ structure: list [type, input_params, output_params, total_steps]
#> $ source : chr "analise_respiratoria_sp.R"
#> $ format : chr "script"
#> $ raw : chr [linhas do arquivo exportado]
#> - attr(*, "class")= chr [1:2] "rap_object" "list"
# Acessando campos individuais
rap$params$uf
#> [1] "SP"
rap$metadata$r_version
#> [1] "R version 4.4.1 (2024-06-14)"
rap$structure$total_steps
#> [1] 5Exportar como R Markdown
Para publicacao de relatorios reproduced com narrativa, use
format = "rmarkdown". O arquivo .Rmd gerado
inclui cabecalho YAML, blocos de configuracao e o pipeline dentro de
chunks executaveis.
rap_rmd <- sus_rap_export(
pipeline = pipeline,
file_path = "relatorio_respiratorio_sp.Rmd",
format = "rmarkdown",
include_metadata = TRUE,
include_validation = TRUE,
include_documentation = "comprehensive",
output_type = "report",
lang = "pt"
)
#> v Pipeline exportado para 'relatorio_respiratorio_sp.Rmd'
#> i Formato : rmarkdown
#> i Etapas : 5
#> i output_type : report
#> i Documentacao : comprehensiveExportar como Quarto
O formato "quarto" gera um arquivo .qmd
compativel com o sistema Quarto, ideal para documentos tecnicos modernos
com suporte a Python, Julia e execucao multipla de engines.
rap_qmd <- sus_rap_export(
pipeline = pipeline,
file_path = "analise_respiratoria_sp.qmd",
format = "quarto",
output_type = "dashboard",
lang = "pt"
)
#> v Pipeline exportado para 'analise_respiratoria_sp.qmd'
#> i Formato: quarto | output_type: dashboardExportar como funcao encapsulada
O formato "function" e o mais adequado para integracao
em pacotes ou scripts de automacao. O pipeline e encapsulado em uma
funcao R com todos os parametros como argumentos formais, pronta para
ser importada ou reutilizada programaticamente.
rap_fn <- sus_rap_export(
pipeline = pipeline,
file_path = "run_analise_respiratoria.R",
format = "function",
lang = "pt"
)
#> v Pipeline exportado para 'run_analise_respiratoria.R'
#> i Formato: function
#> i Funcao gerada: run_pipeline(uf, years, system, cid_group, by, lang)O arquivo gerado contem uma funcao como esta:
run_pipeline <- function(
uf = "SP",
years = 2020:2022,
system = "SIM-DO",
cid_group = "respiratory",
by = "month",
lang = "pt"
) {
sus_data_import(uf = uf, years = years, system = system) |>
sus_data_clean_encoding() |>
sus_data_standardize() |>
sus_data_filter_cid(cid_group = cid_group) |>
sus_data_aggregate(by = by, lang = lang)
}Niveis de documentacao (include_documentation)
O parametro include_documentation controla a quantidade
de comentarios gerados no arquivo exportado:
| Nivel | Descricao |
|---|---|
"minimal" |
Apenas o cabecalho essencial e o bloco de parametros |
"standard" |
Cabecalho, parametros, validacao e comentarios de etapa |
"comprehensive" |
Tudo acima + descricao de cada funcao, tipos esperados e links para a documentacao |
# Exportacao minima -- apenas o essencial
rap_min <- sus_rap_export(
pipeline = pipeline,
file_path = "analise_minima.R",
include_documentation = "minimal",
lang = "pt"
)
# Exportacao abrangente -- maxima rastreabilidade
rap_full <- sus_rap_export(
pipeline = pipeline,
file_path = "analise_completa.R",
include_documentation = "comprehensive",
lang = "pt"
)
sus_rap_read() — Ler de Volta
Depois de exportado, o arquivo .R (ou
.Rmd/.qmd) pode ser lido de volta para um
rap_object em qualquer sessao R, mesmo que o pipeline
original nao exista mais na memoria.
Assinatura
sus_rap_read(file_path, lang = "pt", validate = TRUE)Lendo o arquivo exportado
rap2 <- sus_rap_read("analise_respiratoria_sp.R", lang = "pt")
#> v Arquivo lido: 'analise_respiratoria_sp.R'
#> v Metadados validados
#> i R version : 4.4.1 (exportado em 2026-06-18 09:32:14)
#> i climasus4r : 0.1.0
#> i Etapas : 5
#> i Parametros : uf = "SP" | years = 2020:2022 | system = "SIM-DO"Imprimindo o rap_object
O metodo print.rap_object() exibe um resumo formatado do
pipeline:
print(rap2)
#> -- RAP: analise_respiratoria_sp.R -----------------------
#> Formato : script
#> Exportado : 2026-06-18 09:32:14 BRT
#> R version : 4.4.1 | climasus4r 0.1.0
#> Plataforma: aarch64-apple-darwin20
#>
#> -- Parametros ------------------------------------------
#> uf : "SP"
#> years : 2020 2021 2022
#> system : "SIM-DO"
#> cid_group : "respiratory"
#> by : "month"
#> lang : "pt"
#>
#> -- Pipeline (5 etapas) ----------------------------------
#> [1] sus_data_import()
#> [2] sus_data_clean_encoding()
#> [3] sus_data_standardize()
#> [4] sus_data_filter_cid()
#> [5] sus_data_aggregate()
#> ---------------------------------------------------------
sus_rap_inspect() — Inspecionar e Comparar
Assinatura
sus_rap_inspect(rap, rap2 = NULL, verbose = TRUE, lang = "pt")5.1 Inspecao de um unico RAP
Com apenas um rap_object, sus_rap_inspect()
exibe um resumo detalhado do pipeline: etapas, parametros, metadados e,
com verbose = TRUE, o codigo raw do arquivo exportado.
sus_rap_inspect(rap2, verbose = TRUE)
#> == Inspecao: analise_respiratoria_sp.R ==================
#>
#> METADADOS
#> Timestamp : 2026-06-18 09:32:14 BRT
#> R version : 4.4.1
#> climasus4r: 0.1.0
#> Plataforma: aarch64-apple-darwin20
#> Semente : nao definida
#>
#> ESTRUTURA
#> Formato : script
#> Total etapas : 5
#> Output type : analysis
#> Documentacao : standard
#>
#> PARAMETROS
#> uf = "SP"
#> years = 2020:2022
#> system = "SIM-DO"
#> cid_group = "respiratory"
#> by = "month"
#> lang = "pt"
#>
#> PIPELINE
#> [1] sus_data_import(uf, years, system)
#> [2] sus_data_clean_encoding()
#> [3] sus_data_standardize()
#> [4] sus_data_filter_cid(cid_group)
#> [5] sus_data_aggregate(by, lang)
#>
#> CODIGO (raw)
#> [ver arquivo: analise_respiratoria_sp.R]
#> =========================================================5.2 Comparacao entre dois RAPs (diff)
Ao passar dois rap_objects,
sus_rap_inspect() realiza um diff estruturado,
identificando:
- Parametros que mudaram de valor
- Etapas adicionadas ou removidas
- Divergencias nos metadados (versao de pacote, plataforma)
O cenario abaixo compara o pipeline de Sao Paulo com uma versao equivalente exportada para o Rio de Janeiro:
# Primeiro, exportamos o pipeline para o RJ
pipeline_rj <- quote(
sus_data_import(uf = "RJ", 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", lang = "pt")
)
sus_rap_export(
pipeline = pipeline_rj,
file_path = "analise_respiratoria_rj.R",
lang = "pt"
)
rap_rj <- sus_rap_read("analise_respiratoria_rj.R")
sus_rap_inspect(rap2, rap_rj)
#> == Diff: [1] analise_respiratoria_sp.R vs [2] analise_respiratoria_rj.R ==
#>
#> PARAMETROS ALTERADOS
#> uf : "SP" --> "RJ"
#>
#> PARAMETROS IDENTICOS
#> years, system, cid_group, by, lang
#>
#> ETAPAS
#> Identicas : 5/5 (nenhuma etapa adicionada ou removida)
#>
#> METADADOS
#> Timestamps : diferentes (2026-06-18 09:32:14 vs 2026-06-18 09:45:07)
#> R version : identicas (4.4.1)
#> climasus4r : identicas (0.1.0)
#>
#> CONCLUSAO: pipelines equivalentes com parametro 'uf' distinto.
#> =========================================================
sus_rap_run() — Reexecutar com Novos Parametros
Assinatura
sus_rap_run(rap, ..., envir = parent.frame(), dry_run = FALSE, lang = "pt")Os argumentos passados via ... sobrescrevem os
parametros do RAP apenas na execucao atual — o arquivo
em disco nao e modificado. Para modificar permanentemente o arquivo, use
sus_rap_update() (secao 7).
6.1 Simulacao com dry_run = TRUE
Antes de executar o pipeline com novos parametros, e recomendado
verificar o codigo que seria executado usando
dry_run = TRUE. Nenhuma conexao ao DATASUS e aberta, nenhum
dado e baixado.
sus_rap_run(rap2, uf = "RJ", years = 2021:2023, dry_run = TRUE)
#> -- [dry_run] Codigo que seria executado ------------------
#>
#> sus_data_import(uf = "RJ", years = 2021:2023, system = "SIM-DO") |>
#> sus_data_clean_encoding() |>
#> sus_data_standardize() |>
#> sus_data_filter_cid(cid_group = "respiratory") |>
#> sus_data_aggregate(by = "month", lang = "pt")
#>
#> Parametros substituidos: uf = "RJ" | years = 2021:2023
#> Parametros mantidos : system, cid_group, by, lang
#> ----------------------------------------------------------
#> i Nenhum dado foi baixado (dry_run = TRUE)6.2 Execucao efetiva
Confirmado o codigo, remova dry_run = TRUE para executar
o pipeline:
resultado_rj <- sus_rap_run(
rap2,
uf = "RJ",
years = 2021:2023,
lang = "pt"
)
#> -- Executando RAP: analise_respiratoria_sp.R -------------
#> i Parametros substituidos: uf = "RJ" | years = 2021:2023
#> v [1/5] sus_data_import() ... 148.392 registros importados
#> v [2/5] sus_data_clean_encoding() ... concluido
#> v [3/5] sus_data_standardize() ... concluido
#> v [4/5] sus_data_filter_cid() ... 42.817 registros (cid_group = "respiratory")
#> v [5/5] sus_data_aggregate() ... 36 linhas (mensal, 2021-2023)
#> -- Pipeline concluido em 4.2 segundos --------------------
class(resultado_rj)
#> [1] "climasus_df" "tbl_df" "tbl" "data.frame"6.3 Sobrescrevendo multiplos parametros
Voce pode sobrescrever quantos parametros quiser em uma unica chamada:
resultado_mg_anual <- sus_rap_run(
rap2,
uf = "MG",
years = 2019:2023,
by = "year",
lang = "en"
)
#> -- Executando RAP: analise_respiratoria_sp.R -------------
#> i Parametros substituidos: uf = "MG" | years = 2019:2023 | by = "year"
#> v Pipeline concluido em 6.1 segundos6.4 Controle do ambiente de execucao
O argumento envir define em qual ambiente o pipeline e
avaliado. O padrao parent.frame() e adequado para uso
interativo. Para execucoes automatizadas em scripts ou funcoes, passe
envir = new.env() para isolar o pipeline:
env_isolado <- new.env(parent = baseenv())
resultado_iso <- sus_rap_run(
rap2,
uf = "CE",
envir = env_isolado
)
sus_rap_update() — Atualizar Parametros no Arquivo
Assinatura
sus_rap_update(rap, ..., backup = TRUE, lang = "pt")Enquanto sus_rap_run() substitui parametros apenas para
a execucao atual (sem tocar o arquivo), sus_rap_update()
edita permanentemente o bloco de parametros no arquivo
em disco. Isso e util quando voce quer que a versao “oficial” do
pipeline reflita uma mudanca permanente de escopo.
Atualizando a UF e o periodo
sus_rap_update(
rap2,
uf = c("RJ", "MG"),
years = 2021:2023,
lang = "pt"
)
#> i Backup criado: analise_respiratoria_sp.R.bak (2026-06-18 10:02:31)
#> v Parametros atualizados em 'analise_respiratoria_sp.R':
#> uf : "SP" --> c("RJ", "MG")
#> years : 2020:2022 --> 2021:2023
#> i Parametros nao alterados: system, cid_group, by, langO bloco de parametros antes e depois
Antes da atualizacao:
# -- PARAMETROS (edite aqui para reutilizar o pipeline) ------
params <- list(
uf = "SP",
years = 2020:2022,
system = "SIM-DO",
cid_group = "respiratory",
by = "month",
lang = "pt"
)Depois da atualizacao:
Backup automatico
Por padrao, backup = TRUE cria uma copia do arquivo
original antes de qualquer modificacao, com o sufixo .bak e
timestamp. Isso garante que voce nunca perca a versao anterior do
pipeline:
# O backup e criado automaticamente:
# analise_respiratoria_sp.R.bak.2026-06-18_10-02-31
# Para restaurar manualmente:
file.copy(
"analise_respiratoria_sp.R.bak.2026-06-18_10-02-31",
"analise_respiratoria_sp.R",
overwrite = TRUE
)Recarregando o RAP atualizado
Apos a atualizacao, releia o arquivo para ter um
rap_object com os parametros novos refletidos em
memoria:
rap2_atualizado <- sus_rap_read("analise_respiratoria_sp.R")
# Confirme a atualizacao
rap2_atualizado$params$uf
#> [1] "RJ" "MG"
rap2_atualizado$params$years
#> [1] 2021 2022 2023Fluxo Completo
O ciclo completo de vida de um RAP no climasus4r passa
por seis etapas. O diagrama abaixo ilustra a sequencia tipica de
uso:
Script completo de referencia
O codigo abaixo reune todas as etapas em um unico script de referencia:
library(climasus4r)
# 1. Definir o pipeline com quote()
pipeline <- quote(
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", lang = "pt")
)
# 2. Exportar para disco
rap <- sus_rap_export(
pipeline = pipeline,
file_path = "analise_respiratoria_sp.R",
format = "script",
include_documentation = "standard",
lang = "pt"
)
# 3. Reler de disco (simula colaborador recebendo o arquivo)
rap2 <- sus_rap_read("analise_respiratoria_sp.R")
# 4. Inspecionar
sus_rap_inspect(rap2, verbose = TRUE)
# 5. Simular execucao com novos parametros (sem baixar dados)
sus_rap_run(rap2, uf = "RJ", years = 2021:2023, dry_run = TRUE)
# 6. Executar de verdade
resultado <- sus_rap_run(rap2, uf = "RJ", years = 2021:2023)
# 7. Atualizar parametros no arquivo para escopo ampliado
sus_rap_update(rap2, uf = c("RJ", "MG"), years = 2021:2023)Tabela de referencia rapida
| Funcao | Entrada | Saida | Modifica disco? |
|---|---|---|---|
sus_rap_export() |
quote(pipeline) |
rap_object |
Sim (cria arquivo) |
sus_rap_read() |
caminho do arquivo | rap_object |
Nao |
sus_rap_inspect() |
1 ou 2 rap_object
|
output no console | Nao |
sus_rap_run() |
rap_object |
climasus_df |
Nao |
sus_rap_update() |
rap_object + params |
rap_object (invisivel) |
Sim (edita arquivo) |
Referencias
Wilson G, Bryan J, Cranston K, Kitzes J, Nederbragt L, Teal TK (2017). Good enough practices in scientific computing. PLOS Computational Biology, 13(6), e1005510. https://doi.org/10.1371/journal.pcbi.1005510
Marwick B, Boettiger C, Mullen L (2018). Packaging data analytical work reproducibly using R (and friends). The American Statistician, 72(1), 80-88. https://doi.org/10.1080/00031305.2017.1375986
UK Government Data Science (2022). Reproducible Analytical Pipelines (RAP) Strategy. Cabinet Office, His Majesty’s Government. https://analysisfunction.civilservice.gov.uk/support/reproducible-analytical-pipelines/
Anjos M (2026). climasus4r: Analise integrada saude-clima-ambiente no Brasil. R package version 0.1.0. https://github.com/ByMaxAnjos/climasus4r
Navegacao: Anterior: Tutoriais Tematicos | Proximo: RAP 2 - Pipelines com targets
climasus4r · Analise integrada saude-clima-ambiente no Brasil
Encontrou um problema ou tem sugestoes para este tutorial?
🐛 Reportar no GitHub