22 · Reproduzierbare Berichte mit Quarto

Klinischer Aufhänger

Deine Analyse ist fertig, und sechs Monate später fragt ein Gutachter: „Kannst du zeigen, wie genau Tabelle 2 entstanden ist?" Ohne reproduzierbaren Workflow lautet die ehrliche Antwort oft: „Nicht mehr genau." Nicht nachvollziehbare Ergebnisse gefährden Folgepublikationen, Peer-Review-Entscheidungen und letztlich klinische Schlussfolgerungen, die auf deiner Arbeit beruhen.

Dieses Modul baut ein reproduzierbares Projekt von Grund auf: erst die Struktur und das Repository, dann die Datenschutz-Regeln, dann der Analyse-Code und zuletzt der Bericht, der alles zusammenführt.

1 Reproduzierbarkeit: was & warum

Was bedeutet reproduzierbar? Dieselbe Analyse, von einer anderen Person oder von dir selbst in zwei Jahren, auf demselben Datensatz, liefert bitgenau dasselbe Ergebnis.

Warum scheitert das so häufig?

Wie lösen wir es? Mit drei Prinzipien, die sich durch dieses Modul ziehen:

1. Alles Code, kein Klicken, kein Kopieren.
2. Seed setzen, Zufall muss deterministisch sein.
3. Umgebung dokumentieren, welche Pakete in welcher Version.

2 Das Projekt: Struktur und Repository

Ein Repository ist ein mit Git versioniertes Projektverzeichnis: Git speichert bei jedem git commit einen Snapshot, sodass jeder Stand später abrufbar bleibt. Modul 02 hat das eingerichtet (git init, git add, git commit) — hier geht es darum, was in dieses Repository gehört und wie es geordnet ist. Reproduzierbarkeit beginnt damit, dass alles zur Analyse Gehörende in einer klaren Struktur an einem Ort liegt.

Eine bewährte Struktur für ein klinisches Analyseprojekt:

mein-projekt/
├── README.md              # Kurzbeschreibung, Ansprechpersonen, Laufanleitung
├── .gitignore             # was Git ignorieren soll (s. Abschnitt 3)
├── _quarto.yml            # Quarto-Projektkonfiguration (s. Abschnitt 6)
├── data/
│   ├── roh/               # unveränderliche Rohdaten — nie committen!
│   └── aufbereitet/       # durch Skripte erzeugt, ggf. committen
├── code/
│   ├── 01_bereinigung.py
│   ├── 02_analyse.py
│   └── 03_modell.py
├── berichte/
│   └── bericht.qmd        # Quarto-Dokument (Text + Code)
└── ausgaben/
    ├── tabellen/
    └── figures/

Die nummerierten Skripte in code/ machen die Ausführungsreihenfolge sofort erkennbar; der Bericht in berichte/ fügt ihre Ergebnisse zu einem Dokument zusammen. Wer vier Monate nach Abgabe zurückkommt, weiß sofort, wo er anfangen muss.

3 Datenschutz-Hygiene: was nie ins Repository darf

Die wichtigste Regel: Keine Patientendaten in Git.

Erstelle eine .gitignore-Datei im Projektstamm, vor dem ersten Commit:

# Rohdaten und Dateien mit potenziellen PHI (Protected Health Information) -
# nur der Rohdaten-Ordner, NICHT alle CSVs im Projekt (data/aufbereitet/
# darf laut Projektstruktur oben committet werden)
data/roh/**
data/roh/*.csv
data/roh/*.xlsx
data/roh/*.xls
data/roh/*.sas7bdat
data/roh/*.dta

# Jupyter-Notebook-Ausgaben können Datenfragmente enthalten
.ipynb_checkpoints/

# Betriebssystem-Metadaten
.DS_Store
Thumbs.db

Zusätzliche Schutzmaßnahmen:

• Rohdaten nur auf genehmigten Servern oder verschlüsselten Laufwerken speichern.
• Pseudonymisierung vor jeder Weitergabe, auch intern.
• Aggregierte Ergebnisse (Tabellen, Grafiken ohne Einzelfälle) können in der Regel geteilt werden; prüfe aber deine Einrichtungsregeln und das Ethikvotum.

SEED = 42
import numpy as np
import pandas as pd
np.random.seed(SEED)                       # Pflicht vor jeder Zufallsoperation

cohort = pd.read_csv("https://schradern.github.io/data-science-coach/data/kohorte.csv")
sample = cohort.sample(n=50, random_state=SEED)   # eigener Seed, unabhaengig von numpy
print("Mittleres Alter:", sample["alter"].mean().round(1))

import importlib.metadata                   # Paketversionen fuers Manifest
for pkg in ["numpy", "pandas", "scikit-learn"]:
    print(pkg, importlib.metadata.version(pkg))

SEED <- 42
library(tidyverse)
set.seed(SEED)                             # vor jeder Zufallsoperation

cohort <- read_csv("https://schradern.github.io/data-science-coach/data/kohorte.csv", show_col_types = FALSE)
sample <- cohort |> slice_sample(n = 50)
cat("Mittleres Alter:", mean(sample$alter), "\n")

si <- sessionInfo()                        # Versionen fuer den Bericht
cat("R:", si$R.version$version.string, "\n")
cat("tidyverse:", as.character(packageVersion("tidyverse")), "\n")

6 Der Bericht: Quarto — aus einer Quelle

Skript und Bericht getrennt zu pflegen heißt: die Zahlen aus dem Skript per Copy-Paste in ein Word-Dokument übertragen — genau die manuelle Kette, die Reproduzierbarkeit bricht. Quarto (.qmd) legt Fließtext (Markdown) und Analyse-Code in eine Datei. quarto render führt jeden Code-Chunk aus und bettet Tabelle, Abbildung und Zahl direkt an Ort und Stelle ein.

Warum das besser ist als „Kopieren aus dem Skript":

• Tabelle und der Code, der sie erzeugt, stehen am selben Ort.
• Datensatz geändert? Einfach neu rendern, die Tabelle aktualisiert sich automatisch.
• Gutachter erhalten den Bericht inklusive Code; manuelle Übertragungsfehler entfallen.

Ein Quarto-Projekt anlegen

quarto create project default mein-bericht legt ein Projektverzeichnis mit einer _quarto.yml an. Diese Datei bündelt die Einstellungen, die für alle .qmd-Dateien des Projekts gelten — Ausgabeformat, Inhaltsverzeichnis, Ausgabeverzeichnis —, sodass einzelne Berichte nur noch ihren Titel und Inhalt tragen:

# _quarto.yml — gemeinsame Einstellungen fuer alle .qmd im Projekt
project:
  type: default
format:
  html:
    toc: true
    code-fold: true       # Code vorhanden, aber standardmaessig eingeklappt

In der Projektstruktur aus Abschnitt 2 liegt der Bericht dann unter berichte/. Ein einzelnes .qmd funktioniert aber auch ohne Projekt und ohne _quarto.yml — dann stehen alle Einstellungen im Kopf des Dokuments selbst.

Aufbau einer .qmd-Datei

Jedes Dokument beginnt mit einem YAML-Header zwischen zwei ----Zeilen; er steuert Titel, Format und Ausführung:

title: "Intensivkohorte — Kurzauswertung"
author: "Dr. med. Muster"
date: today
format: html
execute:
  echo: true              # Code im Bericht sichtbar (Transparenz!)

Darunter folgt der Bericht: normaler Markdown-Text, unterbrochen von Code-Chunks — Codeblöcken, deren Sprache in geschweiften Klammern hinter dem Code-Zaun steht ({python} oder {r}). Beim Rendern ersetzt Quarto jeden Chunk durch seine Ausgabe (Tabelle, Zahl, Abbildung). Ein vollständiges, lauffähiges Beispiel steht in code/bericht_beispiel.qmd — es lädt die Kohorte, rechnet eine Table 1 und rendert sie zu HTML. (Im Kurs liegt das Beispiel unter code/, weil jedes Modul seinen Code dort bündelt; in einem eigenen Projekt gehört der Bericht nach berichte/.)

Einrichten (einmalig)

1. Quarto-CLI installieren über quarto.org/docs/get-started — macOS: brew install quarto, Windows: winget install quarto oder der Installer. Prüfen mit quarto --version.
2. Python-Kernel bereitstellen: pip install jupyter in der Kursumgebung aus Modul 02. Quarto führt die {python}-Chunks über Jupyter aus (für {r}-Chunks stattdessen das R-Paket rmarkdown).
3. Nur für PDF: eine LaTeX-Distribution, am einfachsten quarto install tinytex.

Rendern

quarto render code/bericht_beispiel.qmd erzeugt HTML (das im YAML-Header gesetzte format). Mit --to pdf oder --to docx entstehen die anderen Formate aus derselben Quelle. quarto preview code/bericht_beispiel.qmd rendert bei jedem Speichern neu und zeigt den Bericht live im Browser — praktisch beim Schreiben.

Fallstricke und Merksätze

• Seed vergessen ist der häufigste Fehler. Setze ihn ganz oben, bevor irgendein Zufallsgenerator aufgerufen wird.
• random_state in scikit-learn und np.random.seed() sind unabhängig, beide müssen gesetzt werden, wenn beide genutzt werden.
• Relative Pfade über die lib/-Helfer statt absoluter Pfade sind Grundvoraussetzung, dass Analysen auf anderen Rechnern laufen.
• Paketversionen ändern sich still. Dokumentiere sie mit pip freeze oder sessionInfo(); noch besser: virtuelle Umgebungen mit gesperrten Versionen.
• Manuelle Schritte sind reproduzierbarer Tod. Jede Excel-Editierung, die nicht im Code steht, kann nicht nachvollzogen werden.
• echo: true im Quarto-YAML, so sieht der Leser den Code. Für Publikationsanhänge ist das Gold wert.

Selbstcheck