R Markdown Tutorial für Einsteiger

In diesem Artikel sehen wir uns ein unverzichtbares, hilfreiches Data-Science-Paket an, das jede R-Nutzerin und jeder R-Nutzer kennen sollte—R Markdown. Wir klären, was R Markdown ist, welche Vorteile es bietet, wofür es verwendet wird, wie man es installiert, wie es das Arbeiten mit Code, Text und Diagrammen erleichtert, welche Syntax es verwendet, welche Ausgabeformate es gibt und wie wir solche Dokumente rendern und mit unseren Kolleginnen und Kollegen teilen.

Da R Markdown besonders gut auf die integrierte Entwicklungsumgebung (IDE) RStudio zugeschnitten ist, nutzen wir in diesem Artikel durchgängig diese IDE. Das RStudio-Tutorial zeigt dir, wie du RStudio installierst und loslegst.

Legen wir los!

Was ist R Markdown?

R Markdown ist ein kostenloses Open-Source-Paket für R, das dir eine Arbeitsumgebung zum Erstellen von Data-Science-Projekten bietet. Der große Vorteil: Du kombinierst Code, Text und Visualisierungen in einem einzigen, sauberen, teilbaren und vollständig reproduzierbaren Dokument, das sich in zahlreiche Ausgabeformate rendern lässt—sowohl statisch als auch interaktiv.

Beliebte Ausgabeformate sind unter anderem HTML, PDF, Microsoft Word, Präsentationen, Anwendungen, Websites, Dashboards, Berichte, Vorlagen, Artikel, Bücher usw.

Außerdem erleichtert R Markdown die Versionskontrolle und unterstützt neben R viele weitere Programmiersprachen, darunter Python und SQL.

Wenn du tiefer in das Erstellen dynamischer Berichte mit R Markdown einsteigen möchtest, ist der Kurs Reporting with R Markdown der ideale Startpunkt.

R Markdown installieren

Wenn du R Markdown außerhalb von RStudio verwendest, installierst du es wie jedes andere R-Paket aus dem CRAN-Repository:

install.packages("rmarkdown")

Nach der Installation laden wir das Paket in die aktuelle R-Session:

library(rmarkdown)

Arbeiten wir hingegen innerhalb von RStudio mit R Markdown—so wie in diesem Tutorial—müssen wir das rmarkdown-Paket nicht explizit installieren und laden. Über File—New File—R Markdown in der RStudio-Menüleiste öffnest du ein neues R-Markdown-Dokument. Eventuell erscheint der Hinweis Install Required Packages:

Nach Bestätigung der benötigten Pakete gibst du im folgenden Pop-up einen Dokumenttitel und den Autorennamen an (beides optional, aber empfehlenswert), belässt die übrigen Einstellungen und klickst auf OK:

Standarddokument in R Markdown

Im vorherigen Abschnitt haben wir in RStudio ein neues R-Markdown-Dokument geöffnet. Es sieht so aus:

Du siehst Titel, Autor, aktuelles Datum und das voreingestellte Ausgabeformat, die wir im Pop-up angegeben haben. Außerdem enthält es Beispiele der grundlegenden R-Markdown-Syntax: Code-Blöcke einfügen und formatieren, Überschriften hinzufügen, Links einfügen, Text hervorheben und Plots erzeugen.

Gleich schauen wir uns die einzelnen Funktionen von R Markdown und deren Syntax im Detail an. Zunächst speichern wir die Standarddatei und rendern sie im gewählten Ausgabeformat (hier: HTML), um das Ergebnis zu sehen.

Zum Speichern klickst du in der Menüleiste von RStudio auf File—Save As....

Hinweis: Der im Pop-up vergebene Dokumenttitel ist nicht identisch mit dem Dateinamen. Speichere die Datei im Projektverzeichnis und sichere sie regelmäßig während der Arbeit (File—Save).

Zum Rendern der gespeicherten Datei im gewählten Ausgabeformat (HTML) klickst du in der Dokument-Symbolleiste auf Knit:

So sieht unser Standarddokument als HTML aus:

Textformatierung in R Markdown

Oft macht Text den Großteil eines Data-Science-Projekts aus. Umso wichtiger ist es, ihn in R Markdown gut lesbar, effizient und ansprechend zu formatieren.

Wenn du R für Datenanalyse und Data Science lernen und sowohl deine R-Programmierung als auch deine Data-Science-Kompetenzen ausbauen willst, sind diese einsteigerfreundlichen, umfassenden Karrierepfade empfehlenswert:

• Data Analyst with R
• Data Scientist with R

Überschriften

Verschiedene Ebenen von Überschriften fügst du mit dem Rautenzeichen (#) hinzu. Die Syntax lautet:

# Überschrift 1 (Titel)

## Überschrift 2 (Abschnitt)

### Überschrift 3 (Unterabschnitt)

usw.

Gerendert sehen die Überschriften so aus:

Text hervorheben

R Markdown erlaubt verschiedene Arten der Hervorhebung: kursiv, fett, durchgestrichen, hoch- oder tiefgestellt, zum Beispiel:

• *kursiv* oder _kursiv_
• **fett** oder __fett__
• ~~durchgestrichen~~
• Text^hochgestellt^
• Text~tiefgestellt~

So erscheinen diese Hervorhebungen im gerenderten Dokument:

Listen

Für ungeordnete Listen kannst du eine der drei folgenden Schreibweisen verwenden:

* Punkt 1* Punkt 2* Punkt 3

oder:

- Punkt 1- Punkt 2- Punkt 3

oder:

+ Punkt 1+ Punkt 2+ Punkt 3

Das Rendering ist in allen Fällen identisch:

Für geordnete Listen verwendest du diese Syntax:

1. Punkt 12. Punkt 23. Punkt 3

Gerendert wirkt das ähnlich, nur mit Einrückung vor den Zahlen.

Praktisch: Wenn du einen Eintrag löschst, einen neuen hinzufügst oder dich bei einer Zahl vertippst (z. B. 20. statt 2.), korrigiert R Markdown die Nummerierung automatisch und zeigt sie wie beabsichtigt an:

Blockzitate

Für Blockzitate setzt du vor das erste Zeichen der zu zitierenden Zeile ein >:

> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam hendrerit nisi sed sollicitudin pellentesque. Nunc posuere purus rhoncus pulvinar aliquam. Ut aliquet tristique nisl vitae volutpat. Nulla aliquet porttitor venenatis. Donec a dui et dui fringilla consectetur id nec massa. Aliquam erat volutpat. Sed ut dui ut lacus dictum fermentum vel tincidunt neque.

Gerendert sieht das so aus:

Wir fügen nach einem Zitatblock eine Leerzeile ein, um ihn zu beenden.

Links

Wenn du einen Link direkt einfügen möchtest, setze die URL zwischen < und >. Zum Beispiel wird Folgendes:

<https://www.google.com/>

so gerendert:

https://www.google.com/

Um einen Link an ein Wort oder einen kurzen Text zu binden, verwendest du diese Syntax (am Beispiel der Google-Website):

[Google](https://www.google.com/)

Gerendert wird daraus:

Google

Bilder

Bilder fügst du auf drei Arten ein:

1. Bild aus dem Internet:


2. Bilddatei liegt im Projektordner:


3. Bilddatei liegt außerhalb des Projektordners:


Der Alt-Text beschreibt kurz das Bild und wird angezeigt, wenn das Bild aus irgendeinem Grund nicht sichtbar ist.

Sehen wir uns Ansatz 1 an, mit einem Pixabay-Bild und der Bild-URL https://cdn.pixabay.com/photo/2018/12/02/10/07/web-3850917_1280.jpg:


Nach dem Rendern wird das Bild angezeigt:

Umbrüche

In R Markdown gibt es verschiedene Arten von Umbrüchen:

1. Zeilenumbruch—beginnt eine neue Zeile. Am Ende der vorherigen Zeile mit einem Backslash (\) einfügen.
2. Absatzumbruch—beginnt einen neuen Absatz. Am Ende des vorherigen Absatzes zwei Leerzeichen setzen.
3. Folie/Abschnitt—beginnt eine neue Folie (bei Präsentationen) oder einen neuen Abschnitt (in anderen Formaten). Füge dazu eine horizontale Linie (***) ein.
4. Seitenumbruch—beginnt eine neue Seite, wenn das Ausgabeformat dies unterstützt (z. B. in Microsoft Word). Mit dem Befehl \newpage einfügen.

Hier ein Beispiel mit den ersten drei Umbrucharten. Unten ein Lorem-ipsum-Text mit entsprechenden R-Markdown-Symbolen:

Lorem ipsum dolor sit amet, consectetur adipiscing elit.\Nam hendrerit nisi sed sollicitudin pellentesque.

Nunc posuere purus rhoncus pulvinar aliquam.

***

Ut aliquet tristique nisl vitae volutpat.

So wird es im HTML-Dokument gerendert:

Lorem ipsum dolor sit amet, consectetur adipiscing elit.Nam hendrerit nisi sed sollicitudin pellentesque.

Nunc posuere purus rhoncus pulvinar aliquam.

Ut aliquet tristique nisl vitae volutpat.

Code formatieren und ausführen in R Markdown

Code ist ein weiterer zentraler Bestandteil jedes Data-Science-Projekts. In R Markdown kannst du Code ausführen (nicht nur in R), sowohl Code als auch Ausgaben anzeigen, nur den Code zeigen und die Ausgaben verbergen, nur Ausgaben anzeigen und den Quellcode ausblenden usw.

Der einsteigerfreundliche Karrierepfad R Programmer und der Kompetenzpfad R Programming helfen dir, deine R-Coding-Skills zu lernen, zu üben und zu schärfen.

Code-Chunks

Um einen R-Codeblock zu formatieren und auszuführen, umschließt du ihn mit drei Backticks. Nach den ersten drei Backticks folgt in geschweiften Klammern ein r. Beispiel:

```{r}
print("Hello, World!")
```

Wenn wir das Dokument rendern, ohne den Code auszuführen, sieht der Code-Chunk so aus:

Programmiersprache

In R Markdown bist du nicht auf R beschränkt, denn das Paket unterstützt viele weitere Sprachen. Um Code in einer anderen Sprache auszuführen, setzt du deren Namen statt r in die Klammern. Gegebenenfalls musst du zusätzliche Pakete in R installieren und laden.

Um beispielsweise Python in R Markdown zu verwenden, installierst und lädst du das Paket reticulate. Es ermöglicht die bidirektionale Kommunikation zwischen Python und R im selben R-Markdown-Dokument (z. B. Variablen erstellen und darauf zugreifen).

Schreiben wir das Beispiel aus dem vorherigen Abschnitt in Python um (nach Installation und Laden von reticulate):

```{python}
print("Hello, World!")
```

Code-Chunks ausführen

Um in RStudio einen Code-Chunk oder ausgewählte Zeilen darin auszuführen, klickst du in der Dokument-Symbolleiste auf Run und wählst die gewünschte Option aus dem Dropdown:

Im Bild siehst du auch die Tastenkürzel für jede Option, damit du nicht jedes Mal das Menü öffnen musst.

Code-Chunks benennen

Nicht verpflichtend, aber eine gute Praxis: Benenne deine Code-Chunks. Das ist nützlich zum Referenzieren im Dokument, fürs Debugging oder um schnell zu navigieren—besonders in langen Dokumenten mit vielen Chunks.

Den Namen fügst du in den Klammern direkt nach dem Sprachnamen hinzu und trennst ihn mit einem Leerzeichen. Chunk-Namen dürfen keine Leerzeichen enthalten.

Im folgenden Beispiel haben wir den Chunk hello_world genannt:

```{r hello_world}
print("Hello, World!")
```

Optionen für Code-Chunks

Mit Chunk-Optionen steuerst du für jeden einzelnen Chunk Ausführung, Ausgabe, Formatierung, Caching, Animation (falls relevant) und Plots (falls relevant). Du kannst mehrere Optionen kombinieren. Syntax: Die Optionen stehen in den geschweiften Klammern nach dem Chunk-Namen (falls vorhanden, sonst nach dem Sprachnamen) und werden durch Kommas getrennt.

Es gibt viele Optionen in R Markdown. Jede hat einen Standardwert, doch oft willst du etwas anderes. Hier die gängigsten Optionen und was sie bewirken:

• echo=FALSE—der Code selbst wird im finalen Dokument nicht angezeigt, nur die Ausgaben.
• eval=FALSE—der Code im Chunk wird nicht ausgeführt.
• include=FALSE—der Chunk wird ausgeführt, aber nicht im finalen Dokument gezeigt.
• results—Standard ist "markup"; weitere Werte:
• "hide"—Ausgaben werden im finalen Dokument verborgen
• "hold"—Ausgaben werden erst nach Ausführung des gesamten Chunks angezeigt
• "asis"—Ausgaben werden unverändert durchgereicht.
• message=FALSE—vom Code erzeugte Meldungen werden unterdrückt.
• error=FALSE—Fehlermeldungen werden unterdrückt.
• warning=FALSE—Warnungen werden unterdrückt.
• highlight=FALSE—der Code wird nicht syntaxhervorgehoben.
• prompt=TRUE—am Zeilenanfang wird ein > als Prompt angezeigt.

Hier einige Beispiele für Chunks, die in RStudio ausgeführt und anschließend im finalen Dokument gerendert wurden:

Code in R Markdown:

Ausgabe im finalen Dokument:

Inline-Code

Mit Inline-Code fügst du kurze Code-Snippets direkt in den Text ein—sie werden ausgeführt und ihre Ausgabe erscheint im Satz. Die Syntax lautet r <code>.

Ein einfaches Beispiel mit Inline-Code:

There are `r 1+6` colors of the rainbow.

So wird es gerendert:

There are 7 colors of the rainbow.

In der Praxis nutzt du Inline-Code, um Kennzahlen aus den Daten direkt einzubetten. So vermeidest du Tippfehler und hältst Zahlen aktuell, wenn sich die Daten ändern.

Plotten in R Markdown

Plots in R Markdown entstehen durch Code, der Grafiken erzeugt. Alles, was wir zur Code-Formatierung und -Ausführung gesagt haben (außer Inline-Code), gilt also auch hier. Der Unterschied: Die Ausgabe sind Grafiken statt reiner Text oder Zahlen.

Der Kompetenzpfad Data Visualization with R hilft dir, Daten in R zu analysieren und zu visualisieren—und damit bessere, datenbasierte Geschichten zu erzählen.

Zum Anpassen der Plots verwendest du wie in R üblich die Funktionen der Visualisierungspakete sowie die Basisfunktion plot().

Zur Steuerung des Plot-Verhaltens in R Markdown kannst du spezielle Chunk-Optionen nutzen. Viele davon sind sehr spezifisch und sprengen den Rahmen dieses Einstiegs. Hier einige grundlegende Optionen, die beim Plotten hilfreich sind:

• fig.show—Standard ist "asis"; weitere Werte:
• "hide"—Plots werden erzeugt, aber nicht ins finale Dokument eingebunden
• "hold"—Plots werden erst nach Ausführung des gesamten Chunks angezeigt
• "animate"—alle Plots des Chunks werden zu einer Animation kombiniert.
• fig.width—Breite des Plots in Zoll, Standard 7.
• fig.height—Höhe des Plots in Zoll, Standard 7.
• fig.align—Ausrichtung im Dokument: "left", "center" oder "right".
• fig.cap—Bildunterschrift als Zeichenkette.
• fig.path—Pfad zum Verzeichnis für durch den Chunk erzeugte Plot-Dateien.
• fig.ext—Dateiendung der erzeugten Plot-Dateien.

Unten einige Beispiele für plot-spezifische Chunks inklusive Quellcode und gerenderter Ausgabe:

Code in R Markdown:

Ausgabe im finalen Dokument:

Ausgabeformate

Bisher haben wir nur das HTML-Dokument (html_document) als Ausgabe betrachtet. R Markdown bietet jedoch viele weitere Formate, darunter Microsoft Word, Microsoft PowerPoint, PDF, interaktive R-Notebooks, Dashboards usw.

Für Dokumente stehen zum Beispiel html_document, pdf_document, word_document, github_document, html_notebook, html_vignette u. a. zur Verfügung. Für Präsentationen gibt es etwa powerpoint_presentation, ioslides_presentation, slidy_presentation und beamer_presentation.

Das Ausgabeformat legst du in den Dokumentmetadaten fest (dem sogenannten YAML-Header, YAML steht für "yet another markup language"). Für unser Dokument ist html_document gesetzt—das ist auch der Standard in R Markdown:

Um es zu ändern, ersetzt du html_document durch das gewünschte Format (pdf_document, word_document, powerpoint_presentation usw.). Beim nächsten Klick auf Knit wird im gewählten Format gerendert.

R-Markdown-Dokumente veröffentlichen

Zum Veröffentlichen klickst du in RStudio auf File—Publish und wählst das Ziel aus:

Folge dann den weiteren Schritten je nach Ziel und klicke auf Publish. Dein Dokument ist jetzt bereit, um es zu teilen.

Fazit

Zusammenfassend hast du in diesem Artikel gelernt, wie du mit R Markdown startest: Was R Markdown ist und wofür es genutzt wird, wie du es installierst, Text und seine Elemente formatierst, Code formatierst und ausführst, Plots erzeugst, welche Ausgabeformate es gibt, wie du dein Dokument in eines dieser Formate renderst und anschließend veröffentlichst, um es weiterzugeben.

Für praktische Übungen mit R Markdown schau dir unseren Kurs Reporting with R Markdown an. Er hilft dir, Erkenntnisse aus Daten zu gewinnen und sie als PDF, HTML-Datei oder Shiny-App zu veröffentlichen.