Construir Informe Parametrizado

Crear informes que aceptan parámetros para generar múltiples variaciones personalizadas desde una sola plantilla.

Cuándo Usar

• Generar el mismo informe para diferentes departamentos, regiones o períodos de tiempo
• Crear informes específicos por cliente desde una plantilla
• Construir dashboards que filtren subconjuntos específicos
• Automatizar informes recurrentes con diferentes entradas

Entradas

• Requerido: Plantilla de informe (Quarto o R Markdown)
• Requerido: Definiciones de parámetros (nombres, tipos, valores por defecto)
• Opcional: Lista de valores de parámetros para generación por lotes
• Opcional: Directorio de salida para los informes generados

Procedimiento

Paso 1: Definir Parámetros en YAML

Para Quarto (

report.qmd

):

---
title: "Sales Report: `r params$region`"
params:
  region: "North America"
  year: 2025
  include_forecast: true
format:
  html:
    toc: true
---

Para R Markdown (

report.Rmd

):

---
title: "Sales Report"
params:
  region: "North America"
  year: 2025
  include_forecast: true
output: html_document
---

Esperado: El encabezado YAML contiene un bloque

params:

con parámetros nombrados, cada uno con un valor por defecto del tipo correcto.

En caso de fallo: Si el renderizado falla con "object 'params' not found", asegurar que el bloque

params:

esté correctamente indentado bajo el frontmatter YAML. Para Quarto,

params

debe estar en el nivel superior del YAML, no anidado bajo

format:

.

Paso 2: Usar Parámetros en el Código

```{r}
#| label: filter-data

data <- full_dataset |>
  filter(region == params$region, year == params$year)

nrow(data)
```

## Overview for `r params$region`

This report covers the `r params$region` region for `r params$year`.

```{r}
#| label: forecast
#| eval: !expr params$include_forecast

# This chunk only runs when include_forecast is TRUE
forecast_model <- forecast::auto.arima(data$sales)
forecast::autoplot(forecast_model)
```

Esperado: Los bloques de código referencian parámetros mediante

params$name

y los bloques condicionales usan

#| eval: !expr params$flag

para Quarto. Las expresiones R en línea como

`r params$region`

renderizan texto dinámico.

En caso de fallo: Si

params$name

devuelve NULL, verificar que el nombre del parámetro coincida exactamente entre la definición YAML y la referencia en el código (sensible a mayúsculas). Verificar que los valores por defecto sean del tipo correcto.

Paso 3: Renderizar con Parámetros Personalizados

Renderizado individual:

# Quarto
quarto::quarto_render(
  "report.qmd",
  execute_params = list(region = "Europe", year = 2025)
)

# R Markdown
rmarkdown::render(
  "report.Rmd",
  params = list(region = "Europe", year = 2025),
  output_file = "report-europe-2025.html"
)

Esperado: Un solo informe se renderiza exitosamente con valores de parámetros personalizados que anulan los valores por defecto del YAML. El archivo de salida se crea en la ruta especificada.

En caso de fallo: Si el renderizado de Quarto falla, verificar que la CLI

quarto

esté instalada y en el PATH. Si el renderizado de R Markdown falla, verificar que

rmarkdown

esté instalado. Asegurar que los nombres de parámetros en

execute_params

(Quarto) o

params

(R Markdown) coincidan exactamente con las definiciones YAML.

Paso 4: Renderizar Múltiples Informes por Lotes

regions <- c("North America", "Europe", "Asia Pacific", "Latin America")
years <- c(2024, 2025)

# Generate all combinations
combinations <- expand.grid(region = regions, year = years, stringsAsFactors = FALSE)

# Render each
purrr::pwalk(combinations, function(region, year) {
  output_name <- sprintf("report-%s-%d.html",
    tolower(gsub(" ", "-", region)), year)

  quarto::quarto_render(
    "report.qmd",
    execute_params = list(region = region, year = year),
    output_file = output_name
  )
})

Esperado: Un archivo HTML por cada combinación región-año.

En caso de fallo: Verificar que los nombres de parámetros coincidan exactamente entre YAML y código. Asegurar que todos los valores de parámetros sean válidos.

Paso 5: Agregar Validación de Parámetros

#| label: validate-params

stopifnot(
  "Region must be a valid region" = params$region %in% valid_regions,
  "Year must be numeric" = is.numeric(params$year),
  "Year must be reasonable" = params$year >= 2020 && params$year <= 2030
)

Esperado: El bloque de código de validación se ejecuta al inicio de cada renderizado y se detiene con un error informativo si algún parámetro está fuera de rango o tiene el tipo incorrecto.

En caso de fallo: Si

stopifnot()

produce mensajes de error poco útiles, cambiar a llamadas explícitas

if (!cond) stop("message")

para diagnósticos más claros.

Paso 6: Organizar la Salida

# Create output directory
output_dir <- file.path("reports", format(Sys.Date(), "%Y-%m"))
dir.create(output_dir, recursive = TRUE, showWarnings = FALSE)

# Render with output path
quarto::quarto_render(
  "report.qmd",
  execute_params = list(region = region),
  output_file = file.path(output_dir, paste0("report-", region, ".html"))
)

Esperado: Los archivos de salida se escriben en un subdirectorio con fecha y nombres descriptivos (p. ej.,

reports/2025-06/report-europe.html

).

En caso de fallo: Si

dir.create()

falla, verificar que el directorio padre exista y sea escribible. En Windows, verificar que la longitud de la ruta no exceda 260 caracteres.

Validación

• El informe se renderiza con parámetros por defecto
• El informe se renderiza con cada conjunto de parámetros personalizados
• Los parámetros se validan antes del procesamiento
• Los archivos de salida tienen nombres descriptivos
• Las secciones condicionales se renderizan correctamente según los parámetros
• La generación por lotes se completa para todas las combinaciones

Errores Comunes

• Discrepancia en nombres de parámetros: Los nombres YAML deben coincidir exactamente con las referencias

  params$name

  en el código
• Coerción de tipos: YAML puede interpretar

  year: 2025

  como entero pero el código espera carácter. Ser explícito.
• Evaluación condicional: Usar

  #| eval: !expr params$flag

  no

  eval = params$flag

  en Quarto
• Sobrescritura de archivos: Sin nombres de salida únicos, cada renderizado sobrescribe el anterior
• Memoria en modo por lotes: Las ejecuciones largas por lotes pueden acumular memoria. Considerar usar

  callr::r()

  para aislamiento.

Habilidades Relacionadas

• create-quarto-report

  - configuración básica de documentos Quarto

• generate-statistical-tables

  - tablas que se adaptan a parámetros

• format-apa-report

  - informes académicos parametrizados