Pipelines com Cache Inteligente usando targets

Introdução — Por que usar `targets`?

Análises epidemiológicas com dados climáticos raramente são lineares. Ao longo do ciclo de pesquisa, é comum alterar um filtro de CID-10, substituir a janela de agregação climática ou incluir um novo estado no conjunto de dados. Sem um sistema de cache inteligente, qualquer dessas mudanças força a re-execução de todo o pipeline — incluindo etapas custosas como o download do DATASUS, a padronização de encoding e a junção espacial, que podem levar horas.

O pacote targets (Landau, 2021) resolve esse problema com rastreamento automático de dependências: cada etapa do pipeline é um target (alvo), e o targets só re-executa os alvos cujas entradas mudaram desde a última execução. Os resultados intermediários ficam em cache no diretório _targets/, prontos para serem carregados instantaneamente.

A função sus_rap_targets() faz a ponte entre os objetos RAP do climasus4r e o ecossistema targets, gerando automaticamente o arquivo _targets.R com toda a estrutura necessária. A função sus_rap_make() então executa esse pipeline de forma reproduzível, com suporte a paralelismo e monitoramento.

rap_object → sus_rap_targets() → _targets.R → sus_rap_make() → resultados com cache

Funções abordadas neste tutorial

Este tutorial cobre duas funções exportadas do climasus4r:

Função	Descrição
`sus_rap_targets()`	Gera o arquivo `_targets.R` a partir de um objeto RAP
`sus_rap_make()`	Executa o pipeline via `targets::tar_make()`

Pré-requisitos

Instalação das dependências

O pacote targets é listado em Suggests do climasus4r. Instale antes de usar as funções deste tutorial:

# Dependencias necessarias
install.packages("targets")
install.packages("tarchetypes")  # opcional: helpers adicionais

**Pacote targets necessario:** `targets` esta listado em `Suggests` do climasus4r. Instale antes de usar `sus_rap_targets()` e `sus_rap_make()`. O `climasus4r` verificara automaticamente a disponibilidade do pacote ao chamar essas funcoes.

Ponto de partida: o objeto RAP

As funções deste tutorial operam sobre um objeto RAP — uma expressão de pipeline criada com as funções do climasus4r. Você pode obtê-lo de duas formas:

library(climasus4r)

# Opcao A: ler um RAP existente (criado com sus_rap_export())
rap <- sus_rap_read("analise_dengue_nordeste.R")

# Opcao B: usar uma expressao de pipeline diretamente
pipeline <- quote(
  sus_data_import(uf = c("CE", "RN", "PB", "PE", "AL"),
                  years = 2018:2022, system = "SINAN") |>
    sus_data_clean_encoding() |>
    sus_data_standardize() |>
    sus_data_filter_cid(cid_group = "dengue") |>
    sus_data_aggregate(by = "month")
)

**Sobre o objeto RAP:** O Tutorial RAP 1 — *Exportar e Executar* — explica em detalhes como criar, exportar e carregar objetos RAP com `sus_rap_export()` e `sus_rap_read()`. Consulte-o se precisar criar o objeto do zero.

`sus_rap_targets()` — Gerar o `_targets.R`

A função sus_rap_targets() recebe um pipeline do climasus4r e gera um arquivo _targets.R pronto para ser executado com o pacote targets.

Assinatura da função

sus_rap_targets(
  pipeline,
  file_path  = "_targets.R",
  branching  = c("none", "uf", "year", "cross"),
  workers    = 1L,
  include_qc = TRUE,
  lang       = "pt",
  overwrite  = FALSE
)

Uso básico

sus_rap_targets(
  pipeline   = pipeline,
  file_path  = "_targets.R",
  branching  = "none",
  workers    = 1L,
  include_qc = TRUE,
  lang       = "pt"
)
#> i Gerando _targets.R para 'Pipeline SINAN' (branching: none)...
#> v Pipeline targets criado: /path/to/_targets.R

O arquivo _targets.R gerado contém toda a estrutura necessária para o targets rastrear dependências e gerenciar o cache. Veja um extrato simplificado:

# _targets.R -- Generated by climasus4r::sus_rap_targets()
# Pipeline: Pipeline SINAN
# Created : 2026-06-18 10:30:00

library(targets)
library(tarchetypes)
library(climasus4r)
library(dplyr)

options(clustermq.scheduler = "sequential")

list(
  tar_target(params_uf,        c("CE", "RN", "PB", "PE", "AL")),
  tar_target(params_years,     2018:2022),
  tar_target(params_system,    "SINAN"),
  tar_target(params_time_unit, "month"),
  tar_target(params_lang,      "pt"),

  tar_target(pipeline_sinan,
    climasus4r::sus_data_import(
      uf     = params_uf,
      year   = params_years,
      system = params_system,
      lang   = params_lang
    )
  ),

  tar_target(pipeline_sinan_qc,
    climasus4r::sus_data_quality_report(pipeline_sinan)
  ),

  NULL
)

**include_qc = TRUE:** Quando ativado (padrao), `sus_rap_targets()` adiciona automaticamente um alvo de controle de qualidade (`_qc`) apos cada etapa principal. Isso registra metricas de integridade dos dados no cache sem custo adicional de execucao.

O parâmetro `overwrite`

Por padrão, overwrite = FALSE protege arquivos existentes. Se um _targets.R ja existir no caminho indicado, a funcao emite um aviso e para. Use overwrite = TRUE para substituir:

# Substituir um _targets.R existente
sus_rap_targets(
  pipeline  = pipeline,
  file_path = "_targets.R",
  overwrite = TRUE
)
#> ! Arquivo _targets.R existente sera substituido (overwrite = TRUE).
#> v Pipeline targets criado: /path/to/_targets.R

As 4 Estratégias de Branching

O parâmetro branching define como o pipeline é dividido em branches paralelos. Cada estratégia tem um caso de uso ideal:

1️⃣

"none"

Analise unica. Todos os UFs e anos processados juntos. Ideal para analises nacionais ou prototipagem rapida.

🗺️

"uf"

Um branch por estado (UF). Ideal para comparacoes inter-estaduais com cache independente por unidade federativa.

📅

"year"

Um branch por ano. Util para series temporais longas onde anos anteriores raramente mudam apos a coleta.

⚡

"cross"

Produto cartesiano UF x ano. Maximo paralelismo. Requer mais workers e espaco em disco.

Branching por UF (`"uf"`)

sus_rap_targets(
  pipeline  = pipeline,
  file_path = "_targets_uf.R",
  branching = "uf",
  workers   = 4L
)
#> i Gerando _targets.R para 'Pipeline SINAN' (branching: uf)...
#> i Estrategia: 1 branch por UF (5 UFs detectados)
#> v Pipeline targets criado: /path/to/_targets_uf.R

Com branching = "uf", o _targets.R gerado utiliza targets::tar_map() para criar um branch independente por estado. O trecho relevante do arquivo gerado se parece com:

# Extrato do _targets_uf.R gerado
list(
  tar_target(params_uf,    c("CE", "RN", "PB", "PE", "AL")),
  tar_target(params_years, 2018:2022),

  tar_map(
    values = list(uf = c("CE", "RN", "PB", "PE", "AL")),
    tar_target(pipeline_sinan,
      climasus4r::sus_data_import(
        uf     = uf,
        year   = params_years,
        system = "SINAN"
      ),
      pattern = map(params_uf)
    )
  ),

  NULL
)

Cada UF tem seu próprio cache: se os dados de "CE" mudarem, apenas o branch "CE" é re-executado. Os demais permanecem em cache.

Branching cruzado (`"cross"`)

sus_rap_targets(
  pipeline  = pipeline,
  file_path = "_targets_cross.R",
  branching = "cross",
  workers   = 8L
)
#> i Gerando _targets.R para 'Pipeline SINAN' (branching: cross)...
#> i Estrategia: produto cartesiano UF x ano (5 UFs x 5 anos = 25 branches)
#> ! Aviso: 25 branches com workers = 8 pode exigir bastante memoria RAM.
#> v Pipeline targets criado: /path/to/_targets_cross.R

**Uso de recursos com "cross":** O produto cartesiano UF x ano pode gerar muitos branches simultaneamente. Para 10 UFs e 10 anos, sao 100 branches. Monitore o uso de RAM e ajuste `workers` de acordo com os recursos disponíveis na maquina.

Comparação das estratégias

Estrategia	Branches	Quando usar	Workers recomendados
`"none"`	1	Prototipagem, analises unicas	1
`"uf"`	1 por UF	Comparacoes estaduais	n_UFs
`"year"`	1 por ano	Series longas, dados historicos	n_years
`"cross"`	UFs × anos	Paineis espaco-temporais completos	n_UFs × n_years

`sus_rap_make()` — Executar o Pipeline

A função sus_rap_make() executa o pipeline gerado com sus_rap_targets() chamando targets::tar_make() internamente, com integração ao sistema de metadados do climasus4r.

Assinatura da função

sus_rap_make(
  rap,
  workers   = 1L,
  reporter  = "verbose",
  branching = "none",
  lang      = "pt",
  ...
)

Execução básica

resultado <- sus_rap_make(
  rap      = rap,
  workers  = 1L,
  reporter = "verbose",
  lang     = "pt"
)
#> i Executando via targets::tar_make()...
#> * Target params_uf
#> * Target params_years
#> * Target params_system
#> * Target params_time_unit
#> * Target pipeline_sinan [10.3s]
#> * Target pipeline_sinan_qc [0.8s]
#> v Execucao targets concluida.

Acessando os resultados

O objeto retornado por sus_rap_make() é uma lista com três componentes:

# Acessar resultados
head(resultado$results)  # data.frame final do pipeline
resultado$store          # caminho do diretorio de cache (_targets/)
resultado$rap            # rap_object original com metadados atualizados

# Tambem pode usar a API nativa do targets
targets::tar_load(pipeline_sinan)
targets::tar_read("pipeline_sinan_qc")
targets::tar_visnetwork()  # grafo visual de dependencias

**Dica:** Para ver o grafo de dependencias do pipeline, use `targets::tar_visnetwork()` apos gerar o `_targets.R`. Isso ajuda a identificar gargalos e otimizar a ordem de execucao dos alvos.

O poder do cache: segunda execução

Na segunda execução do mesmo pipeline, o targets verifica o hash de cada alvo. Se nada mudou nas entradas, o alvo é marcado como [skipped] e carregado diretamente do cache — sem re-executar o codigo:

# Segunda execucao: apenas o que mudou e re-executado
resultado2 <- sus_rap_make(rap, workers = 1L)
#> i Executando via targets::tar_make()...
#> * Target params_uf         [skipped]
#> * Target params_years      [skipped]
#> * Target params_system     [skipped]
#> * Target params_time_unit  [skipped]
#> * Target pipeline_sinan    [skipped]  # cache valido!
#> * Target pipeline_sinan_qc [skipped]  # cache valido!
#> v Execucao targets concluida.

Isso significa que, ao alterar apenas o filtro de CID-10, apenas as etapas a partir de sus_data_filter_cid() são re-executadas. As etapas de importação e encoding permanecem em cache.

Execução com paralelismo

Para pipelines com branching = "uf" ou "cross", o paralelismo é habilitado com workers > 1. O climasus4r usa o future/furrr internamente:

# Executar com 4 workers em paralelo
resultado_paralelo <- sus_rap_make(
  rap      = rap,
  workers  = 4L,
  reporter = "verbose",
  branching = "uf",
  lang     = "pt"
)
#> i Executando via targets::tar_make() com 4 workers (future::multisession)...
#> * Target pipeline_sinan_CE [3.1s]
#> * Target pipeline_sinan_RN [2.8s]  # executando em paralelo com CE
#> * Target pipeline_sinan_PB [3.4s]
#> * Target pipeline_sinan_PE [3.0s]  # executando em paralelo com PB
#> * Target pipeline_sinan_AL [2.5s]
#> v Execucao targets concluida em 7.2s (vs ~14s sequencial).

**Controle do plano de paralelismo:** O `climasus4r` nunca define o plano `future` globalmente. Se voce ja definiu `future::plan(multisession, workers = 8)` antes de chamar `sus_rap_make()`, esse plano sera respeitado. O parametro `workers` em `sus_rap_make()` e usado apenas quando nenhum plano customizado esta ativo.

Workflow com `targets` + `renv`

Para máxima reprodutibilidade, combine o cache inteligente do targets com o gerenciamento de dependências do renv. Essa combinação garante que tanto o ambiente de pacotes quanto os resultados intermediários sejam reproduzíveis:

# 1. Inicializar renv e criar snapshot das dependencias
renv::init()
renv::snapshot()

# 2. Gerar _targets.R com estrategia de branching adequada
sus_rap_targets(
  pipeline  = pipeline,
  file_path = "_targets.R",
  branching = "uf",
  workers   = 4L
)

# 3. Executar o pipeline (usa o _targets.R gerado no passo anterior)
sus_rap_make(rap, workers = 4L)

# 4. Verificar status do pipeline a qualquer momento
targets::tar_progress()   # status de cada alvo
targets::tar_outdated()   # alvos desatualizados
targets::tar_visnetwork() # grafo interativo de dependencias

**Para projetos completos:** Use `sus_rap_template()` (RAP Tutorial 3) que cria automaticamente a estrutura do projeto com `renv`, `_targets.R`, Quarto e GitHub Actions em uma so chamada. Ideal para iniciar um projeto do zero com todas as boas praticas ja configuradas.

Estrutura recomendada de projeto

Um projeto climasus4r com targets e renv bem organizado segue esta estrutura de diretórios:

# Estrutura recomendada de um projeto climasus4r + targets
# meu_projeto_dengue/
# ├── _targets.R              # gerado por sus_rap_targets()
# ├── _targets/               # cache do targets (nao versionar no git)
# ├── renv/                   # ambiente renv
# ├── renv.lock               # snapshot das dependencias (versionar)
# ├── R/
# │   └── funcoes_aux.R       # funcoes auxiliares do projeto
# ├── data/
# │   └── dados_brutos/       # dados originais (nao versionar)
# ├── output/
# │   ├── figuras/
# │   └── tabelas/
# └── relatorio.Rmd           # relatorio final que carrega do cache

**Git e cache:** Adicione `_targets/` ao seu `.gitignore`. O cache pode ser gigabytes e nao deve ser versionado. O que deve ir para o git e o `_targets.R` (gerado por `sus_rap_targets()`) e o `renv.lock` — esses dois arquivos permitem que qualquer colaborador reproduza os resultados do zero.

Referências

Landau WM (2021). The targets R package: a dynamic Make-like function-oriented pipeline toolkit for reproducibility and high-performance computing. Journal of Open Source Software, 6(57), 2959. https://doi.org/10.21105/joss.02959
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

Navegacao: Anterior: RAP 1 - Exportar e Executar | Proximo: RAP 3 - Compartilhar e Scaffolding

climasus4r · Analise integrada saude-clima-ambiente no Brasil

Encontrou um problema ou tem sugestoes para este tutorial?

🐛 Reportar no GitHub

Gerar `_targets.R`, executar com paralelismo dinamico e monitorar com `sus_rap_targets()` e `sus_rap_make()`

Dr. Max Anjos

17 October, 2026

Introdução — Por que usar `targets`?

Funções abordadas neste tutorial

Pré-requisitos

Instalação das dependências

Ponto de partida: o objeto RAP

`sus_rap_targets()` — Gerar o `_targets.R`

Assinatura da função

Uso básico

O parâmetro `overwrite`

As 4 Estratégias de Branching

"none"

"uf"

"year"

"cross"

Branching por UF (`"uf"`)

Branching cruzado (`"cross"`)

Comparação das estratégias

`sus_rap_make()` — Executar o Pipeline

Assinatura da função

Execução básica

Acessando os resultados

O poder do cache: segunda execução

Execução com paralelismo

Workflow com `targets` + `renv`

Estrutura recomendada de projeto

Referências

Pipelines com Cache Inteligente usando targets

Gerar _targets.R, executar com paralelismo dinamico e monitorar com sus_rap_targets() e sus_rap_make()

Dr. Max Anjos

17 October, 2026

Introdução — Por que usar targets?

Funções abordadas neste tutorial

Pré-requisitos

Instalação das dependências

Ponto de partida: o objeto RAP

sus_rap_targets() — Gerar o _targets.R

Assinatura da função

Uso básico

O parâmetro overwrite

As 4 Estratégias de Branching

"none"

"uf"

"year"

"cross"

Branching por UF ("uf")

Branching cruzado ("cross")

Comparação das estratégias

sus_rap_make() — Executar o Pipeline

Assinatura da função

Execução básica

Acessando os resultados

O poder do cache: segunda execução

Execução com paralelismo

Workflow com targets + renv

Estrutura recomendada de projeto

Referências

Gerar `_targets.R`, executar com paralelismo dinamico e monitorar com `sus_rap_targets()` e `sus_rap_make()`

Introdução — Por que usar `targets`?

`sus_rap_targets()` — Gerar o `_targets.R`

O parâmetro `overwrite`

Branching por UF (`"uf"`)

Branching cruzado (`"cross"`)

`sus_rap_make()` — Executar o Pipeline

Workflow com `targets` + `renv`