19  RMarkdown

Im Sommer 2022 wurde RMarkdown durch den Nachfolger quarto abgelöst, weshalb dieses Kapitel eher historische Informationen enthält. Wenn Sie RMarkdown noch nie benutzt haben, sollten Sie dieses Kapitel überspringen und direkt mit quarto einsteigen, siehe Kapitel 20.

RMarkdown ermöglicht es, R-Code, -Output und -Diagramme, sowie Formeln und externe Quellen (z.B. Bilder aus dem Internet) in ansprechenden Dokumenten (z.B. Webseite, Word, Powerpoint, PDF) zu exportieren. Es ist sehr gut dafür geeignet, die eigenen statistischen Auswertungen und Ergebnisse für Endanwender (z.b. Auftragsgeber oder Dozenten) darzustellen.

Die Funktionalität hat sich so sehr weiterentwickelt, dass mittlerweile auch Abschlussarbeiten (Bachelor, Master) komplett mit RMarkdown geschrieben werden.

Tatsächlich ist Abschnitt 27.7.3 zur Ordinalen Regression zunächst mit RMarkdown erstellt und veröffentlicht worden 1, das ist aber schon sehr lange her.

Wir erstellen in unserem Projekt ErsteSchritte nun das erste Markdown-Dokument. Klicken Sie hierzu wieder oben im Scriptfenster auf das grüne + Symbol und wählen Sie R Markdown... (Abbildung 19.1).

Abb. 19.1: neues RMarkdown Dokument

Falls Sie dies zum ersten Mal tun, schlägt RStudio die notwendigen Zusatzpaket zur Installation vor (Abbildung 19.2).

Abb. 19.2: Zusatzpakete für RMarkdown installieren

Die Installation dauert ein paar Minuten, und Sie können den Prozess unten im Konsolfenster verfolgen (Abbildung 19.3, siehe grüner Balken).

Abb. 19.3: Installationsprozess

Es öffnet sich ein neus Fenster (Abbildung 19.4). Wir erstellen hier ein Dokument. Sie sehen aber schon, dass RMarkdown weitere Formate (z.B. Präsentationen) ebenfalls unterstützt.

Abb. 19.4: neues HTML Dokument

Tragen Sie den Titel des Dokumentes sowie den Autoren ein. Wir belassen in diesem Beispiel die Default Output Option auf HTML. Sie können aber auch Word oder PDF wählen.

Es wird nun eine Standardvorlage des Dokumentes erzeugt (Abbildung 19.5). Bevor wir uns dem Inhalt zuwenden speichern wir das Dokument zunächst ab. Klicken Sie hierzu auf das Diskettensymbol (Mauszeiger in Abbildung 19.5) oder drücken Sie die Tastenkombination [STRG] + [S]. Geben Sie Ihrem Dokument einen Dateinamen mit der Endung .Rmd (für RMarkdown). Ich habe meine Datei MeinErstesMarkdown.Rmd genannt.

Abb. 19.5: speichern über Diskettensymbol

Die Datei ist nun ebenfalls im Dateiverzeichnis zu sehen (Abbildung 19.6) und kann von dort aus geöffnet werden.

Abb. 19.6: RMarkdown Dokument im Arbeitsverzeichnis

Über dem Scriptfenster befindet sich der Knit-Knopf (Abbildung 19.7, Mauszeigen).

Abb. 19.7: Knit-Knopf

Wenn Sie hier klicken, oder die Tastenkombination [STRG] + [SHIFT] + [K] benutzen, wird aus Ihrem RMarkdown die gewünschte Ausgabedatei (in diesem Beispiel html, also eine Webseite) erzeugt und im Arbeitsverzeichnis gespeichert.

Da die Standardvorlage alle wichtigen Dinge enthält können wir direkt auf den Knit-Knopf klicken. Das RMarkdown-Dokument wird nun “übersetzt”, und Sie können den Prozess im Konsolenfenster verfolgen (Abbildung 19.8).

Abb. 19.8: Knit-Prozess

Ist dieser Schritt erfolgreich, öffnet sich ein neues Fenster mit dem Endresultat (Abbildung 19.9.

Abb. 19.9: fertiges RMarkdown Dokument

In unserem Arbeitsverzeichnis sehen wir ebenfalls die soeben erzeugte Ausgabedatei, in Abbildung 19.10 ist das MeinErstsMarkdown.html.

Abb. 19.10: fertige HTML Datei

Beachten Sie, dass in der html-Datei bereits alle nötigen Ressourcen (z.B. alle Bilder) gespeichert sind. Möchten Sie Ihr html-Dokument mit Kolleginnen und Kollegen teilen, brauchen Sie keine weiteren Dateien kopieren oder versenden. Die html-Webseite wird auf allen Geräten “gleich” aussehen, und es werden z.B. keine Grafiken oder Bilder fehlen.

19.1 Syntax

Die Syntax von RMardown ist recht leicht, und es existiert zudem ein Cheatsheet (siehe Abschnitt 26.1) unter

https://raw.githubusercontent.com/rstudio/cheatsheets/master/rmarkdown-2.0.pdf.

Schauen wir uns unsere eben erzeugte Markdowndatei noch einmal an. Wir löschen alles, bis auf die ersten Zeilen, und beginnen ganz von vorne.

--- 
title: "Ein neuer Titel" 
author: "Jörg große Schlarmann" 
date: "27 3 2021" 
output: html_document 
---

Dies ist die Kopfzeile des Dokuments. Wir können hier den Titel, Autor und das Datum ändern. Unter den drei Strichen beginnen wir unser Dokument. Schreiben Sie folgende Zeilen.

---
title: "Dies ist ein Test"
author: "Timm Thaler"
date: "27 3 2021"
output: html_document
---

# Überschrift

Willkommen zu meinem RMarkdown-Dokument

- dies ist ein Punkt
- dies ein weitere

1. erstens
2. zweitens
3. drittens

## Unter-Überschrift

Dies ist **fett**, dies *kursiv*, dies ~~durchgestrichen~~.

Drücken Sie den Knit-Knopf und erzeugen so einen Testoutput.

Das Zeichen # steht für Überschriften und deren Hierarchie. Die Anzahl der # legt die Überschriftenhierarchie fest. Aus den Spiegelstrichen ist eine Liste geworden, die Zahlen wurden in eine nummerierte Aufzählungsliste umgewandelt. Schauen Sie im RMarkdown-Cheatsheet nach, welche weiteren Zeichen für welchen Effekt stehen.

In RStudio gibt es auch einen visuellen Markdown-Modus, der so ähnlich funktioniert wie Word oder LibreOffice. So können Sie Ihren Text “wie gewohnt” gestalten. Klicken Sie hierzu auf das A-Symbol rechts oben (siehe Mauszeiger in Abbildung 19.11).

Abb. 19.11: visueller Modus über A

Der Text sieht nun “fast” schon so aus, wie auf dem Endoutput (Abbildung 19.12).

Abb. 19.12: visueller Editiermodus

Sie haben zudem oben eine Menüzeile, mit der Sie die Schriftart wechseln, externe Bilder einbinden oder Tabellen erzeugen können.

Durch Klick auf das A-Symbol wechseln Sie zwischen visueller und “klassischer” Ansicht.

Denken Sie daran, in die klassische Ansicht zurück zu wechseln, bevor Sie Markdown-Code kopieren und einfügen. Dies ist ein häufiger Anfgängerfehler, und der visuelle Editor kann mit dem Code nichts anfangen.

In Markdown können sehr leicht Tabellen erzeugt werden. Versuchen Sie diesen Code aus (vorher vom visuellen Editor zurückwechseln!), und beachten Sie, wie “gut lesbar” und “leicht zu merken” das ist.

## Tabelle

| Name   | Beruf       | Alter |
|--------|-------------|-------|
| Heinz  | Kraftfahrer | 46    |
| Lisa   | Professorin | 32    |
| Jürgen | Klemptner   | 48    |

: Meine Tabelle

Alles weitere finden Sie auf den erwähnten Cheatsheets.

Kommen wir nun zum eigentlichen Kernpunkt: der Darstellung von R-Code und -Output.

Hierfür muss im Markdowndokument der Bereich für den R-Code festgelegt werden. Dies erfolgt über die Zeichenkette ``` , die den Codebereicht einschließt.

```{r}
# hier steht der R-Code
```

Die Anführungsstriche grenzen den Codebereich ein. Dieser wird Chunk genannt. Das {r} bedeutet, dass R-Code verwendet wird.

Achtung, Anfängerfehler

Achten Sie auf die korrekten Anführungszeichen!

Achten Sie darauf, die korrekten ``` zu verwenden, und nicht etwa ''' oder ´´´.

Dies ist ein häufiger Anfängerfehler.

In RStudio können Sie einfach die Tastenkombination [STRG] + [ALT] + [i] drücken, oder im Scriptfenster oben auf das grüne c klicken (Abbildung 19.13).

Abb. 19.13: erstellt neuen Chunk

Beides fügt einen neuen Chunk (Codeblock) ein.

Schreiben Sie in Ihr Dokument:

Ich lade den pf8-Datensatz mit: 
```{r}
load(url("https://www.produnis.de/R/pf8.RData"))
```

Wenn Sie den Knit-Knopf drücken, wird der load()-Befehl im Dokument angezeigt und in der Konsole ausgeführt.

Ergänzen Sie jeweils die nun folgende Zeilen, und schauen Sie sich das Ergebnis nach einem Knit an.

Ich lade den pf8-Datensatz, der Befehl wird aber im Dokument nicht angezeigt.
```{r include=FALSE}
load(url("https://www.produnis.de/R/pf8.RData"))
```

Durch den Parameter include=FALSE wird der Befehl zwar intern ausgeführt, jedoch nicht im Dokument angezeigt. Sollte der Befehl einen Output erzeugen, wird dieser ebenfalls nicht angezeigt.

Wenn Sie nur das Ergebnis anzeigen möchten, aber nicht die R-Befehle, setzen Sie den Parameter echo=FALSE.

Wir plotten Alter und gewicht aus dem pf8-Datensatz 
```{r echo=FALSE}
plot(pf8$Alter, pf8$Gewicht)
```

In der “Standardeinstellung” werden immer Befehl und Output des Chunks im Dokument angezeigt. Sie können dieses Verhalten auch erzwingen durch den Parameter echo=TRUE

Wir plotten Alter und gewicht aus dem pf8-Datensatz 
```{r echo=TRUE}
plot(pf8$Alter, pf8$Gewicht)
```



Darstellungsoptionen der Chunks
Verhalten Code
nur Code, kein Output results=“hide”
nur Code, nicht ausführen eval=FALSE
kein Code, nur Output echo=FALSE
zeige beides echo=TRUE
zeige nichts include=FALSE
mache auch nichts eval=FALSE, include=FALSE



Die Chunks werden im Editorfenster farblich hervorgehoben (Abbildung 19.14).

Abb. 19.14: Chunk ausführen

Sie haben hier die Möglichkeit, den Code “ohne Knit” auszuführen und sich das Ergebnis anzeigen zu lassen. Klicken Sie dazu rechts auf das grüne Dreieck.

In diesem Beispiel wird der Plot nun direkt im Markdownfenster angezeigt (Abbildung 19.15). Dies ist wirklich hilfreich beim Erstellen des Dokuments, denn Sie müssen nicht immer erst das gesamte Dokument knitten oder überhaupt geöffnet haben, um zu sehen, was R an dieser Stelle ausgeben würde.

Abb. 19.15: Der Chunk-Output wird bereits im Editor angezeigt

Über das Zahnrad gelangen Sie zu weiteren Einstellungsmöglichkeiten. So können Sie die Chunks internet mit Namen versehen, so dass Sie später im Dokument darauf referenzieren können.

Die vielen weiteren Möglichkeiten von RMarkdown werden in diesem Buch nicht weiter behandelt, weitere Informationen erhalten Sie im RMarkdown-Cheatsheet (siehe Abschnitt 26.1) oder im frei verfügbaren Buch R Markdown: The Definitive Guide, welches Sie unter https://bookdown.org/yihui/rmarkdown/ lesen können.

Grundsätzlich sollten Sie es so halten, dass Sie in den Scriptdateien Ihre Auswertungen ausprobieren und mit den Befehlen “herumspielen”. Die Quintessenz Ihrer Analyseschritte können Sie dann in “aufgräumter” Form in einem RMarkdown festhalten und mit anderen teilen.


  1. https://rpubs.com/produnis/oreg↩︎