Pipelines con Cache Inteligente usando targets

Introducción — ¿Por qué usar `targets`?

Los análisis epidemiológicos con datos climáticos raramente son lineales. A lo largo del ciclo de investigación, es común modificar un filtro de CID-10, cambiar la ventana de agregación climática o incluir un nuevo estado en el conjunto de datos. Sin un sistema de cache inteligente, cualquiera de estos cambios obliga a re-ejecutar todo el pipeline — incluyendo etapas costosas como la descarga del DATASUS, la estandarización de codificación y la unión espacial, que pueden tardar horas.

El paquete targets (Landau, 2021) resuelve este problema con rastreo automático de dependencias: cada etapa del pipeline es un target (objetivo), y targets solo re-ejecuta los objetivos cuyas entradas cambiaron desde la última ejecución. Los resultados intermedios quedan en cache en el directorio _targets/, listos para cargarse instantáneamente.

La función sus_rap_targets() conecta los objetos RAP de climasus4r con el ecosistema targets, generando automáticamente el archivo _targets.R con toda la estructura necesaria. La función sus_rap_make() ejecuta luego ese pipeline de forma reproducible, con soporte para paralelismo y monitoreo.

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

Funciones abordadas en este tutorial

Este tutorial cubre dos funciones exportadas de climasus4r:

Función	Descripción
`sus_rap_targets()`	Genera el archivo `_targets.R` a partir de un objeto RAP
`sus_rap_make()`	Ejecuta el pipeline vía `targets::tar_make()`

Prerrequisitos

Instalación de las dependencias

El paquete targets está listado en Suggests de climasus4r. Instálelo antes de usar las funciones de este tutorial:

# Dependencias necesarias
install.packages("targets")
install.packages("tarchetypes")  # opcional: helpers adicionales

**Paquete targets necesario:** `targets` esta listado en `Suggests` de climasus4r. Instalelo antes de usar `sus_rap_targets()` y `sus_rap_make()`. El `climasus4r` verificara automaticamente la disponibilidad del paquete al llamar estas funciones.

Punto de partida: el objeto RAP

Las funciones de este tutorial operan sobre un objeto RAP — una expresión de pipeline creada con las funciones de climasus4r. Puede obtenerlo de dos formas:

library(climasus4r)

# Opcao A: ler um RAP existente (criado con 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 el objeto RAP:** El Tutorial RAP 1 — *Exportar y Ejecutar* — explica en detalle como crear, exportar y cargar objetos RAP con `sus_rap_export()` y `sus_rap_read()`. Consultelo si necesita crear el objeto desde cero.

`sus_rap_targets()` — Generar el `_targets.R`

La función sus_rap_targets() recibe un pipeline de climasus4r y genera un archivo _targets.R listo para ejecutarse con el paquete targets.

Firma de la función

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

El archivo _targets.R generado contiene toda la estructura necesaria para que targets rastree dependencias y gestione el cache. Vea un extracto 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:** Cuando esta activado (predeterminado), `sus_rap_targets()` agrega automaticamente un objetivo de control de calidad (`_qc`) despues de cada etapa principal. Esto registra metricas de integridad de los datos en el cache sin costo adicional de ejecucion.

El parámetro `overwrite`

Por defecto, overwrite = FALSE protege archivos existentes. Si ya existe un _targets.R en la ruta indicada, la función emite una advertencia y se detiene. Use overwrite = TRUE para reemplazarlo:

# 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

Las 4 Estrategias de Branching

El parámetro branching define cómo se divide el pipeline en branches (ramas) paralelos. Cada estrategia tiene un caso de uso ideal:

1️⃣

"none"

Analisis unico. Todos los UFs y anos procesados juntos. Ideal para analisis nacionales o prototipado rapido.

🗺️

"uf"

Una rama por estado (UF). Ideal para comparaciones interestatales con cache independiente por unidad federativa.

📅

"year"

Una rama por ano. Util para series temporales largas donde los anos anteriores rara vez cambian despues de la recoleccion.

⚡

"cross"

Producto cartesiano UF x ano. Maximo paralelismo. Requiere mas workers y espacio en 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

Con branching = "uf", el _targets.R generado utiliza targets::tar_map() para crear una rama independiente por estado. El extracto relevante del archivo generado se ve así:

# 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 tiene su propio cache: si los datos de "CE" cambian, solo se re-ejecuta la rama "CE". Las demás permanecen en 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 con "cross":** El producto cartesiano UF x ano puede generar muchas ramas simultaneamente. Para 10 UFs y 10 anos, son 100 ramas. Monitoree el uso de RAM y ajuste `workers` de acuerdo con los recursos disponibles en la maquina.

Comparación de las estrategias

Estrategia	Ramas	Cuando usar	Workers recomendados
`"none"`	1	Prototipado, analisis unicos	1
`"uf"`	1 por UF	Comparaciones estatales	n_UFs
`"year"`	1 por ano	Series largas, datos historicos	n_years
`"cross"`	UFs × anos	Paneles espacio-temporales completos	n_UFs × n_years

`sus_rap_make()` — Ejecutar el Pipeline

La función sus_rap_make() ejecuta el pipeline generado con sus_rap_targets() llamando internamente a targets::tar_make(), con integración al sistema de metadatos de climasus4r.

Firma de la función

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

Ejecución 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.

Accediendo a los resultados

El objeto devuelto por sus_rap_make() es una lista con tres 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

**Consejo:** Para ver el grafo de dependencias del pipeline, use `targets::tar_visnetwork()` despues de generar el `_targets.R`. Esto ayuda a identificar cuellos de botella y optimizar el orden de ejecucion de los objetivos.

El poder del cache: segunda ejecución

En la segunda ejecución del mismo pipeline, targets verifica el hash de cada objetivo. Si nada cambió en las entradas, el objetivo se marca como [skipped] y se carga directamente desde el cache — sin re-ejecutar el código:

# 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.

Esto significa que, al alterar solo el filtro de CID-10, solo se re-ejecutan las etapas a partir de sus_data_filter_cid(). Las etapas de importación y codificación permanecen en cache.

Ejecución con paralelismo

Para pipelines con branching = "uf" o "cross", el paralelismo se habilita con workers > 1. climasus4r usa 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).

**Control del plan de paralelismo:** `climasus4r` nunca define el plan `future` globalmente. Si usted ya definio `future::plan(multisession, workers = 8)` antes de llamar `sus_rap_make()`, ese plan sera respetado. El parametro `workers` en `sus_rap_make()` se usa solo cuando ningun plan personalizado esta activo.

Workflow con `targets` + `renv`

Para máxima reproducibilidad, combine el cache inteligente de targets con la gestión de dependencias de renv. Esta combinación garantiza que tanto el entorno de paquetes como los resultados intermedios sean reproducibles:

# 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 proyectos completos:** Use `sus_rap_template()` (RAP Tutorial 3) que crea automaticamente la estructura del proyecto con `renv`, `_targets.R`, Quarto y GitHub Actions en una sola llamada. Ideal para iniciar un proyecto desde cero con todas las buenas practicas ya configuradas.

Estructura recomendada de proyecto

Un proyecto climasus4r con targets y renv bien organizado sigue esta estructura de directorios:

# 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 y cache:** Agregue `_targets/` a su `.gitignore`. El cache puede ocupar gigabytes y no debe versionarse. Lo que debe ir al git es el `_targets.R` (generado por `sus_rap_targets()`) y el `renv.lock` — estos dos archivos permiten que cualquier colaborador reproduzca los resultados desde cero.

Referencias

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

Navegación: Anterior: RAP 1 - Exportar y Ejecutar | Siguiente: RAP 3 - Compartir y Scaffolding

climasus4r · Analisis integrado salud-clima-ambiente en Brasil

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

🐛 Reportar en GitHub

Generar `_targets.R`, ejecutar con paralelismo dinamico y monitorear con `sus_rap_targets()` y `sus_rap_make()`

Dr. Max Anjos

17 October, 2026

Introducción — ¿Por qué usar `targets`?

Funciones abordadas en este tutorial

Prerrequisitos

Instalación de las dependencias

Punto de partida: el objeto RAP

`sus_rap_targets()` — Generar el `_targets.R`

Firma de la función

Uso básico

El parámetro `overwrite`

Las 4 Estrategias de Branching

"none"

"uf"

"year"

"cross"

Branching por UF (`"uf"`)

Branching cruzado (`"cross"`)

Comparación de las estrategias

`sus_rap_make()` — Ejecutar el Pipeline

Firma de la función

Ejecución básica

Accediendo a los resultados

El poder del cache: segunda ejecución

Ejecución con paralelismo

Workflow con `targets` + `renv`

Estructura recomendada de proyecto

Referencias

Pipelines con Cache Inteligente usando targets

Generar _targets.R, ejecutar con paralelismo dinamico y monitorear con sus_rap_targets() y sus_rap_make()

Dr. Max Anjos

17 October, 2026

Introducción — ¿Por qué usar targets?

Funciones abordadas en este tutorial

Prerrequisitos

Instalación de las dependencias

Punto de partida: el objeto RAP

sus_rap_targets() — Generar el _targets.R

Firma de la función

Uso básico

El parámetro overwrite

Las 4 Estrategias de Branching

"none"

"uf"

"year"

"cross"

Branching por UF ("uf")

Branching cruzado ("cross")

Comparación de las estrategias

sus_rap_make() — Ejecutar el Pipeline

Firma de la función

Ejecución básica

Accediendo a los resultados

El poder del cache: segunda ejecución

Ejecución con paralelismo

Workflow con targets + renv

Estructura recomendada de proyecto

Referencias

Generar `_targets.R`, ejecutar con paralelismo dinamico y monitorear con `sus_rap_targets()` y `sus_rap_make()`

Introducción — ¿Por qué usar `targets`?

`sus_rap_targets()` — Generar el `_targets.R`

El parámetro `overwrite`

Branching por UF (`"uf"`)

Branching cruzado (`"cross"`)

`sus_rap_make()` — Ejecutar el Pipeline

Workflow con `targets` + `renv`