R Tutorial (Teil 3): Computable Manuscripts mit Quarto

Veröffentlichungsdatum

22. April 2026

1 Wie funktioniert dieses Tutorial?

In diesem Tutorial lernen Sie Quarto kennen. Quarto ist ein Format, mit dem wir Text, Code und Ergebnisse in einem gemeinsamen Dokument zusammenführen können. Dadurch lassen sich Analysen so dokumentieren, dass sie nicht nur für uns selbst, sondern auch für andere Personen leichter nachvollziehbar werden.

Anders als im ersten Teil setzen wir hier voraus, dass Sie bereits mit R Skripten vertraut sind. Sie wissen also schon, wie man R Befehle schreibt, Objekte anlegt und Code ausführt. Das Ziel dieses Tutorials ist deshalb nicht mehr, die Grundlagen von R zu erklären, sondern zu zeigen, wie wir diese Grundlagen in einem reproduzierbaren Bericht strukturieren können.

Quarto ist besonders nützlich, wenn wir:

  • Analysen sauber dokumentieren möchten,
  • Ergebnisse direkt in Text einbauen wollen,
  • Berichte als HTML- oder PDF-Datei exportieren möchten,
  • Code, Interpretation und Output an einem Ort sammeln wollen.

In diesem Tutorial werden Sie wieder verschiedene farbige Kästen sehen:

HinweisHinweis

In den blauen Kästen finden Sie zusätzliche Hinweise zur Funktionsweise von Quarto.

TippNützlich

In den grünen Kästen finden Sie weiterführende Informationen, die Ihnen beim Arbeiten mit Quarto helfen können.

WarnungVorsicht

In den gelben Kästen weisen wir auf typische Fehlerquellen hin.

VorsichtProbieren Sie es aus!

In den orangen Kästen finden Sie kleine Übungen, die Sie selbst in RStudio durchführen sollten.

1.1 Wie benutzen Sie dieses Tutorial?

Der beste Weg, Quarto zu lernen, besteht darin, die Beispiele nicht nur zu lesen, sondern direkt selbst auszuprobieren. Öffnen Sie dazu RStudio, erstellen Sie eine neue .qmd Datei und führen Sie die gezeigten Code-Beispiele schrittweise aus.

Bitte arbeiten Sie aktiv mit. Nur so wird aus einer theoretischen Einführung ein praktisches Werkzeug.

2 Was ist Quarto?

Quarto ist ein System zur Erstellung von Dokumenten, in denen Fließtext, Code und Ausgaben bzw. Ergebnisse kombiniert werden. Die Grundidee ist Ihnen möglicherweise schon aus R Markdown bekannt (https://rmarkdown.rstudio.com/). Quarto greift diese Idee auf und entwickelt sie weiter (https://quarto.org/).

Ein Quarto-Dokument kann zum Beispiel Folgendes enthalten:

  • Überschriften und erklärenden Text,
  • R Code zur Datenanalyse,
  • Tabellen und Grafiken,
  • automatisch berechnete Ergebnisse,
  • formatierte Ausgaben als HTML oder PDF.

Der große Vorteil besteht darin, dass alles in einer einzigen Datei zusammengehalten wird.

2.1 Warum ist Quarto nützlich?

Wenn wir Analysen nur in einem R Skript durchführen, sehen wir zwar den Code, aber häufig fehlt eine gut lesbare Dokumentation der einzelnen Schritte. In Quarto können wir dagegen direkt erklären,

  • was wir tun,
  • warum wir es tun,
  • und was das Ergebnis bedeutet.

So entsteht nicht nur ausführbarer Code, sondern ein vollständiger Analysebericht.

HinweisHinweis

Quarto ist keine Alternative zu R, sondern ein Format, in dem wir unter anderem R Code einbetten können. Gerade bei Abschlussarbeiten hat sich das saubere Dokumentieren mit Quarto sehr bewährt. Zum Beispiel um zu vermeiden, dass man bei einem Blick in die Analysen nach einer 2-Wochen Schreibphase nicht mehr versteht, was man sich bei einem Code-Abschnitt gedacht hat. Selbst minimale Dokumentation mit Stichpunkten kann hier schon helfen!

3 Aufbau eines Quarto-Dokuments

Ein Quarto-Dokument besteht im Wesentlichen aus drei Teilen:

  1. einem YAML-Header am Anfang der Datei,
  2. Markdown-Text für die Struktur und Erläuterungen,
  3. Code-Chunks, in denen wir R Code ausführen.

3.1 Der YAML-Header

Ganz am Anfang einer .qmd Datei steht ein Block zwischen drei Bindestrichen ---. Dort werden Metadaten des Dokuments definiert, zum Beispiel Titel und Ausgabeformat.

Ein einfacher Header kann so aussehen:

---
title: "Mein erstes Quarto Dokument"
format: html
lang: "de"
---

(Das Format nennt sich YAML - ein rekursives Akronym für “YAML Ain’t Markup Language”.) Weitere Einstellungsmöglichkeiten können Sie in der Dokumentation nachlesen.

3.2 Markdown-Text

Den normalen Text im Dokument schreiben wir in Markdown. Markdown ist eine einfache Auszeichnungssprache, mit der sich Überschriften, Listen, Hervorhebungen und Links erzeugen lassen.

Beispiele:


Überschriften werden so formatiert...

# Heading 1
## Heading 2
### Heading 3

Fett hervorheben wird so formatiert...

**bold** 

Kursiv hervorheben wird so formatiert...

*italic*

Aufzählungen und Links werden so formatiert...

- bullet points
- [Link: R Markdown Basics](https://rmarkdown.rstudio.com/lesson-8.html)
- [Link: R Markdown Cookbook](https://bookdown.org/yihui/rmarkdown-cookbook/)

Oder nummerierte Aufzählungen:

1. Der erste Punkt
2. Der zweite
3. Und der letzte.

(Hinweis: Vor dem ersten Punkt jeder Aufzählung muss eine Leerzeile stehen)

Für eine umfassende Dokumentation siehe:

HinweisHinweis zu Überschriften

Gerade Überschriften helfen sehr Analyseskripte übersichtlich zu gestalten. Diese können auch direkt in RStudio zur Navigation genutzt werden über das Outline rechts oben oder unten links in dem Skript-Fenster.

Navigation über Outline (oben rechts)

Navigation über Chunks (unten links)

3.3 Code Chunks

Anders als bei klassischen R-Skripten schreiben wir in einem Quarto-Dokument nicht nur Code untereinander. Stattdessen wird ausführbarer Code in sogenannte Code Chunks gesetzt. Ein Chunk ist also ein abgegrenzter Bereich, in dem Quarto erkennt: Dieser Teil soll als Code ausgeführt werden. Die grundlegende Idee passt gut zu der skriptartigen Einführung in unseren Lehrmaterialien: Quarto verbindet Text, Struktur und ausführbaren Code in einem gemeinsamen Dokument.

Ein einfacher R-Chunk sieht so aus:

```{r}
x <- 1:5
mean(x)
```

Wenn das Dokument gerendert wird (dazu später mehr), führt Quarto den Code im Chunk aus und zeigt standardmäßig sowohl den Code als auch das Ergebnis an. Das sieht dann so aus:

x <- 1:5
mean(x)
[1] 3
HinweisWoran erkennt man einen Chunk?

Ein Code-Chunk beginnt mit drei Backticks und einer geschweiften Klammer, in der die Sprache angegeben wird. Für R schreiben wir also:

```{r}
# some R code
```

RStudio stellt hier jedoch ein nützliches Feature bereit, über das wir automatisch Code Chunks einfügen können. Das geht über das kleine grüne +c Symbol oben im Skript-Fenster:

Standardmäßig werden Chunks zudem farblich im Skript abgehoben.

3.4 Code und Text verbinden

Ein zentraler Vorteil von Quarto ist, dass wir Ergebnisse nicht manuell in den Text übertragen müssen. Stattdessen können wir berechnete Werte direkt im Fließtext anzeigen lassen. Das verhindert typische Fehler (z. B. falsches Abschreiben) und macht Berichte konsistent.

Inline-Code

Die einfachste Möglichkeit ist sogenannter Inline-Code. Dabei wird ein kurzer R-Code evaluiert und das Ergebnis an der Stelle in den Text geschrieben. Inline-Code beginnt mit einem einfachen backtick `, direkt (ohne Leerzeichen) ein r (um die Programmiersprache festzulegen), dann ein Leerzeichen. Dann folgt der R-Code, und wird wieder mit einem einfach backtick geschlossen.

Beispiel:

Der Mittelwert beträgt `r mean(c(1, 2, 3, 4, 5))`.

Im fertigen Dokument erscheint dann:

HinweisNach dem rendern …

Der Mittelwert beträgt 3.

Werte aus Objekten

Oft berechnen wir Werte zuerst in einem Chunk und verwenden sie dann im Text.

```{r}
x <- c(2, 4, 6, 8)
m <- mean(x)
```

Der Mittelwert der Variable beträgt `r m`.

Und im fertigen Dokument steht dann:

HinweisNach dem rendern …

Der Mittelwert der Variable beträgt 5.

Dies geht genauso mit komplexeren Objekten wie z.B. bei einer Regression:

```{r} 
model <- lm(mpg ~ wt, data = mtcars)

b <- coef(model)
p <- summary(model)$coefficients[2,4]
r2 <- summary(model)$r.squared
```
Das Modell erklärt `r round(r2, 2)*100`% der Varianz.
Der Effekt beträgt b = `r round(b, 2)` (p = `r round (p, 3)`).

4 Dokument rendern (Render)

Bisher haben wir gesehen, wie wir Text und Code in einem Quarto-Dokument kombinieren. Damit aus dieser .qmd Datei jedoch ein fertiger Bericht entsteht, müssen wir das Dokument rendern.

4.1 Was bedeutet „rendern“?

Beim Rendern passiert Folgendes:

  1. Der gesamte Code im Dokument wird von oben nach unten ausgeführt
  2. Die Ergebnisse werden automatisch in das Dokument eingefügt
  3. Aus der .qmd Datei wird eine fertige Ausgabe erzeugt (z. B. HTML oder PDF)

Das Ergebnis ist ein vollständig reproduzierbarer Bericht, der Text, Code und Output kombiniert.

Viele gängige Formate wie HTML, PDF oder Word sind dabei als Render-Output möglich. Welches Format erstellt wird bestimmen Sie im YAML-Header.

4.2 Wie rendern Sie ein Dokument?

In RStudio können Sie ein Quarto-Dokument ganz einfach rendern:

  • Klicken Sie auf den Button „Render“ oben im Skript-Fenster

4.3 Was ist der Unterschied zum „Run“-Button?

Ein häufiger Fehler ist, Rendern mit dem Ausführen einzelner Chunks zu verwechseln.

Aktion Bedeutung
Run Chunk Führt nur den aktuellen Code-Chunk in R aus
Render Führt das gesamte Dokument neu aus und erstellt die Ausgabe

Beim Rendern wird alles neu berechnet, in einem “frischen” Environment – unabhängig davon, was vorher im Workspace gespeichert war.

WarnungVorsicht

Wenn Sie nur einzelne Chunks ausführen (Run), kann es sein, dass Ihr Dokument später beim Rendern nicht funktioniert.

Warum?

  • Objekte fehlen möglicherweise
  • Reihenfolgen stimmen nicht
  • versteckte Abhängigkeiten entstehen

Deshalb gilt:
Testen Sie Ihr Dokument immer durch Rendern, nicht nur durch einzelnes Ausführen von Code.

4.4 Warum ist Rendern wichtig?

Beim Rendern wird überprüft, ob Ihr Dokument:

  • vollständig reproduzierbar ist
  • alle benötigten Objekte korrekt erzeugt
  • in der richtigen Reihenfolge funktioniert

Das ist besonders wichtig für:

  • Hausarbeiten
  • Abschlussarbeiten
  • wissenschaftliche Berichte

5 Übung: Eigenes Quarto-Dokument erstellen

Ziel dieser Aufgabe ist es, dass Sie selbst ein kleines Quarto-Dokument erstellen, strukturieren und eine einfache Analyse berichten.

Schritt 1: Neues Dokument erstellen

  • Erstellen Sie in RStudio eine neue .qmd Datei
  • Fügen Sie folgenden YAML-Header ein:
---
title: "Meine erste Analyse mit Quarto"
author: Maximiliane Musterfrau
format: html
lang: "de"
---

Schritt 2: Struktur mit Überschriften

Erstellen Sie folgende Struktur im Dokument:

# Einleitung

# Methode

# Ergebnisse

# Diskussion

Schritt 3: Daten und Analyse

Führen Sie eine einfache lineare Regression mit dem Datensatz mtcars durch:

model <- lm(mpg ~ wt, data = mtcars)
summary(model)

Call:
lm(formula = mpg ~ wt, data = mtcars)

Residuals:
    Min      1Q  Median      3Q     Max 
-4.5432 -2.3647 -0.1252  1.4096  6.8727 

Coefficients:
            Estimate Std. Error t value Pr(>|t|)    
(Intercept)  37.2851     1.8776  19.858  < 2e-16 ***
wt           -5.3445     0.5591  -9.559 1.29e-10 ***
---
Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1

Residual standard error: 3.046 on 30 degrees of freedom
Multiple R-squared:  0.7528,    Adjusted R-squared:  0.7446 
F-statistic: 91.38 on 1 and 30 DF,  p-value: 1.294e-10

Schritt 4: Ergebnisse im Text berichten

Schreiben Sie unter „Ergebnisse“ einen kurzen Text, in dem Sie:

  • den Zusammenhang beschreiben
  • den Regressionskoeffizienten berichten
  • den p-Wert angeben

Verwenden Sie Inline-Code, um die Werte automatisch einzufügen.

Schritt 5: Dokument rendern

  • Klicken Sie auf Render in RStudio
  • Prüfen Sie:
    • Wird der Code korrekt ausgeführt?
    • Werden die Zahlen im Text angezeigt?
    • Ist das Dokument übersichtlich strukturiert?

Ändern Sie im YAML-Header das Format mal zu PDF:

format: pdf

Klappt es, ein PDF zu erstellen?