pjt222/build-parameterized-report

Parametrisierten Bericht erstellen

Berichte erstellen, die Parameter akzeptieren, um mehrere angepasste Varianten aus einer einzelnen Vorlage zu generieren.

Wann verwenden

• Den gleichen Bericht fuer verschiedene Abteilungen, Regionen oder Zeitraeume generieren
• Kundenspezifische Berichte aus einer Vorlage erstellen
• Dashboards erstellen, die auf bestimmte Teilmengen filtern
• Wiederkehrende Berichte mit unterschiedlichen Eingaben automatisieren

Eingaben

• Erforderlich: Berichtsvorlage (Quarto oder R Markdown)
• Erforderlich: Parameterdefinitionen (Namen, Typen, Standardwerte)
• Optional: Liste von Parameterwerten fuer die Batch-Generierung
• Optional: Ausgabeverzeichnis fuer generierte Berichte

Vorgehensweise

Schritt 1: Parameter im YAML definieren

Fuer Quarto (report.qmd):

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

Fuer R Markdown (report.Rmd):

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

Erwartet: Der YAML-Header enthaelt einen params:-Block mit benannten Parametern, die jeweils einen Standardwert des korrekten Typs haben.

Bei Fehler: Wenn das Rendering mit "object 'params' not found" fehlschlaegt, sicherstellen, dass der params:-Block korrekt unter dem YAML-Frontmatter eingerueckt ist. Fuer Quarto muss params auf der obersten Ebene des YAML stehen, nicht unter format: verschachtelt.

Schritt 2: Parameter im Code verwenden

```{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)
```

Erwartet: Code-Chunks referenzieren Parameter ueber params$name und bedingte Chunks verwenden #| eval: !expr params$flag fuer Quarto. Inline-R-Ausdruecke wie `r params$region` rendern dynamischen Text.

Bei Fehler: Wenn params$name NULL zurueckgibt, sicherstellen, dass der Parametername exakt zwischen YAML-Definition und Code-Referenz uebereinstimmt (Gross-/Kleinschreibung beachten). Pruefen, ob Standardwerte den korrekten Typ haben.

Schritt 3: Mit benutzerdefinierten Parametern rendern

Einzelnes Rendering:

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

Erwartet: Ein einzelner Bericht wird erfolgreich mit benutzerdefinierten Parameterwerten gerendert, die die YAML-Standardwerte ueberschreiben. Die Ausgabedatei wird am angegebenen Pfad erstellt.

Bei Fehler: Wenn Quarto-Rendering fehlschlaegt, pruefen, ob quarto-CLI installiert und im PATH ist. Wenn R-Markdown-Rendering fehlschlaegt, sicherstellen, dass rmarkdown installiert ist. Parameternamen in execute_params (Quarto) oder params (R Markdown) muessen exakt mit den YAML-Definitionen uebereinstimmen.

Schritt 4: Mehrere Berichte im Batch rendern

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
  )
})

Erwartet: Eine HTML-Datei pro Region-Jahr-Kombination.

Bei Fehler: Pruefen, dass Parameternamen exakt zwischen YAML und Code uebereinstimmen. Sicherstellen, dass alle Parameterwerte gueltig sind.

Schritt 5: Parametervalidierung hinzufuegen

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

Erwartet: Der Validierungs-Code-Chunk wird zu Beginn jedes Renderings ausgefuehrt und stoppt mit einer informativen Fehlermeldung, wenn ein Parameter ausserhalb des Bereichs liegt oder den falschen Typ hat.

Bei Fehler: Wenn stopifnot() wenig hilfreiche Fehlermeldungen erzeugt, auf explizite if (!cond) stop("message")-Aufrufe umstellen fuer klarere Diagnose.

Schritt 6: Ausgabe organisieren

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

Erwartet: Ausgabedateien werden in ein datumsbezogenes Unterverzeichnis mit beschreibenden Namen geschrieben (z.B. reports/2025-06/report-europe.html).

Bei Fehler: Wenn dir.create() fehlschlaegt, pruefen, ob das uebergeordnete Verzeichnis existiert und beschreibbar ist. Unter Windows sicherstellen, dass die Pfadlaenge 260 Zeichen nicht ueberschreitet.

Validierung

• [ ] Bericht rendert mit Standardparametern
• [ ] Bericht rendert mit jedem Satz benutzerdefinierter Parameter
• [ ] Parameter werden vor der Verarbeitung validiert
• [ ] Ausgabedateien sind beschreibend benannt
• [ ] Bedingte Abschnitte rendern korrekt basierend auf Parametern
• [ ] Batch-Generierung wird fuer alle Kombinationen abgeschlossen

Haeufige Fehler

• Parameternamen-Abweichung: YAML-Namen muessen exakt mit params$name-Referenzen im Code uebereinstimmen
• Typumwandlung: YAML kann year: 2025 als Integer parsen, aber Code erwartet Character. Explizit sein.
• Bedingte Auswertung: #| eval: !expr params$flag verwenden, nicht eval = params$flag in Quarto
• Datei-Ueberschreibung: Ohne eindeutige Ausgabenamen ueberschreibt jedes Rendering das vorherige
• Speicher im Batch-Modus: Lange Batch-Laeufe koennen Speicher ansammeln. callr::r() fuer Isolation erwaegen.

Verwandte Skills

• create-quarto-report - Basis-Quarto-Dokumenteinrichtung
• generate-statistical-tables - Tabellen, die sich an Parameter anpassen
• format-apa-report - Parametrisierte akademische Berichte