Die Logik von Markdown und Quarto

Author

Katharina Maubach & Patrick Zerrer

Artwork by @allison_horst

Wir können in R-Studio unterschiedliche Arten von Dokumenten nutzen. In diesem Kurs nutzen wir hauptsächlich R Quarto. Im folgenden Kapitel gehen wir auf die wichtigsten Funktionsweisen von Quarto ein.

1 R Markdown und Quarto

In diesem Kurs verwenden wir R Markdown bzw. R Quarto Dokumente. Diese haben den Vorteil, dass wir innerhalb eines Dokumentes Codeteile (sogenannte Code Chunks) und Text kombinieren können. Dies erlaubt die Dokumentation und Reproduzierbarkeit statistischer Auswertungen.

Bei Quarto handelt es sich im Prinzip um die neuere Variante von RMarkdown Dokumenten. Diese beinhalten alle Funktionalitäten von Markdown-Dokumenten (sind genauso aufgebaut und lassen sich normal rendern), aber bieten zusätzlich die Möglichkeit weitere Programmiersprachen (wie Python, Julia und Javascript) und interaktive Elemente (Widgets und Shiny-Anwendungen). Markdown-Dokumente weisen die Endung .rmd auf wohingegen Quarto-Dokumente den Endung .qmd haben. Beide Dokumenttypen können für unseren Kurszweck gleichwertig genutzt werden. Lediglich bei der Arbeit mit interaktiven, multimedialen oder mehrsprachigen Dokumenten ist Quarto besser geeignet als Markdown.

2 Installation der Programme

Markdown kann innerhalb von R mit dem Befehl install.packages("Rmarkdown") installiert und anschließend geladen werden. Da es sich bei Quarto nicht um ein Package, sondern ein eigenes Interface handelt, muss das Programm extern heruntergeladen und auf dem Rechner installiert werden.

3 Bestehende Dokument laden

Zum Laden eines Quarto- oder Markdown Dokumentes könnt ihr dieses einfach auf eurem Rechner doppelklicken. Wahlweise könnt ihr auch über File -> Open File (oder Strg + O) innerhalb von RStudio ein Dokument öffnen.

4 Neue Dokumente anlegen

Um ein neues Dokument anzulegen, könnt ihr einfach über File -> New File das gewünschte Dokument anlegen. Sowohl bei Markdown, als auch bei Quarto öffnet sich dann das Folgende Fenster:

Neues Dokument anlegen

Dort könnt ihr euer Dokument benennen (Title), die Autoren festlegen (Author) sowie das Output-Format (HTML, PDF oder WORD) festlegen. Zudem könnt ihr bei Quarto angeben, wie ist das Dokument gerendert werden soll (Knitr vs. Jupyter). Hier könnt ihr die Auswahl auf Knitr belassen. Zuletzt könnt ihr festlegen, ob ihr den visual markdown editor oder den source editor nutzen möchtet. All diese Punkte könnt ihr jedoch auch noch nachfolgend im YAML-Header oder im Menü) ändern.

5 Übergreifende Menüpunkte

Unterhalb der allgemeinen RStudio-Menüleiste findet ihr eine eigene Markdown und Quarto-Dokumentleiste:

Dokumentmenüleistet

Hier könnt ihr euer Dokument speichern (Diskettensymbol), in eurem Dokument suchen und ersetzen (Lupensymbol) oder euer Dokument Rendern (Quarto) oder Knitten (Markdown). Hiermit rendert ihr euer Dokument von R in euer gewünschtes Outputformat (Word, Pdf, oder Html). Zusätzlich könnt ihr mit dem Zahnrad Optionen für den Umgang mit dem gerenderten Dokument und den Codechunks festlegen. Zusätzlich könnt ihr hier neue Codechunks anlegen (+C-Symbol auf der rechten Seite) oder die bestehenden Code-Chunks ausführen (Run-Symbol)

6 Überblick über die Dokumentkomponenten

Sowohl Markdown, als auch Quarto-Dokumente bestehen aus drei Bestandteilen: dem YAML-Header, Textbereichen und Codebereichen.

6.1 YAML-Header

Innerhalb des YAML Headers, welcher jeweils von --- umgeben ist, legen wir die Dokumentstruktur fest.

YAML Header in einem Quarto Dokument

Dies beinhaltet beispielsweise den Titel des Dokumentes title:, die Autoren author, sowie Spezifikationen zur Dokumentstruktur, wie beispielsweise das Outputformat format: oder auch in Quarto Spezifikationen zum Umgang mit den Codechunks execute: echo : true auf Gesamtdokumentebene.

6.2 Text

In Markdown und Quarto-Dokumenten können wir Text einbinden und diesen beliebig formatieren. Dazu können wir wahlweise die Source-Variante oder die Visual-Variante nutzen. In der Source-Variante variieren wir Text mittels Syntax. Typische Syntaxbefehle sind:

  • *kursiv*: jeweils einen Stern vor und nach einem Wort um dieses kursiv zu schreiben
  • **fett**: jeweils zwei Sterne vor und nach einem Wort um dieses fett zu schreiben
  • #: Rauten für Überschriften, wobei eine Raute die erste Überschrift signalisiert, zwei Rauten die zweite usw.
  • ![Bildunterschrift](Link des Bildes): um Bilder einzufügen
  • [Linktext](url): Um Links einzufügen

Möchten wir übrigens die oben genutzten Symbole im Text nutzen, so können wir mit einem  vor dem jeweiligen Symbol die Formatierung umgehen.

Wahlweise können wir auch den Visual-Modus nutzen, indem wir oben in der Dokumentleiste von Sourceauf Visual umstellen. In diesem Modus erhalten wir ein Word-ähnliches Interface und können Formatoptionen durch Klicken auf die jeweilige Formatierung umsetzen:

Formatierungsoptionen im Visual Modus

6.3 Code Chunks

Innerhalb von Markdown und Quarto können wir Codebefehle direkt in unser Dokument innerhalb von sogenannten Codechunks integrieren. Hier können wir alle Arten von Code schreiben sowie diese mit Hilfe von # direkt kommentieren (alles hinter einer Raute wird dabei nicht ausgeführt). Codechunks beginnen mit drei Backticks und einem r in geschweiften Klammern und enden wieder mit drei Backticks:

```{r}
# Dies ist ein Code Chunk
```

Um die Codechunks zu erzeugen können wir einfach auf Code -> Insert Codechunk gehen, auf das +C-Symbol in der Dokumentmenüleiste oder den Shortcut Alt + Strg + I nutzen. Innerhalb der Chunks können wir Code schreiben und ausführen. Dies geschieht für eine einzelne Codezeile mit dem Shortcut Strg + Enter und für den gesamten Codechunk mit dem Shortcut Strg + Shift + Enter. Wahlweise könnt ihr auch den kleinen grünen Pfeil in der rechten oberen Ecke des Chunks, Code -> Run Selected Lines oder den Punkt Run in der Quarto-Dokumentleiste auswählen.

Zusätzlich können wir hinter dem {r} angeben, wie R mit dem Code des Chunks umgehen soll. Wir können beispielsweise auswählen, ob R den Code ausführen soll (eval = T/F) ob der Codebereich in unserem Enddokument aufgeführt sein soll (echo = T) oder wir lediglich die Ergebnisse angezeigt wollen (echo = F) oder ob wir beispielsweise Warnungen (warnings = T/F) oder Messages (message = T/F) in unserem Output-Dokument wünschen:

```{r, echo = T}
# Dies ist ein Code Chunk
```

Wahlweise können wir diese Optionen auch für das Gesamtdokument im YAML-Header festlegen. Dafür nutzen wir den Zusatz execute: und geben anschließend alle unsere Dokumentoptionen (für einen Überblick siehe hier) an.

Codeoptionen im Quarto Header

Achtung: wir nutzen hier : statt = und schreiben true und false statt TRUE/T und FALSE/F.

6.4 Globale Optionen

Zusätzlich können wir für das Gesamtdokument innerhalb eines Codechunks sogenannte options festlegen. Dies sind Einstellungen für unser gesamtes Dokument, die die Art und Weise beeinflussen, wie R seine Ergebnisse berechnet und anzeigt. Es gibt in R eine ganze Vielzahl solcher Einstellungen, welche man sich über die Eingabe von ?option in der Konsole anzeigen lassen kann. Die wichtigsten, mit welchen wir auch im Verlauf des Kurses arbeiten, sind scipen, digits und max.print.

  • scipen: Gibt an, ob bei sehr kleinen Zahlen (unterhalb von 0) die Nachkommastellen ausgeschrieben werden oder stattdessen die mathematische exponentionelle (e hoch minus, z.B. 1.234568e-06) verwendet werden soll. Options(scipen = 0) ist die Grundeinstellung. Hier wird die exponentielle Schreibweise verwendet. Möchten wir zu besseren Lesbarkeit und Verständlichkeit stattdessen die ausgeschriebenen Nachkommastellen, so verwenden wir options(scipen = 999).
  • digits: Über digits können wir die Anzahl der angezeigten Nachkommastellen festlegen. In der Grundeinstellung (default) zeigt R sieben Nachkommastellen an. Über options(digits = x) können wir die Zahl der angezeigten Nachkommastellen dementsprechend anpassen.
  • max.print: Mit max.print können wir einstellen, wie viele Zeilen eines Ergebnisses (oder Datensatzes uns R anzeigt). Üblicherweise in R werden alle Zeilen (beziehungsweise bis zu 99999) Zeilen eines Datensatzes angezeigt. Wenn man aus Übersichtlichkeitsgründen, bspw. bei sehr großen Datensätzen sich nur weniger Zeilen anzeigen lassen möchte, kann man mit options(max.print = x) die Zeilenzahl dementsprechend anpassen.
```{r}
options(scipen = 0) # exponentielle Schreibweise
options(scipen = 999) #ausgeschriebene Nachkommastallen
options(digits = 2) #gibt jeweils 2 Nachkommastellen aus
options(max.print = 100) #R zeigt nur die ersten 100 Zeilen eines Ergebnisses oder Datensatzes an
```

7 Literatur

Weiterführende Literatur

📖 Gehrau, V., Maubach, K., & Fujarski, S. (2022). Einfache Datenauswertung mit R. Link

📖 Xie, Y., Allaire, J. J., & Grolemund, G. (2020). R markdown: The definitive guide. Chapman; Hall/CRC Link

📖 Xie, Y., Dervieux, C., & Riederer, E. (2020). R markdown cookbook. Chapman and Hall/CRC Link

📖 Allaire, J. J., Xie, Y., McPherson, J., Luraschi, J., Ushey, K., Atkins, A., Wickham, H., Cheng, J., Chang, W., & Iannone, R. (2020a). rmarkdown: Dynamic documents for r. Link