install.packages(c("knitr", "rmarkdown"))4 Quarto
Stellen wir uns folgende Situation vor: Für eine Hausarbeit haben wir die Daten einer Umfrage mit R ausgewertet. Wir haben Kennzahlen berechnet, ein paar Grafiken erstellt und alles per Copy & Paste in ein Word-Dokument übertragen. Zwei Tage vor der Abgabe stellt sich heraus, dass drei Fragebögen doppelt eingegeben wurden. Nun heißt es: Daten korrigieren, alle Rechnungen erneut ausführen, jede einzelne Zahl im Text suchen und ersetzen, alle Grafiken neu exportieren und wieder einfügen – und hoffen, dass wir nichts übersehen haben.
Mit Quarto wäre das kein Problem gewesen: Text, R-Code und Ergebnisse stehen dort in einer Datei. Ändern sich die Daten, genügt ein Klick und das komplette Dokument wird neu erzeugt – mit allen Zahlen, Tabellen und Grafiken.
In diesem Kapitel lernen wir
- wie ein Quarto-Dokument aufgebaut ist,
- wie wir Texte mit Markdown formatieren,
- wie wir R-Code und dessen Ergebnisse (Zahlen, Tabellen und Grafiken) einbinden und
- wie wir daraus HTML-Dokumente, PDF-Dateien und Präsentationen erzeugen.
Zum Schluss gibt es eine Übersicht über typische Fehler und wie wir sie beheben (Kapitel 4.10) sowie eine Zusammenfassung (Kapitel 4.11).
4.1 Was ist Quarto?
Quarto ist ein kostenloses Open-Source-Programm, mit dem wir aus einfachen Textdateien fertige Dokumente erzeugen. Entwickelt wird es von der Firma Posit, die auch RStudio herausgibt. Die Grundidee ist einfach: Wir schreiben eine Datei mit der Endung .qmd (für Quarto Markdown), die drei Dinge enthält:
- Angaben über das Dokument, wie zum Beispiel Titel, Autor und das gewünschte Ausgabeformat,
- Text, der mit wenigen Sonderzeichen formatiert wird (sogenanntes Markdown), und
- R-Code.
Aus dieser Datei erzeugt Quarto das fertige Dokument. Dabei wird der R-Code ausgeführt, und an seiner Stelle stehen im fertigen Dokument die Ergebnisse: Zahlen, Tabellen und Grafiken. Diesen Vorgang nennen wir Rendern.
Übrigens: Auch dieses Skript ist mit Quarto geschrieben – jedes Kapitel ist eine eigene .qmd-Datei.
Wofür eignet sich Quarto?
- Mitschriften und Übungsaufgaben: Erklärungen, R-Code und Ergebnisse stehen übersichtlich beieinander – viel lesbarer als ein reines R-Skript mit Kommentaren.
- Berichte, Hausarbeiten und Abschlussarbeiten: als HTML-, PDF- oder Word-Datei, auf Wunsch mit Inhalts-, Abbildungs- und Literaturverzeichnis.
- Präsentationen: zum Beispiel Folien, die im Browser laufen.
- Webseiten und Bücher: so wie dieses Skript.
Warum nicht einfach Word?
Natürlich können wir Berichte auch mit Word schreiben. Quarto hat aber einige entscheidende Vorteile:
- Keine Übertragungsfehler: Zahlen werden nicht abgetippt, sondern direkt von R in den Text geschrieben.
- Aktualisierung per Knopfdruck: Ändern sich die Daten, wird das Dokument einfach neu gerendert.
- Reproduzierbarkeit: Jede Zahl im Dokument lässt sich nachvollziehen, denn der Code, der sie berechnet, steht im Dokument. In der Wissenschaft – und gerade in der Psychologie – ist das ein wichtiges Qualitätsmerkmal.
- Ein Dokument, viele Formate: Aus derselben Datei entstehen bei Bedarf eine HTML-Seite, eine PDF-Datei oder ein Word-Dokument.
- Konzentration auf den Inhalt: Um das Layout, die Nummerierung von Abbildungen und Tabellen oder das Literaturverzeichnis kümmert sich Quarto.
4.1.1 Wie funktioniert Quarto?
Was beim Rendern im Hintergrund passiert, müssen wir nicht im Detail verstehen. Eine grobe Vorstellung hilft aber sehr, wenn einmal etwas nicht funktioniert. Das Rendern geschieht in zwei Schritten (siehe Abbildung 4.1):
- Zuerst führt das R-Paket knitr den R-Code des Dokuments von oben nach unten aus und schreibt Text und Ergebnisse in eine reine Textdatei im Markdown-Format (
.md). Grafiken werden dabei als Bilddateien gespeichert und eingebunden. - Danach wandelt das Programm Pandoc diese Markdown-Datei in das gewünschte Ausgabeformat um: in eine HTML-Seite, eine Präsentation, ein Word-Dokument oder – mit einem Zwischenschritt über ein Textsatzsystem wie LaTeX oder Typst – in eine PDF-Datei.
Die Zwischendateien werden anschließend automatisch gelöscht. Wir sehen also nur unsere .qmd-Datei und das fertige Dokument.
4.2 Installation und Vorbereitung
Die gute Nachricht zuerst: Quarto ist in RStudio bereits enthalten. Mit einer aktuellen Version von RStudio (siehe Kapitel 1.2) müssen wir Quarto also nicht separat installieren.
Damit R-Code in Quarto-Dokumenten ausgeführt werden kann, werden zusätzlich die R-Pakete knitr und rmarkdown benötigt. RStudio bietet deren Installation normalerweise automatisch an, sobald wir das erste Quarto-Dokument öffnen. Wir können die Pakete aber auch selbst in der Konsole installieren:
Für PDF-Dateien: LaTeX oder Typst
PDF-Dateien kann Quarto auf zwei Wegen erzeugen: mit Typst oder mit LaTeX. Typst ist bereits in Quarto enthalten, hier müssen wir also nichts installieren (Kapitel 4.8.3). Für den Weg über LaTeX benötigen wir dagegen eine LaTeX-Installation. LaTeX ist ein Textsatzsystem, das im Hintergrund aus dem Text eine sauber gesetzte PDF-Datei macht. Am einfachsten ist TinyTeX, eine schlanke LaTeX-Distribution, die fehlende Bestandteile bei Bedarf selbstständig nachinstalliert. Wir installieren sie in der Konsole mit
install.packages("tinytex")
tinytex::install_tinytex()oder alternativ im Reiter Terminal (rechts neben dem Reiter Console) mit dem Befehl
quarto install tinytexDie Installation dauert einige Minuten und muss nur einmal durchgeführt werden. Ist bereits eine andere LaTeX-Distribution installiert (zum Beispiel MiKTeX, TeX Live oder MacTeX), können wir auch diese verwenden.
Quarto zusätzlich installieren (optional)
Möchten wir Quarto auch außerhalb von RStudio nutzen (zum Beispiel im Terminal oder in einem anderen Editor wie Positron oder VS Code) oder immer die neueste Version haben, können wir Quarto zusätzlich von quarto.org herunterladen. Für Windows und macOS gibt es ein Installationsprogramm, für Linux zum Beispiel ein .deb-Paket (Debian/Ubuntu), das sich mit sudo dpkg -i quarto-*.deb installieren lässt. Ob alles funktioniert, prüfen wir anschließend im Terminal mit quarto check.
4.3 Das erste Quarto-Dokument
Genug der Vorrede – erstellen wir unser erstes Dokument! Dazu öffnen wir unser RStudio-Projekt für diesen Kurs (siehe Kapitel 3.3) und gehen wie folgt vor:
- Im Menü wählen wir File >> New File >> Quarto Document…
- Im folgenden Dialogfenster tragen wir einen Titel und unseren Namen ein. Als Format wählen wir HTML und als Engine Knitr.
- Den Haken bei Use visual markdown editor entfernen wir (warum, sehen wir in Kapitel 4.3.1).
- Nach einem Klick auf Create öffnet sich ein neues Dokument, das bereits etwas (englischen) Beispieltext enthält.
- Wir speichern die Datei mit File >> Save (Strg+S bzw. Cmd+S) unter einem sinnvollen Namen, zum Beispiel
erstes_dokument.qmd. - Zum Schluss klicken wir auf den Knopf Render oberhalb des Editors oder drücken Strg+Shift+K (Windows/Linux) bzw. Cmd+Shift+K (Mac).
Nach ein paar Sekunden erscheint das fertige Dokument im Reiter Viewer (rechts unten) oder in einem eigenen Fenster. Im Reiter Background Jobs neben der Konsole können wir verfolgen, was beim Rendern passiert – und dort erscheinen auch die Fehlermeldungen, falls etwas schiefgeht.
In unserem Projektordner liegt nun neben erstes_dokument.qmd auch die Datei erstes_dokument.html. Das ist das fertige Dokument, das sich mit jedem Browser öffnen lässt.
4.3.1 Source oder Visual?
Oben links im Editor gibt es die beiden Schalter Source und Visual:
- Im Modus Source sehen wir den reinen Text der
.qmd-Datei mit allen Formatierungszeichen. - Im Modus Visual sieht der Text ähnlich aus wie in Word: Überschriften sind groß, fetter Text ist fett, und über das Menü Insert lassen sich Tabellen, Bilder oder Literaturangaben bequem einfügen.
Beide Modi bearbeiten dieselbe Datei, ein Hin- und Herschalten ist also jederzeit möglich. Zum Lernen verwenden wir den Modus Source: Nur so sehen wir, was wirklich in der Datei steht – und nur so finden wir Fehler. Später, zum Beispiel beim Schreiben längerer Texte, kann der Visual-Modus sehr praktisch sein.
4.3.2 Aufbau eines Quarto-Dokuments
Schauen wir uns nun ein kleines, aber vollständiges Beispiel an: einen kurzen Bericht über die Pinguine aus dem Paket palmerpenguins, die wir bereits aus den vorherigen Kapiteln kennen.
---
title: "Pinguine im Palmer-Archipel"
author: "Max Mustermann"
date: today
lang: de
format: html
---
```{r}
#| message: false
library(pacman)
p_load(tidyverse, palmerpenguins)
```
# Einleitung
Der Datensatz `penguins` enthält Messungen von
`r nrow(penguins)` Pinguinen aus drei verschiedenen Arten.
# Ergebnisse
Schwerere Pinguine haben längere Flossen:
```{r}
#| warning: false
penguins |>
ggplot(aes(x = flipper_length_mm, y = body_mass_g, color = species)) +
geom_point()
```Ein Quarto-Dokument besteht also aus drei Bausteinen:
- Dem YAML-Header ganz oben zwischen den beiden Zeilen
---. Er enthält Angaben über das Dokument wie Titel, Autor, Datum und Ausgabeformat (Kapitel 4.4). - Dem Text, der in Markdown geschrieben wird. Die Raute
#macht eine Zeile zur Überschrift, zwei Sternchen**machen Text fett und so weiter (Kapitel 4.5). - Den Code-Chunks, die mit
```{r}beginnen und mit```enden. Der Code darin wird beim Rendern ausgeführt (Kapitel 4.6). R-Code kann aber auch direkt im Text stehen: Der Ausdruck`r nrow(penguins)`wird beim Rendern durch die Anzahl der Pinguine ersetzt.
In den folgenden Abschnitten schauen wir uns diese Bausteine der Reihe nach genauer an.
4.4 Der YAML-Header
Der YAML-Header steht ganz am Anfang des Dokuments zwischen zwei Zeilen mit je drei Bindestrichen ---. Er enthält Angaben über das Dokument (sogenannte Metadaten) wie Titel und Autor sowie Einstellungen, zum Beispiel das Ausgabeformat. YAML ist ein einfaches Format, um solche Informationen übersichtlich aufzuschreiben.
4.4.1 Die Regeln
YAML kommt mit wenigen Regeln aus, die wir aber genau einhalten müssen:
- Jede Angabe hat die Form
schlüssel: wert. Nach dem Doppelpunkt steht immer ein Leerzeichen. - Untergeordnete Angaben werden mit Leerzeichen eingerückt, üblich sind zwei Leerzeichen pro Ebene (niemals Tabulatoren). Die Einrückung legt fest, was wozu gehört – ähnlich wie bei einer Gliederung.
- Texte, die Sonderzeichen wie einen Doppelpunkt enthalten, setzen wir in Anführungszeichen:
title: "Statistik: Eine Einführung". Im Zweifel schadet es nie, Texte in Anführungszeichen zu setzen. - Alles hinter einer Raute
#ist ein Kommentar und wird ignoriert.
4.4.2 Ein einfacher YAML-Header
---
title: "Mein erster Bericht"
subtitle: "Eine kleine Demonstration"
author: "Max Mustermann"
date: today # das Datum des Renderns
lang: de # Sprache des Dokuments: Deutsch
format: html # Ausgabeformat
---Die meisten Einträge erklären sich von selbst. Zwei verdienen einen zweiten Blick:
-
date: todaysetzt beim Rendern automatisch das aktuelle Datum ein. Natürlich können wir auch ein festes Datum angeben, zum Beispieldate: "2026-10-01". Wie das Datum angezeigt wird, lässt sich mitdate-formateinstellen, etwadate-format: "DD.MM.YYYY". -
lang: desorgt dafür, dass alle automatisch erzeugten Texte auf Deutsch erscheinen: „Abbildung“ statt „Figure“, „Inhaltsverzeichnis“ statt „Table of contents“ und so weiter. In PDF-Dateien wird außerdem die deutsche Silbentrennung verwendet.
4.4.3 Optionen für das Ausgabeformat
Die meisten Einstellungen beziehen sich auf das Ausgabeformat. Sie werden unter dem Format eingerückt:
---
title: "Mein erster Bericht"
author: "Max Mustermann"
date: today
lang: de
format:
html:
toc: true # Inhaltsverzeichnis
number-sections: true # Abschnitte nummerieren
---Wichtig ist der Unterschied zum vorherigen Beispiel: Solange es keine weiteren Optionen gibt, genügt format: html in einer Zeile. Sobald Optionen hinzukommen, steht html: in einer eigenen Zeile (mit Doppelpunkt!), und die Optionen werden darunter eingerückt. Die Struktur ist also format → html → toc. Welche Optionen es für die einzelnen Formate gibt, sehen wir in Kapitel 4.8.
Beispiel: Mehrere Autorinnen und Autoren
Bei einer Gruppenarbeit gibt es mehrere Autorinnen und Autoren. Diese werden als Liste angegeben, wobei jeder Eintrag der Liste mit einem Bindestrich beginnt:
author:
- name: "Max Mustermann"
affiliation: "Technische Hochschule Augsburg"
- name: "Erika Musterfrau"
affiliation: "Technische Hochschule Augsburg"4.5 Texte schreiben mit Markdown
Nach dem YAML-Header folgt der eigentliche Inhalt des Dokuments. Texte werden in Markdown geschrieben, einer sehr einfachen Auszeichnungssprache: Statt wie in Word auf Knöpfe zu drücken, formatieren wir den Text mit ein paar Sonderzeichen. Zwei Sternchen um ein Wort machen es fett, eine Raute am Zeilenanfang macht die Zeile zur Überschrift. Der große Vorteil: Der Text bleibt auch ohne Rendern gut lesbar.
Im Folgenden sind die wichtigsten Elemente zusammengestellt. Eine vollständige Übersicht gibt es in der Quarto-Dokumentation.
4.5.1 Absätze
Absätze werden durch eine Leerzeile getrennt. Ein einfacher Zeilenumbruch im Editor wird dagegen ignoriert: Die Zeilen werden beim Rendern zu einem Absatz zusammengefügt. Wir können also ruhig nach jedem Satz eine neue Zeile beginnen, das macht den Text im Editor sogar übersichtlicher.
Das ist der erste Satz des ersten Absatzes.
Dieser Satz gehört noch zum ersten Absatz.
Mit einer Leerzeile beginnt ein neuer Absatz.Text, der nicht im fertigen Dokument erscheinen soll, zum Beispiel eine Notiz an uns selbst, schreiben wir zwischen <!-- und -->.
4.5.2 Texthervorhebungen
| Markdown | Ergebnis |
|---|---|
*kursiv* |
kursiv |
**fett** |
fett |
***fett und kursiv*** |
fett und kursiv |
~~durchgestrichen~~ |
|
x^2^ |
x2 |
H~2~O |
H2O |
`Code` |
Code |
[Quarto](https://quarto.org) |
Quarto |
4.5.3 Überschriften
Überschriften beginnen mit einer oder mehreren Rauten #. Die Anzahl der Rauten bestimmt die Ebene:
# Überschrift der Ebene 1
## Überschrift der Ebene 2
### Überschrift der Ebene 3Dabei ist Folgendes zu beachten:
- Nach den Rauten folgt ein Leerzeichen, und vor der Überschrift steht eine Leerzeile.
- Der Titel des Dokuments steht bereits im YAML-Header. Die Kapitel eines Berichts beginnen daher mit
#, die Unterkapitel mit##und so weiter. - Soll eine Überschrift nicht nummeriert werden, zum Beispiel beim Literaturverzeichnis, schreiben wir
{.unnumbered}dahinter:# Literatur {.unnumbered}.
4.5.4 Listen
Aufzählungen beginnen mit einem Bindestrich - (oder einem Sternchen *), nummerierte Listen mit einer Zahl und einem Punkt. Unterpunkte werden eingerückt – vier Leerzeichen pro Ebene funktionieren immer. In den folgenden Beispielen steht links der Markdown-Text und rechts das Ergebnis.
- Äpfel
- Birnen
- Williams Christ
- Gute Luise
- Kirschen- Äpfel
- Birnen
- Williams Christ
- Gute Luise
- Kirschen
1. Daten einlesen
2. Daten bereinigen
3. Daten auswerten
- Kennzahlen berechnen
- Grafiken erstellen- Daten einlesen
- Daten bereinigen
- Daten auswerten
- Kennzahlen berechnen
- Grafiken erstellen
Bei nummerierten Listen zählt Quarto übrigens selbst: Auch wenn jede Zeile mit 1. beginnt, entsteht die Nummerierung 1, 2, 3. Für To-do-Listen in einer Mitschrift gibt es außerdem Checklisten, deren Punkte mit - [ ] (offen) bzw. - [x] (erledigt) beginnen.
4.5.5 Links, Bilder und Fußnoten
Mehr Informationen gibt es auf der [Webseite von Quarto](https://quarto.org).
{width="40%"}
Dieser Satz hat eine Fußnote.^[Und das ist die Fußnote.]- Bei Links steht der angezeigte Text in eckigen Klammern und die Adresse in runden Klammern.
-
Bilder werden genauso eingebunden, nur mit einem Ausrufezeichen davor. Der Text in den eckigen Klammern wird zur Bildunterschrift, in den geschweiften Klammern können wir zum Beispiel die Breite angeben. Der Pfad bezieht sich auf den Ordner, in dem die
.qmd-Datei liegt – im Beispiel liegt das Bild also im Unterordnerbilder. - Fußnoten werden automatisch nummeriert. In einer PDF-Datei stehen sie unten auf der Seite, in einer HTML-Datei in der Regel am Ende des Dokuments.1
4.5.6 Tabellen
Einfache Tabellen können wir direkt in Markdown schreiben:
| Art | Anzahl | Insel |
|:----------|-------:|:-------------------------|
| Adelie | 152 | Biscoe, Dream, Torgersen |
| Chinstrap | 68 | Dream |
| Gentoo | 124 | Biscoe |
: Die Pinguinarten im Datensatz penguins. {#tbl-arten}Das ergibt Tabelle 4.2:
| Art | Anzahl | Insel |
|---|---|---|
| Adelie | 152 | Biscoe, Dream, Torgersen |
| Chinstrap | 68 | Dream |
| Gentoo | 124 | Biscoe |
Die Spalten werden durch senkrechte Striche | getrennt, die zweite Zeile trennt die Überschriften vom Rest der Tabelle. Mit den Doppelpunkten legen wir die Ausrichtung fest: :--- bedeutet linksbündig, ---: rechtsbündig und :---: zentriert. Die Striche müssen nicht genau untereinander stehen, so ist es aber übersichtlicher. Die Zeile unter der Tabelle, die mit einem Doppelpunkt beginnt, ist die Tabellenüberschrift; {#tbl-...} gibt der Tabelle einen Namen, über den wir im Text auf sie verweisen können (Kapitel 4.9.1).
Tabellen von Hand zu schreiben ist allerdings mühsam – und die Zahlen in Tabelle 4.2 sind abgetippt, also genau das, was wir mit Quarto eigentlich vermeiden wollen. Tabellen, deren Inhalt aus Daten berechnet wird, erzeugen wir daher besser mit R (Kapitel 4.6.4).
4.5.7 Mathematische Formeln
In der Statistik geht es nicht ohne Formeln. Diese schreiben wir in Quarto in LaTeX-Schreibweise: Formeln im Fließtext stehen zwischen einfachen Dollarzeichen, abgesetzte Formeln zwischen doppelten Dollarzeichen.
Der Mittelwert $\bar{x}$ von $n$ Beobachtungen $x_1, \ldots, x_n$ ist
$$
\bar{x} = \frac{1}{n} \sum_{i=1}^{n} x_i .
$$Das ergibt:
Der Mittelwert \bar{x} von n Beobachtungen x_1, \ldots, x_n ist \bar{x} = \frac{1}{n} \sum_{i=1}^{n} x_i .
Tabelle 4.3 zeigt einige häufig benötigte Befehle. Eine umfangreiche Übersicht bietet zum Beispiel die Wikipedia-Seite Hilfe:TeX.
| LaTeX | Ergebnis |
|---|---|
x^2, x_i, x_{ij}
|
x^2, x_i, x_{ij} |
\frac{a}{b} |
\frac{a}{b} |
\sqrt{x} |
\sqrt{x} |
\bar{x}, \hat{\mu}
|
\bar{x}, \hat{\mu} |
\sum_{i=1}^{n} x_i |
\sum_{i=1}^{n} x_i |
\mu, \sigma, \alpha, \chi^2
|
\mu, \sigma, \alpha, \chi^2 |
\cdot, \leq, \geq, \neq, \approx
|
\cdot, \leq, \geq, \neq, \approx |
4.5.8 Callouts
Sicher sind uns in diesem Skript schon die farbigen Kästen aufgefallen, zum Beispiel für Aufgaben, Lösungen und Tipps. Solche Kästen heißen in Quarto Callouts:
::: {.callout-tip title="Tipp: Regelmäßig speichern"}
Am besten speichern wir unsere Datei regelmäßig mit Strg+S bzw. Cmd+S.
:::Das ergibt:
Es gibt fünf Arten von Callouts, die sich in Farbe und Symbol unterscheiden: callout-note, callout-tip, callout-important, callout-warning und callout-caution. Mit collapse="true" wird der Inhalt zunächst eingeklappt und erst per Klick sichtbar. So sind zum Beispiel die Lösungen in diesem Skript versteckt:
::: {.callout-caution collapse="true" title="Lösung"}
Hier steht die Lösung.
:::4.6 R-Code einbinden
Jetzt wird es spannend: Wir binden R-Code in unser Dokument ein. Dafür gibt es zwei Möglichkeiten – Code-Chunks für längeren Code und Inline-Code für einzelne Zahlen im Text.
4.6.1 Code-Chunks
R-Code steht in sogenannten Code-Chunks (engl. chunk: Stück, Brocken). Ein Chunk beginnt mit drei Backticks und {r} und endet mit drei Backticks:
```{r}
summary(penguins$body_mass_g)
```Beim Rendern wird der Code ausgeführt. Im fertigen Dokument erscheinen dann der Code und direkt darunter sein Ergebnis.
Einen neuen Chunk fügen wir am einfachsten über Code >> Insert Chunk ein, mit der Tastenkombination Strg+Alt+I (Windows/Linux) bzw. Cmd+Option+I (Mac) oder über das grüne Symbol +C oben rechts in der Editorleiste. Und falls wir die Backticks lieber selbst tippen: Auf einer deutschen Tastatur entsteht ein Backtick mit Shift und der Taste rechts neben dem ß, gefolgt von der Leertaste.
Pakete und Daten gehören in den ersten Chunk
Es ist üblich, im ersten Chunk eines Dokuments alle benötigten Pakete zu laden und gegebenenfalls Daten einzulesen. Für dieses Kapitel sieht der erste Chunk so aus:
```{r}
#| message: false
library(pacman)
p_load(tidyverse, palmerpenguins)
```Die Zeile #| message: false ist eine sogenannte Chunk-Option. Sie sorgt dafür, dass die Meldungen, die beim Laden mancher Pakete erscheinen, nicht im Dokument landen. Chunk-Optionen schauen wir uns in Kapitel 4.6.2 genauer an.
Danach stehen die Pakete in allen folgenden Chunks zur Verfügung:
```{r}
penguins |>
count(species)
```# A tibble: 3 × 2
species n
<fct> <int>
1 Adelie 152
2 Chinstrap 68
3 Gentoo 124Chunks interaktiv ausführen
Während wir an einem Dokument arbeiten, möchten wir Code natürlich ausprobieren, ohne jedes Mal das ganze Dokument zu rendern. Dafür gibt es oben rechts an jedem Chunk kleine Symbole:
- Der grüne Pfeil führt den aktuellen Chunk aus (Strg+Shift+Enter bzw. Cmd+Shift+Return).
- Das Symbol links daneben führt alle Chunks oberhalb des aktuellen Chunks aus.
Das Ergebnis erscheint direkt unter dem Chunk im Editor. Einzelne Zeilen führen wir wie in einem R-Skript mit Strg+Enter bzw. Cmd+Return aus (siehe Kapitel 3.1.2).
4.6.2 Chunk-Optionen
Mit Chunk-Optionen steuern wir, was von einem Chunk im fertigen Dokument zu sehen ist: der Code, das Ergebnis, beides oder gar nichts. Außerdem können wir Grafiken beschriften, ihre Größe festlegen und vieles mehr. Chunk-Optionen stehen am Anfang des Chunks in Zeilen, die mit #| beginnen. Sie werden – genau wie im YAML-Header – in der Form option: wert geschrieben; Wahrheitswerte schreiben wir dabei klein (true bzw. false). Tabelle 4.4 zeigt die wichtigsten Optionen.
| Option | Bedeutung | Standard |
|---|---|---|
echo |
Code anzeigen | true |
eval |
Code ausführen | true |
output |
Ergebnis anzeigen | true |
include |
Code und Ergebnis anzeigen; bei false wird der Code zwar ausgeführt, aber nichts angezeigt |
true |
warning |
Warnungen anzeigen | true |
message |
Meldungen anzeigen, z.B. beim Laden von Paketen | true |
error |
Fehlermeldungen anzeigen und trotzdem weiterrendern | false |
label |
Name des Chunks, z.B. für Querverweise | – |
fig-cap |
Bildunterschrift einer Grafik | – |
fig-width, fig-height
|
Breite und Höhe einer Grafik in Zoll (1 Zoll = 2,54 cm) | je nach Format |
fig-align |
Ausrichtung einer Grafik (left, center oder right) |
– |
out-width |
Anzeigebreite einer Grafik, z.B. "70%"
|
– |
tbl-cap |
Überschrift einer Tabelle | – |
Code, Ergebnis oder beides?
Die vier Optionen echo, eval, output und include werden gerne verwechselt. Tabelle 4.5 zeigt, was sie jeweils bewirken und wofür wir sie typischerweise brauchen.
| Option | Code sichtbar | Code ausgeführt | Ergebnis sichtbar | typische Verwendung |
|---|---|---|---|---|
| (keine) | ja | ja | ja | Mitschriften, Übungsaufgaben |
echo: false |
nein | ja | ja | Berichte, bei denen nur die Ergebnisse interessieren |
output: false |
ja | ja | nein | Code zeigen, dessen Ausgabe nicht interessiert |
eval: false |
ja | nein | – | Code zeigen, der nicht ausgeführt werden soll, z.B. install.packages()
|
include: false |
nein | ja | nein | Pakete laden, Daten einlesen, Hilfsrechnungen |
Beispiel: Eine Grafik mit Beschriftung
Im folgenden Chunk werden mehrere Optionen kombiniert: Die Warnung über fehlende Werte wird unterdrückt, und die Grafik bekommt eine bestimmte Größe, einen Namen (label) und eine Bildunterschrift (fig-cap).
```{r}
#| label: fig-RQuarto-Pinguine
#| fig-cap: "Flossenlänge und Körpergewicht der Pinguine, getrennt nach Art."
#| warning: false
#| fig-width: 7
#| fig-height: 4
penguins |>
ggplot(aes(x = flipper_length_mm, y = body_mass_g, color = species)) +
geom_point() +
labs(x = "Flossenlänge (mm)", y = "Körpergewicht (g)", color = "Art")
```
Da das Label mit fig- beginnt, wird die Grafik automatisch nummeriert, und wir können im Text auf sie verweisen: Schreiben wir @fig-RQuarto-Pinguine, so erscheint im Dokument „Abbildung 4.2“. Wie das genau funktioniert, sehen wir in Kapitel 4.9.1.
Optionen für alle Chunks
Soll eine Option für alle Chunks eines Dokuments gelten, schreiben wir sie in den YAML-Header unter execute:. Einzelne Chunks können diese Einstellung mit einer eigenen Chunk-Option wieder überschreiben.
execute:
echo: false # Code in keinem Chunk anzeigen
warning: false # keine Warnungen anzeigen4.6.3 Inline-Code: Ergebnisse im Text
Aus Word kennen wir vielleicht Serienbriefe: einen Brieftext mit Platzhaltern, die automatisch mit Namen und Adressen gefüllt werden. Inline-Code funktioniert ganz ähnlich. Wir schreiben einen kurzen R-Ausdruck direkt in den Text, und beim Rendern wird er durch sein Ergebnis ersetzt. Inline-Code beginnt mit einem Backtick, gefolgt von einem r und einem Leerzeichen; dann folgt der R-Ausdruck und zum Schluss wieder ein Backtick, also zum Beispiel `r nrow(penguins)`.
Beispiel
Zuerst berechnen wir in einem Chunk die benötigten Werte:
```{r}
anzahl <- nrow(penguins)
gewicht <- mean(penguins$body_mass_g, na.rm = TRUE)
```Im Text schreiben wir dann:
Der Datensatz enthält `r anzahl` Pinguine, die im Mittel
`r round(gewicht)` Gramm wiegen.Im fertigen Dokument steht an dieser Stelle:
Der Datensatz enthält 344 Pinguine, die im Mittel 4202 Gramm wiegen.
Keine dieser Zahlen wurde abgetippt! Ändern sich die Daten, stehen nach dem nächsten Rendern automatisch die richtigen Zahlen im Text.
Zahlen mit Dezimalkomma
R verwendet – wie im Englischen üblich – den Punkt als Dezimaltrenner. In einem deutschen Text wirkt „4201.8 Gramm“ aber seltsam. Mit der Funktion format() lässt sich das ändern. Damit wir das nicht jedes Mal ausschreiben müssen, lohnt sich eine kleine Hilfsfunktion, die wir am besten im ersten Chunk des Dokuments definieren:
```{r}
komma <- function(x, stellen = 1) {
format(round(x, stellen), nsmall = stellen, big.mark = ".", decimal.mark = ",")
}
komma(gewicht)
```[1] "4.201,8"Aus `r komma(gewicht)` wird im Text dann „4.201,8 Gramm“.
4.6.4 Tabellen aus R
Geben wir in einem Chunk eine Datentabelle aus, erscheint sie im Dokument genau so wie in der Konsole. Für eine Mitschrift ist das in Ordnung, für einen Bericht eher nicht. Schöner wird es mit der Funktion kable() aus dem Paket knitr, die aus einer Datentabelle eine richtige Tabelle macht:
```{r}
#| label: tbl-RQuarto-Pinguine
#| tbl-cap: "Anzahl, mittleres Körpergewicht und mittlere Flossenlänge der Pinguine nach Art."
penguins |>
group_by(species) |>
summarise(anzahl = n(),
gewicht = mean(body_mass_g, na.rm = TRUE),
flosse = mean(flipper_length_mm, na.rm = TRUE)) |>
knitr::kable(digits = 1,
col.names = c("Art", "Anzahl", "Gewicht (g)", "Flossenlänge (mm)"),
format.args = list(big.mark = ".", decimal.mark = ","))
```| Art | Anzahl | Gewicht (g) | Flossenlänge (mm) |
|---|---|---|---|
| Adelie | 152 | 3.700,7 | 190,0 |
| Chinstrap | 68 | 3.733,1 | 195,8 |
| Gentoo | 124 | 5.076,0 | 217,2 |
Dabei rundet digits = 1 auf eine Nachkommastelle, col.names legt die Spaltenüberschriften fest und format.args sorgt für das deutsche Zahlenformat. Wie bei Grafiken bekommt die Tabelle über label und tbl-cap eine Nummer und eine Überschrift, sodass wir im Text auf Tabelle 4.6 verweisen können.
4.7 Rendern
Das Rendern haben wir schon kennengelernt: Ein Klick auf Render (oder Strg+Shift+K bzw. Cmd+Shift+K) speichert die Datei und erzeugt das Dokument. Das fertige Dokument landet im selben Ordner wie die .qmd-Datei und hat denselben Namen, nur eine andere Endung.
4.7.1 Interaktiv ausführen oder rendern?
Beim Arbeiten mit Quarto gibt es also zwei Arten, R-Code auszuführen, und es ist wichtig, den Unterschied zu kennen:
| Chunk ausführen (grüner Pfeil) | Rendern (Knopf Render) | |
|---|---|---|
| R-Sitzung | die aktuelle Sitzung (wie die Konsole) | eine neue, leere Sitzung |
| kennt Objekte aus der Konsole | ja | nein |
| Ergebnis | Ausgabe im Editor | das fertige Dokument |
| wofür? | Ausprobieren und Entwickeln | Dokument erzeugen |
Daraus entsteht der wohl häufigste Anfängerfehler: Beim interaktiven Ausführen funktioniert alles, aber beim Rendern bricht Quarto mit einer Fehlermeldung wie Objekt 'daten' nicht gefunden ab. Die Ursache ist fast immer ein Objekt oder Paket, das nur in der Konsole existiert, im Dokument aber nicht erzeugt bzw. geladen wird (siehe auch den Kasten in Kapitel 4.1.1).
4.7.2 Rendern ohne Render-Knopf
Den Render-Knopf gibt es nur in RStudio. Wir können aber auch in der Konsole rendern, wofür wir das Paket quarto benötigen:
install.packages("quarto") # nur einmal nötig
quarto::quarto_render("bericht.qmd")Im Terminal lautet der entsprechende Befehl
quarto render bericht.qmdMit quarto preview bericht.qmd erhalten wir außerdem eine Vorschau im Browser, die sich bei jedem Speichern automatisch aktualisiert.
4.8 Ausgabeformate
Das Ausgabeformat legen wir im YAML-Header mit format: fest. Die wichtigsten Formate für uns sind html, pdf bzw. typst (beide erzeugen PDF-Dateien) und revealjs. Daneben gibt es viele weitere, zum Beispiel docx für Word-Dokumente.
4.8.1 HTML
HTML ist das Standardformat. Es ist schnell erzeugt, braucht keine zusätzliche Software, sieht auf jedem Bildschirm gut aus und kann interaktive Elemente enthalten. Für Mitschriften, Übungsaufgaben und Berichte, die am Bildschirm gelesen werden, ist es die erste Wahl. Hier ein YAML-Header mit einigen nützlichen Optionen:
---
title: "Übung 3: Deskriptive Statistik"
author: "Max Mustermann"
date: today
lang: de
format:
html:
toc: true # Inhaltsverzeichnis
number-sections: true # Abschnitte nummerieren
code-fold: true # Code eingeklappt, per Klick sichtbar
df-print: paged # Datentabellen zum Durchblättern
theme: cosmo # Farbschema
embed-resources: true # alles in eine einzige HTML-Datei packen
---Für das Farbschema (theme) stehen rund 25 fertige Designs zur Verfügung, zum Beispiel cosmo, flatly, journal oder darkly. Eine Übersicht gibt es in der Quarto-Dokumentation.
4.8.2 PDF mit LaTeX
Für Hausarbeiten und alles, was ausgedruckt oder als festes Dokument abgegeben wird, ist PDF das richtige Format. Mit format: pdf erzeugt Quarto die PDF-Datei über LaTeX, daher muss wie in Kapitel 4.2 beschrieben TinyTeX (oder eine andere LaTeX-Distribution) installiert sein. Das erste Rendern kann eine Weile dauern, da fehlende LaTeX-Pakete automatisch aus dem Internet nachgeladen werden. Ganz ohne LaTeX kommen wir mit Typst aus, siehe Kapitel 4.8.3.
Ein YAML-Header für eine Hausarbeit könnte zum Beispiel so aussehen:
---
title: "Hausarbeit Statistik"
subtitle: "Eine Auswertung des Datensatzes penguins"
author: "Max Mustermann"
date: today
lang: de
format:
pdf:
toc: true # Inhaltsverzeichnis
number-sections: true # Abschnitte nummerieren
papersize: a4 # Papierformat DIN A4
geometry: margin=2.5cm # Seitenränder
fontsize: 11pt # Schriftgröße
linestretch: 1.5 # Zeilenabstand
lof: true # Abbildungsverzeichnis
lot: true # Tabellenverzeichnis
fig-pos: "H" # Abbildungen genau an diese Stelle setzen
---Im Vergleich zu HTML gibt es zwei wichtige Unterschiede:
- Interaktive Elemente wie eingeklappter Code (
code-fold) oder blätterbare Tabellen gibt es in einer PDF-Datei nicht; die entsprechenden Optionen werden ignoriert. - LaTeX setzt Abbildungen gerne an eine Stelle, an der sie typografisch gut passen – und das ist nicht unbedingt die Stelle, an der sie im Text stehen. Wollen wir das verhindern, hilft die Option
fig-pos: "H"wie im Beispiel oben.
4.8.3 PDF mit Typst
Quarto kann PDF-Dateien auch ganz ohne LaTeX erzeugen, nämlich mit Typst. Typst ist ein modernes Textsatzsystem, das als einfachere und schnellere Alternative zu LaTeX entwickelt wurde. Für uns hat es zwei große Vorteile:
- Keine Installation: Typst ist bereits in Quarto enthalten. Wir müssen also weder TinyTeX noch eine andere LaTeX-Distribution installieren.
- Schnell: Die PDF-Datei ist meist in wenigen Sekunden fertig.
Um Typst zu verwenden, schreiben wir im YAML-Header typst statt pdf. Dabei gibt es eine wichtige Besonderheit: Ohne weitere Angaben verwendet Typst das US-amerikanische Papierformat Letter. Für DIN A4 geben wir deshalb papersize: a4 an. Ein kleines, vollständiges Beispiel:
---
title: "Pinguine im Palmer-Archipel"
author: "Max Mustermann"
date: today
lang: de
format:
typst:
papersize: a4 # Papierformat DIN A4
margin:
x: 2.5cm # Seitenränder links und rechts
y: 2.5cm # Seitenränder oben und unten
fontsize: 11pt # Schriftgröße
toc: true # Inhaltsverzeichnis
number-sections: true # Abschnitte nummerieren
---
```{r}
#| include: false
library(pacman)
p_load(tidyverse, palmerpenguins)
```
# Einleitung
Der Datensatz `penguins` enthält Messungen von
`r nrow(penguins)` Pinguinen. @fig-flossen zeigt den Zusammenhang
zwischen Flossenlänge und Körpergewicht.
```{r}
#| label: fig-flossen
#| fig-cap: "Flossenlänge und Körpergewicht der Pinguine."
#| echo: false
#| warning: false
penguins |>
ggplot(aes(x = flipper_length_mm, y = body_mass_g, color = species)) +
geom_point()
```Nach dem Rendern liegt neben der .qmd-Datei eine PDF-Datei mit demselben Namen. Neu gegenüber dem LaTeX-Beispiel aus Kapitel 4.8.2 sind vor allem die Seitenränder: Bei Typst legen wir sie mit margin fest, wobei x für die Ränder links und rechts und y für die Ränder oben und unten steht. Einzelne Ränder lassen sich auch mit top, bottom, left und right angeben. Ohne Angabe sind die Ränder 1,25 Zoll (gut 3 cm) breit.
Was wir in diesem Kapitel kennengelernt haben – Überschriften, Listen, Formeln, Tabellen, Callouts, Querverweise und Literaturangaben –, funktioniert auch mit Typst. Einige Unterschiede zu LaTeX gibt es aber:
- Einstellungen, die speziell für LaTeX gedacht sind, wie
geometryoderfig-pos, haben bei Typst keine Wirkung. - LaTeX-Befehle direkt im Text, etwa
\newpage, werden bei Typst ignoriert. Einen Seitenumbruch, der in allen Formaten funktioniert, erzeugt der Shortcode{{< pagebreak >}}. - Bilder, die wir mit
einbinden, erscheinen bei Typst manchmal in einer anderen Größe als gewohnt. Dann hilft es, die Breite anzugeben, zum Beispiel mit{width="80%"}.
4.8.4 Präsentationen mit revealjs
Mit dem Format revealjs erzeugt Quarto Präsentationen, die im Browser laufen. Sie sind eine gute Alternative zu PowerPoint, vor allem wenn Ergebnisse aus R gezeigt werden sollen: Ändern sich die Daten, sind nach dem nächsten Rendern auch alle Grafiken auf den Folien aktuell. Der Aufbau einer Präsentation ist denkbar einfach:
- Jede Überschrift der Ebene 2 (
##) beginnt eine neue Folie und wird zu deren Titel. - Eine Überschrift der Ebene 1 (
#) erzeugt eine Abschnittsfolie, auf der nur diese Überschrift steht. - Die Titelfolie entsteht automatisch aus den Angaben im YAML-Header.
Eine kleine, aber vollständige Präsentation sieht so aus:
---
title: "Pinguine im Palmer-Archipel"
subtitle: "Referat im Kurs Datenanalyse"
author: "Max Mustermann"
date: today
lang: de
format:
revealjs:
slide-number: true # Foliennummern anzeigen
incremental: true # Listen Punkt für Punkt einblenden
footer: "Referat Datenanalyse" # Fußzeile auf jeder Folie
---
```{r}
#| include: false
library(pacman)
p_load(tidyverse, palmerpenguins)
```
# Die Daten
## Worum geht es?
- Messungen an `r nrow(penguins)` Pinguinen
- drei Arten: Adelie, Chinstrap und Gentoo
- unter anderem Flossenlänge und Körpergewicht
## Große Pinguine haben lange Flossen
```{r}
#| warning: false
penguins |>
ggplot(aes(x = flipper_length_mm, y = body_mass_g, color = species)) +
geom_point()
```
## Zwei Spalten
:::: {.columns}
::: {.column width="50%"}
Links steht Text …
:::
::: {.column width="50%"}
… und rechts auch.
:::
::::
::: {.notes}
Diese Notizen sieht nur, wer vorträgt.
:::Einiges ist bei Präsentationen anders als bei den übrigen Formaten:
-
Code wird standardmäßig nicht angezeigt, sondern nur sein Ergebnis – schließlich soll zum Beispiel eine Grafik möglichst viel Platz auf der Folie bekommen. Soll der Code zu sehen sein, setzen wir im Chunk
echo: true. Mit der zusätzlichen Optionoutput-location: columnstehen Code und Ergebnis nebeneinander. - Mit
incremental: trueim YAML-Header erscheinen die Punkte aller Listen nacheinander. Eine Pause an einer beliebigen Stelle erzeugen wir mit einer Zeile, die nur. . .enthält (drei Punkte mit Leerzeichen dazwischen). - Spalten erzeugen wir wie im Beispiel mit
.columnsund.column. - Notizen für den Vortrag stehen in einem Block
.notes. Sie erscheinen nur in der Sprecheransicht. - Passt der Inhalt nicht auf eine Folie, hilft
{.smaller}hinter dem Folientitel (kleinere Schrift) oder{.scrollable}(die Folie wird scrollbar), zum Beispiel## Ergebnisse {.smaller}. - Das Aussehen ändern wir mit der Option
theme. Es gibt gut ein Dutzend fertiger Designs, zum Beispieldefault,simple,serifoderdark.
Präsentieren
Die fertige Präsentation öffnen wir im Browser. Dort helfen die folgenden Tasten:
| Taste | Wirkung |
|---|---|
| Pfeiltasten, Leertaste | vor- und zurückblättern |
| F | Vollbild |
| S | Sprecheransicht mit Notizen, nächster Folie und Uhr |
| O oder Esc | Übersicht über alle Folien |
| B | Bildschirm schwarz schalten und wieder zurück |
| E | Druckansicht, z.B. zum Speichern als PDF-Datei |
Eine Übersicht über alle Tasten erhalten wir mit der Taste ?. Um die Präsentation als PDF-Datei zu speichern, wechseln wir mit E in die Druckansicht und drucken die Seite dann über den Browser (Strg+P bzw. Cmd+P) in eine PDF-Datei – am besten mit Google Chrome oder Chromium, im Querformat und ohne Seitenränder. Soll die Präsentation dagegen als HTML-Datei weitergegeben werden, hilft auch hier embed-resources: true (das funktioniert allerdings nicht zusammen mit der Tafel-Funktion chalkboard).
Was mit revealjs sonst noch alles möglich ist, zeigt die Demo-Präsentation von Quarto sehr eindrucksvoll. Eine Vorlage für eine Präsentation mit dem Logo der THA gibt es in Kapitel 4.13.
4.8.5 Mehrere Formate gleichzeitig
Ein Dokument kann auch in mehreren Formaten erzeugt werden, zum Beispiel als HTML-Datei zum Lesen am Bildschirm und als PDF-Datei zum Abgeben. Dazu führen wir einfach alle Formate im YAML-Header auf (statt pdf geht natürlich auch typst):
format:
html:
toc: true
embed-resources: true
pdf:
toc: true
papersize: a4Der Knopf Render erzeugt zunächst nur das erste Format; über den kleinen Pfeil daneben können wir ein anderes auswählen. Alle Formate auf einmal erhalten wir in der Konsole mit quarto::quarto_render("bericht.qmd", output_format = "all") oder im Terminal mit quarto render bericht.qmd.
Optionen, die für alle Formate gelten sollen (wie hier toc: true), können wir übrigens auch einmal auf die oberste Ebene des YAML-Headers schreiben, also direkt unter title oder author, statt sie bei jedem Format zu wiederholen.
4.9 Querverweise und Literaturangaben
Spätestens bei der ersten Hausarbeit brauchen wir zwei weitere Dinge: Verweise auf Abbildungen, Tabellen und Abschnitte sowie Literaturangaben. Beides erledigt Quarto fast von allein.
4.9.1 Querverweise
In längeren Texten verweisen wir oft auf andere Stellen: „Wie in Abbildung 3 zu sehen ist, …“. Quarto nummeriert Abbildungen, Tabellen, Abschnitte und Gleichungen automatisch und passt alle Verweise an, wenn etwas hinzukommt oder verschoben wird. Dazu sind zwei Schritte nötig:
- Das Element bekommt ein Label, das mit einem festgelegten Präfix beginnt:
fig-für Abbildungen,tbl-für Tabellen,sec-für Abschnitte undeq-für Gleichungen. - Im Text verweisen wir mit
@und dem Label darauf.
Tabelle 4.7 zeigt, wie die Labels jeweils vergeben werden.
| Element | Label vergeben | Verweis im Text |
|---|---|---|
| Grafik aus R | Chunk-Optionen label: fig-streuung und fig-cap
|
@fig-streuung |
| Bild | {#fig-logo} |
@fig-logo |
| Tabelle aus R | Chunk-Optionen label: tbl-kennzahlen und tbl-cap
|
@tbl-kennzahlen |
| Markdown-Tabelle |
: Titel {#tbl-arten} in der Zeile unter der Tabelle |
@tbl-arten |
| Abschnitt | # Methoden {#sec-methoden} |
@sec-methoden |
| Gleichung | $$ … $$ {#eq-zwert} |
@eq-zwert |
In diesem Kapitel haben wir das schon mehrfach genutzt. So wird aus dem Text
@fig-RQuarto-Pinguine und @tbl-RQuarto-Pinguine zeigen, dass
Gentoo-Pinguine am schwersten sind.im fertigen Dokument:
Abbildung 4.2 und Tabelle 4.6 zeigen, dass Gentoo-Pinguine am schwersten sind.
Die Wörter „Abbildung“ und „Tabelle“ fügt Quarto selbst ein. Schreiben wir sie zusätzlich in den Text, stehen sie doppelt da.
Auch Gleichungen lassen sich nummerieren. Dazu schreiben wir das Label direkt hinter die abschließenden Dollarzeichen:
$$
z_i = \frac{x_i - \bar{x}}{s}
$$ {#eq-RQuarto-zWert}Das ergibt eine nummerierte Gleichung:
z_i = \frac{x_i - \bar{x}}{s} \tag{4.1}
Mit @eq-RQuarto-zWert verweisen wir dann auf Gleichung 4.1.
4.9.2 Literaturangaben
Wissenschaftliche Texte kommen nicht ohne Literaturangaben aus. Quarto erzeugt Zitate und Literaturverzeichnis automatisch in einem einheitlichen Stil. Wir benötigen dafür
- eine Literaturdatei im BibTeX-Format (Endung
.bib), in der alle Quellen stehen, und - im YAML-Header einen Verweis auf diese Datei.
Ein Eintrag in der Literaturdatei sieht zum Beispiel so aus:
@book{wickham2023,
author = {Wickham, Hadley and Çetinkaya-Rundel, Mine and Grolemund, Garrett},
title = {R for Data Science},
edition = {2},
publisher = {O'Reilly},
year = {2023}
}Solche Einträge müssen wir selten selbst schreiben: Google Scholar liefert sie über Zitieren >> BibTeX, Literaturverwaltungsprogramme wie Zotero oder Citavi können sie exportieren, und im Visual-Modus von RStudio (Kapitel 4.3.1) findet Insert >> Citation Quellen sogar direkt über ihre DOI und trägt sie automatisch in die Literaturdatei ein.
Im YAML-Header geben wir die Literaturdatei und bei Bedarf einen Zitierstil an. In der Psychologie wird nach den Regeln der APA zitiert; die passende Stildatei apa.csl gibt es kostenlos im Zotero Style Repository. Ohne Angabe eines Stils verwendet Quarto den Chicago-Stil. Beide Dateien legen wir am besten in denselben Ordner wie die .qmd-Datei.
bibliography: literatur.bib
csl: apa.cslIm Text zitieren wir mit @ und dem Schlüssel des Eintrags, hier also wickham2023. Tabelle 4.8 zeigt die wichtigsten Varianten. Wie das Ergebnis genau aussieht, hängt vom Zitierstil ab.
| Markdown | Ergebnis (APA) |
|---|---|
[@wickham2023] |
(Wickham et al., 2023) |
@wickham2023 |
Wickham et al. (2023) |
[@wickham2023, S. 42] |
(Wickham et al., 2023, S. 42) |
[vgl. @wickham2023] |
(vgl. Wickham et al., 2023) |
[@mueller2020; @wickham2023] |
(Müller, 2020; Wickham et al., 2023) |
Das Literaturverzeichnis erstellt Quarto ebenfalls automatisch. Es enthält genau die Quellen, die im Text zitiert werden, und steht am Ende des Dokuments – oder an der Stelle, an der wir einen Block mit der ID refs einfügen. Damit es eine eigene Überschrift bekommt, schließen wir das Dokument zum Beispiel so ab:
# Literatur {.unnumbered}
::: {#refs}
:::4.10 Häufige Fehler und ihre Lösung
Beim Arbeiten mit Quarto treten immer wieder dieselben Fehler auf. Tabelle 4.9 fasst die häufigsten zusammen.
| Problem bzw. Fehlermeldung | Ursache | Lösung |
|---|---|---|
Objekt 'daten' nicht gefunden |
Das Objekt wurde nur in der Konsole erzeugt, zum Beispiel über Import Dataset. | Den Code, der das Objekt erzeugt, in einen Chunk oberhalb schreiben. Bei Import Dataset steht er im Feld Code Preview. |
konnte Funktion "ggplot" nicht finden |
Das Paket wurde nicht im Dokument geladen. | Alle Pakete im ersten Chunk des Dokuments laden. |
es gibt kein Paket namens '…' |
Das Paket ist nicht installiert. | Das Paket einmalig in der Konsole installieren. |
Objekt 'flipper_length_mm' nicht gefunden, obwohl es penguins gibt |
Seit R 4.5 enthält R selbst einen Datensatz penguins, allerdings mit kürzeren Spaltennamen. Ohne das Paket palmerpenguins wird dieser verwendet. |
Das Paket palmerpenguins im ersten Chunk laden. |
| Eine Datei, z.B. eine csv-Datei, wird nicht gefunden. | Relative Pfade beziehen sich auf den Ordner, in dem die .qmd-Datei liegt. |
Pfad prüfen, Daten im Projektordner ablegen (siehe Kapitel 3.3.2). |
| Fehlermeldung zum YAML-Header | Einrückung falsch, Leerzeichen nach dem Doppelpunkt fehlt oder Tabulator verwendet. | Siehe Kapitel 4.4. |
| Liste oder Überschrift erscheint als normaler Text. | Die Leerzeile davor bzw. das Leerzeichen nach # fehlt. |
Leerzeile bzw. Leerzeichen ergänzen. |
| Chunk-Optionen werden ignoriert. | Die Optionszeilen stehen nicht direkt am Anfang des Chunks, oder eine Option ist falsch geschrieben. | Optionen direkt unter die erste Zeile des Chunks schreiben und die Schreibweise prüfen. |
Im Text steht ?@fig-… statt eines Verweises. |
Label falsch geschrieben oder Präfix vergessen. | Label und Verweis vergleichen (Kapitel 4.9.1). |
| Die PDF-Datei wird nicht erzeugt, Hinweis auf fehlendes LaTeX bzw. TeX. | LaTeX ist nicht installiert. | TinyTeX installieren (Kapitel 4.2) oder Typst verwenden (Kapitel 4.8.3). |
| Die PDF-Datei hat das US-Format Letter statt DIN A4. | Bei Typst ist Letter voreingestellt. |
papersize: a4 angeben (Kapitel 4.8.3). |
Wenn nichts mehr geht
- Fehlermeldung lesen: Im Reiter Background Jobs steht, in welchem Chunk bzw. in welcher Zeile der Fehler auftritt. Hier zahlt es sich aus, den Chunks Labels zu geben.
- Rendern simulieren: Mit Run >> Restart R and Run All Chunks sehen wir, welcher Chunk den Fehler verursacht.
-
Eingrenzen: Hat das Rendern vor Kurzem noch funktioniert, steckt der Fehler in den letzten Änderungen. Verdächtige Chunks setzen wir vorübergehend auf
eval: false, Textstellen kommentieren wir mit<!--und-->aus – so lange, bis der Fehler verschwindet. - Hilfe holen: Wir fragen in unserer Lerngruppe nach oder lassen uns die Fehlermeldung von einer KI erklären. Dabei geben wir die vollständige Fehlermeldung und den betroffenen Code an und erwähnen ausdrücklich, dass wir Quarto verwenden.
4.11 Zusammenfassung
- Ein Quarto-Dokument (
.qmd) besteht aus dem YAML-Header, Text in Markdown und Code-Chunks. Beim Rendern entsteht daraus das fertige Dokument. - Beim Rendern wird der R-Code in einer neuen, leeren R-Sitzung ausgeführt. Alles, was das Dokument braucht – Pakete, Daten, Objekte –, muss daher im Dokument selbst stehen.
- Im YAML-Header legen wir Titel, Autor, Datum, Sprache und Ausgabeformat fest. Auf die Einrückung kommt es an!
-
Markdown formatiert Text mit wenigen Zeichen:
#für Überschriften,**für Fettdruck,-für Listen und$für Formeln. -
Chunk-Optionen (
#|) steuern, was von einem Chunk im Dokument erscheint (echo,eval,output,include), und beschriften Grafiken und Tabellen (label,fig-cap,tbl-cap). - Zahlen im Text kommen per Inline-Code direkt aus R – sie werden nie abgetippt.
-
HTML eignet sich für Mitschriften und Übungen, PDF für Hausarbeiten und revealjs für Präsentationen. PDF-Dateien erzeugen wir mit LaTeX (
format: pdf) oder ganz ohne Installation mit Typst (format: typst, für DIN A4 mitpapersize: a4). -
Querverweise (
@fig-…,@tbl-…) und Literaturangaben ([@schlüssel]) erzeugt Quarto automatisch. - Wir rendern häufig – dann lassen sich Fehler leicht finden.
4.12 Abschlussaufgabe: Ein kleiner Bericht
4.13 Nützliche Ressourcen und Vorlagen
Zum Weiterlesen
- Quarto-Dokumentation: die offizielle, sehr ausführliche Dokumentation (auf Englisch)
- Markdown-Grundlagen: alle Markdown-Elemente auf einen Blick
- Quarto in RStudio: Tipps für die Arbeit mit RStudio
- Typst in Quarto: alle Einstellungen für PDF-Dateien mit Typst
- R for Data Science: Quarto und Quarto formats: zwei gut lesbare Kapitel aus dem Standardwerk von Hadley Wickham, Mine Çetinkaya-Rundel und Garrett Grolemund
- Revealjs-Demo: Was mit Präsentationen alles möglich ist
- Galerie: Beispiele zum Stöbern – jeweils mit Quellcode
Vorlagen
- Vorlage für eine Vorlesungsmitschrift bzw. Hausaufgabe
- Vorlage für eine Präsentation, dazu das passende Logo der THA
So wie diese hier.↩︎
Gladwell, Malcolm. 2023. Outliers: Die Geheimnisse Erfolgreicher
Menschen. FinanzBuch Verlag.