Hier gibt es eine kurze Einführung in R Markdown.Wir beschränken uns dabei auf die grundlegende Idee von Markdown, da diekonkrete Syntax im Internet an zahlreichen Stellen wunderbar erläutert istund man das konkrete Schreiben am besten in der Anwendung lernt.
14.1 Markdown vs.R-Markdown
Bei Markdown handelt es sich um eine sehr einfache Auszeichnungssprache,d.h. eine Programmiersprache, mit der schön formatierte Texte erstellt werdenkönnen und die gleichzeitig auch für Menschen sehr einfach lesbar ist.Dateien, die in Markdown geschrieben sind, sind gewöhnlicherweise an derEndung .md zu erkennen.
R-Markdown stellt man sich am besten als eine Kombination von Markdown und Rvor:R-Markdown Dateien, die immer durch die Dateiendung .Rmd gekennzeichnet sind,bestehen sowohl aus Markdown-Code, als auch aus R-Code.Das bedeutet, dass man sein Forschungsprojekt gleichzeitig erklären unddurchführen kann.Im Prinzip können ganze Forschungspapiere in R-Markdown verfasst werden unddamit vollständig reproduzierbar gestaltet werden.
14.2 Installation von R-Markdown
Für den Fall, dass Sie mit R-Studio arbeiten brauchen Sie lediglichdas Paket rmarkdown zu installieren:
install.packages('rmarkdown')Das Standardformat für R-Markdown Dokumente ist html.
Damit Sie auch PDF-Dokumente erstellen können müssen Sie noch eineLatex-Distribution.Wir empfehlen Ihnen in jedem Fall die Distributiontinytexzu installieren, unabhängig davon, ob Sie bereits über eine andereDistribution verfügen.Beachten Sie, dass nach der Installation des Pakets tinytex diedie tinytex-Distribution noch nicht installiert wurde.Das Paket und die Distribution sind zwei unterschiedliche Dinge!Um die Distribution zu installieren müssen Sie bei bestehenderInternetverbindung noch folgenden Befehl in Ihrer R-Konsoleausführen:
tinytex::install_tinytex()Beachten Sie, dass das einen kurzen Augenblick dauern kann und dassca. 65 MB an Dateien aus dem Internet heruntergeladen werden.
14.3 Der R-Markdown Workflow
14.3.1 Ein neues R-Markdown Dokument erstellen
R-Studio macht es Ihnen sehr leicht R-Markdown Dokumente zu erstellen.Klicken Sie einfach auf den Button Neu und wählen dort dannR Markdown aus, wie auf folgendem Screenshot zu sehen ist:
Im folgenden Fenster können Sie getrost die Standardeinstellungenso wie vorgeschlagen belassen, da Sie alles später noch sehr leicht ändernkönnen.
Sie sehen nun eine Datei, das bereits einigen Beispielcode enthält und damitschon einen Großteil der Syntax illustriert.
Ein R-Markdown Dokument besteht in der Regel aus zwei Teilen:dem Titelblock und dem darunter folgenden Dokumentenkörper:
14.3.2 Der Titelblock
Der Titelblock ist immer durch zwei Zeilen mit dem Inhalt “---” oben undunten abgegrenzt.Die Syntax des Titelblocks folgt der SpracheYAML, aber das hat wenigpraktische Relevanz.Im Titelblock werden alle globalen Einstellungen für das Dokument vorgenommen.Für einfache Dokumente muss nur wenig an den Standardeinstellungen geändertwerden, aber im Laufe der Zeit werden Sie merken, dass Sie über den YAML-BlockIhr Dokument zu ganz großen Teilen individualisieren können.In der Regel finden Sie alle Antworten durch Googlen, daher werde ich hier nichtweiter auf den Header eingehen.
14.3.3 Der Textkörper
Der Textkörper besteht aus normalem Text, welcher in der Markdown Syntaxgeschrieben ist, und so genannten Chunks.Für die wirklich einfache Syntax für normalen Text gibt es zahlreiche guteAnleitungen im Internet, z.B. dieses eingängigeCheat Sheet.
Innerhalb der Chunks können Sie Code in einer beliebigen Programmierspracheschreiben, insbesondere auch in R.Die Syntax unterscheidet sich dabei überhaupt nicht von einem normalenR Skript.
Um einen Chunk zu Ihrem Dokument hinzuzufügen klicken Sie oben rechts imSkripbereich auf ‘Insert’ und wählen R aus:
Daraufhin wird an der Stelle des Cursors ein Chunk in Ihr Dokumenteingefügt.Dieser Chunk wird in der ersten und letzten Zeile durch ``` begrenzt.In der ersten Zeile wird zusätzlich innerhalb von geschweiften Klammern dieProgrammiersprache des Chunks definiert:
Darüber hinaus kann das Ausführverhalten für den Chunk durch weitereArgumente innerhalb der geschweiften Klammer weiter spezifiziert werden.
Häufig möchten Sie z.B., dass der Code im Chunk zwar im Dokument angezeigt,aber nicht ausgeführt werden soll.Dies können Sie durch die Option eval=FALSE erreichen.In diesem Fall sähe Ihr Chunk so aus:
In diesem Beispiel wird die Zuweisung x <- 4 bei der Kompillierung desDokuments nicht ausgeführt.
Eine gute Übersicht über die Optionen, die Ihnen offen stehen, finden Siehieroder durch Googlen.
Sie können einzelne Chunks auch schon vor dem Kompillieren des Dokumentsausführen indem Sie auf das Play-Zeichen oben links beim Chunk drücken.Damit erhalten Sie eine Vorschau auf das Ergebnis.
14.3.4 Kompillieren von Dokumenten
Der Prozess, der aus dem Quellcode ihres Dokuments (also allem was in der .RmdDatei geschrieben ist) das fertige Dokument erstellt, wird Kompillieren genannt.Dabei wird aus dem .Rmd Dokument ein gut lesbares .html oder .pdf Dokumenterstellt, wobei alle Chunks normal ausgeführt werden (es sei denn dies wirddurch die Option eval=FALSE verhindert).
Grundsätzlich gibt es zwei Möglichkeiten ein Dokument zu kompillieren:über die entsprechende R-Funktion, oder über den Knit-Button in R-Studio.
Die klassische Variante verwendet die Funktion render() aus dem Paketrmarkdown. Die wichtigsten Argumente sind dabei die folgenden: inputspezifiziert die zu kompillierende .Rmd-Datei, output_format dasfür den Output gewünschte Format97 undoutput_file den Pfad und den Namen der zu erstellenden Outputdatei.
Wenn Sie also das Dokument FirstMarkdown.Rmd kompillieren wollen und denOutput unter Output/OurMarkdown.html als html-Datei speichern wollen,dann können Sie das mit folgendem Code, vorausgesetzt die DateiFirstMarkdown.Rmd liegt im Unterordner R:
rmarkdown::render( input = "R/FirstMarkdown.Rmd", output_format = "html", output_file = "output/FirstMarkdown.html")Weitere Informationen zu den Parametern finden Sie wie immer über die help()Funktion.Alternativ können Sie auch den Button Knit in der R-Studio Oberflächeverwenden.Das ist in der Regel bequemer, lässt aber weniger individuelle Anpassungen zu.
14.4 Relative Pfade in Markdown-Dokumenten
Der problematischste Teil beim Arbeiten mit R-Markdown ist der Umgang mitrelativen Pfaden.Um das Problem zu illustrieren nehmen wir einmal folgende Ordnerstruktur an,wobei der Ordner MarkdownProject unser Arbeitsverzeichnis ist:
Das Problem ist nun, dass wenn Sie eine R-Markdown Datei kompillieren, dieseDatei alle Pfade nicht ausgehend von Ihrem Arbeitsverzeichnisinterpretiert, sondern vom Speicherort der .Rmd-Datei.Das ist natürlich hochproblematisch, denn stellen Sie sich vor, Sie möchtenin Ihrem R-Markdown-Skript die Datei data/BIP-Data.csv einlesen.Normalerweise würden Sie dafür den folgenden Code verwenden:
bip_data <- data.table::fread("data/BIP-Data.csv")Zwar würde der Code in einem R-Skript, z.B. in R/R-Skript.R perfektfunktionieren.In einem R-Markdown Dokument, das nicht im Arbeitsverzeichnis direktgespeichert ist, jedoch nicht.Da in R-Markdown-Dokumenten alle Pfade relativ des Speicherorts des Dokumentsinterpretiert werden, müssten wir hier schreiben:98
bip_data <- data.table::fread("../data/BIP-Data.csv")Das wäre allerdings unschön, weil wir dann unterschiedlichen Codes in Skriptenund in R-Markdown-Dokumenten verwenden müssten und das Ganze dadurch deutlichverwirrender werden würde.
Es wäre also schön, wenn R automatisch wüsste, was das Arbeitsverzeichnis desaktuellen Projekts ist und dieses automatisch berücksichtigt, unabhängig davonob wir mit einem .R oder .Rmd Dokument arbeiten und wo dieses Dokumentinnerhalb unserer Projekt-Struktur gespeichert ist.
Zum Glück können wir genau das mit Hilfe des Paketshereerreichen.99Das Paket enthält eine Funktion here() die als Argument einen Dateinamenoder einen relativen Pfad akzeptiert, und daraus einen absoluten Pfad auf demComputer, auf dem der Code gerade ausgeführt wird, konstruiert.
Wir können also unseren Code von oben einfach folgendermaßen umschreiben:
bip_data <- data.table::fread(here::here("data/BIP-Data.csv"))In dieser Form funktioniert er sowohl in .R als auch .Rmd Dateien ohneProbleme.
Hinweis I: Die Funktion
here()verwendet verschiedene Heuristiken umdas Arbeitsverzeichnis des aktuellen Projekt herauszufinden. Darunter fällt auchdas Suchen nach einer.RprojDatei.Überhaupt funktionieren die Heuristiken in der Regel wunderbar und könnenfür Ihren konkreten Fall über die Funktiondr_here()angezeigt werden.Um ganz sicherzugehen sollte man aber immer in das Arbeitsverzeichnis eineDatei.hereablegen.Diese kann manuell, oder über die Funktionset_here(), erstellt werden.
Hinweis II: Die Verwendung von
here()ist essenziell, wenn Ihre R-Markdown Dokumenteauf mehreren Computern funktionieren sollen. Daher ist die Verwendung in denArbeitsblättern verpflichtend.
14.5 Abschließende Hinweise
Es ist essenziell, dass wir uns das Dokument nach demKompillieren nochmal genau anschauen und überprüfen, dass keine ungewolltenChunks ausgeführt wurden und alle Referenzen stimmen.Die Gefahr, dass wir beim Coden etwas übersehen haben ist sehr groß, daes sich bei Markdown nicht um eine What you see is what you get-Sprachehandelt: das Ergebnis ist nicht live, sondern erst nach dem Kompillierensichtbar.
Ansonsten sollten Sie folgende Aspekte beim Erstellen vonMarkdown-Dokumenten immer beachten:
- Schauen Sie sich das kompillierte Dokument aus der Perspektive derLeser:innen an: ist überflüssiger Code oder überflüssige Informationvorhanden, die Sie eliminieren können? Oft geben wir Tabellen für unsals Zwischenergebnis aus, diese sind dann aber für die finalen Adressateneher störend. Grundsätzlich gilt: nur die nötigsten Ergebnisse undfür das Verständnis essenziellen Code im finalen Dokument belassen.
- Ist das Dokument gut lesbar, oder gibt es Elemente, die den Leseflussstören? Klassische Kandidaten sind Tabellen, die für das gewählt Format zubreit oder sehr lang sind. Reduzieren Sie die Tabellen in diesem Falleauf das Notwendige (z.B. durch Verwendung von
head()oderdplyr::select()). - In der Regel sind Nachrichten (‘messages’) und Warnungen (‘warnings’) zwar für Sie wichtig, aber für Leser:innen eigentlich immer nur störend. Schalten Sie sie daher in den Chunks eher aus. Das geht über die Chunk Optionen
message=FALASE, warning=FALSE, aberam einfachsten als Standardeinstellung am Anfang Ihres Dokuments:
knitr::opts_chunk$set( message = FALSE, warning = FALSE)- Überhaupt kann man sich über die globalen Chunk-Optionen vielTipp-Arbeit sparen. So bietet sich häufig auch
fig.align = 'center'oder sogarecho=FALSEan, wenn Sie Chunks standardmäßig nichtim Markdown anzeigen lassen wollen. - Falls Sie Regressionsoutput in Ihrem Dokument haben: häufig ist derOutput der
summary()Funktion nicht sonderlich schön. Außerdem wird esleicht unübersichtlich wenn Sie mehrere Regressionen ausgeben.Es bietet sich hier häufig die Verwendung von alternativen Paketen wiestargazerodertexregan.Für Tabellen bietet sich ansonsten das Paketxtablean. - Überprüfen Sie ob alle Referenzen (zu Tabellen, Sektionen, etc.) imText vorhanden sind oder Sie etwas vergessen haben. Suchen Sie dazu imfinalen Dokument einfach nach Fragezeichen.
14.6 Weitere Quellen
Eine gute Übersicht über die häufigsten Befehle enthält diesesCheat Sheet.Eine sehr umfangreiche Einführung bietet das Online-BuchR Markdown: The Definitive Guide.Aber auch darüber hinaus finden sich im Internet zahlreiche Beispiele für dieR-Markdown-Syntax.Dieses Skript wurde übrigens inR Bookdown,einer Erweiterung von R-Markdown für Bücher, geschrieben.
R-Markdown Dateien können in sehr vieleverschiedene Formate kompilliert werden, das am häufigsten verwendete Formatist jedoch
html. Eine Übersicht finden Siehier.↩︎Mit
../bewegt man sichbei einem relativen Pfad einen Ordner nach oben.↩︎Tatsächlich ist
heredermaßen praktisch, dass ich empfehle grundsätzlich allePfade in jedem Projekt - ob R-Markdown oder nicht - mit Hilfe vonhereanzugeben.↩︎
