Kapitel 5 RMarkdown

Markdown ist eine “Auszeichnungssprache,” die es erlaubt, mit einer recht einfachen Syntax ansprechende Dokumente zu erstellen. Sie wurde dabei so konzipiert, dass schon der Quellcode leicht lesbar ist.

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 8.1.7.3 zur Ordinalen Regression zunächst mit RMarkdown erstellt und veröffentlicht worden,4 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 5.1).

Abbildung 5.1: neues RMarkdown Dokument

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

Abbildung 5.2: Zusatzpakete für RMarkdown installieren

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

Abbildung 5.3: Installationsprozess

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

Abbildung 5.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 5.5. Bevor wir uns dem Inhalt zuwenden speichern wir das Dokument zunächst ab. Klicken Sie hierzu auf das Diskettensymbol (Mauszeiger in Abbildung 5.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.

Abbildung 5.5: speichern über Diskettensymbol

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

Abbildung 5.6: RMarkdown Dokument im Arbeitsverzeichnis

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

Abbildung 5.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 5.8).

Abbildung 5.8: Knit-Prozess

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

Abbildung 5.9: fertiges RMarkdown Dokument

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

Abbildung 5.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.

5.1 Syntax

Die Syntax von RMardown ist recht leicht, und es existiert zudem ein Cheatsheet (siehe Abschnitt 7.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 5.11).

Abbildung 5.11: visueller Modus über A

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

Abbildung 5.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.

Achten Sie darauf, die korrkten ``` 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 5.13).

Abbildung 5.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 5.14).

Abbildung 5.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 5.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  an dieser Stelle ausgeben würde.

Abbildung 5.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 7.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.