R Markdown Intro
Markdown ist eine sehr einfache Syntax, die es Benutzern erlaubt, aus einfachen Textdateien gut gelayoutete Dokumente zu erstellen. Das Arbeiten mit Markdown bietet zwar nicht so viele Layoutoptionen wie zum Beispiel Microsoft Word, aber dafür sind mit Markdown erstellte Dokumente sehr einheitlich, vergleichbar und vor allem gibt es sehr viel weniger Probleme und Fehlerquellen bezüglich des Layouts.
Viele Benutzer wollen einfach schnell Dokumente erstellen, die ein vernünftiges Layout aufweisen, ohne dabei einen hohen Aufwand betreiben zu müssen. Markdown kann in solchen Fällen eine große Hilfe sein und erfreut sich daher seit einiger Zeit sehr großer Beliebtheit. Es gibt natürlich auch andere Varianten, um mittels Syntax gelayoutete Dokumente zu erstellen. Ein prominentes Beispiel hierfür ist LaTeX, welches sehr viel mehr Gestaltungsoptionen bietet als Markdown, dafür aber auch viel komplexer und entsprechend schwerer zu Erlenen ist. Besonders, wenn es um die schnelle Erstellung ganz einfacher Dokumente geht, ist Markdown daher das Mittel der Wahl.
Um Markdowndokumente zu erstellen benötigt man im Prinzip nur einen ganz einfachen Texteditor. Wünschenswert ist allerdings ein Programm, welches zum einen die Markdown Syntax hervorhebt (Syntaxhighlighting) und zum anderen die Option bietet, aus geschriebenen Markdown Code ein gerendertes Dokument zu erstellen.
Eine Datei, die in der Markdown Syntax geschrieben wurde, wird erst durch Rendern zu einem fertig gelayouteten Dokument!
Durch das Rendern wird aus dem einfachen Textdokument eine HTML-Datei erzeugt, in der die Markdown Syntax interpretiert wird, um so das Dokument entsprechend der Anweisungen zu layouten. Wie man z.B. mit RStudio Markdowndokumente rendert, wird weiter unten in dieser Einführung erläutert.
In Markdowndokumenten gibt es verschiedene Befehlszeichen, die jeweils unterschiedliche Layoutanweisungen darstellen. Im Folgenden werden die wichtigsten dieser Befehle vorgestellt und erläutert. Eine sehr gute Einführung gibt es ebenfalls auf dieser Webseite:
-
Um Text in fetter Schrift hervorzuheben umschließt man die entsprechende Textstelle mit zwei ** auf jeder Seite:
Aus **Beispiel** wird so Beispiel
-
Um Text in kursiver Schrift hervorzuheben umschließt man die entsprechende Textstelle mit einem * auf jeder Seite:
Aus *Beispiel* wird so Beispiel
-
Um Text in durchgestrichen dazustellen umschließt man die entsprechende Textstelle mit zwei ~ auf jeder Seite:
Aus ~~Beispiel~~ wird so
Beispiel -
Statt der * kann man auch Unterstriche, also _ verwenden:
Aus __Beispiel__ wird so Beispiel
Aus _Beispiel_ wird so Beispiel
Aus *__Beispiel__* wird so Beispiel (Fett und gleichzeitig kursiv durch Verwenden beider Zeichen)
Wir können durch Verwendung von * auch einfache nicht nummerierte Listen erstellen. Markdown erkennt * als Listenzeichen, wenn danach ein Leerzeichen folgt:
* Eintrag
* Eintrag
* Eintrag
wird zu:
- Eintrag
- Eintrag
- Eintrag
Wir können auch nummerierte Listen erstellen, in dem wir 1., 2., 3., usw. verwenden:
1. Eintrag
2. Eintrag
3. Eintrag
wird zu:
- Eintrag
- Eintrag
- Eintrag
Markdown bietet eine schöne und einfache Möglichkeit, um schnell kleine Tabellen zu erstellen. Dazu schreiben wir zunächst die Spaltennamen nebeneinander, getrennt durch |. In der Zeile darunter folgt die eigentliche Tabellenkonfiguration. Wir beschreiben jede Spalte mit - - - und trennen die Bindestrichte wie auch in der Zeile der Spaltennamen mit |. In den Zeilen darunter folgen dann die Einträge in die Tabelle, getrennt durch | wie zuvor schon. Das Ganze sieht dann wie folgt aus:
Test|Test|Test
---|---|---
1|2|3
1|2|3
1|2|3
wird zu:
| Test | Test | Test |
|---|---|---|
| 1 | 2 | 3 |
| 1 | 2 | 3 |
| 1 | 2 | 3 |
Wir können die Ausrichtung der einzelnen Spalten kontrollieren, in dem wir : in der Konfigurationszeile verwenden. Ein : links bedeutet linksbündige Ausrichtung (Standardeinstellung auch ohne :), ein : rechts bedeutet rechtsbündige Ausrichtung. Ein : sowohl links als auch rechts bedeutet eine Zentrierung der Zelleninhalte:
Test|Test|Test
:---|:---:|---:
l|z|r
l|z|r
l|z|r
wird zu:
| Test | Test | Test |
|---|---|---|
| l | z | r |
| l | z | r |
| l | z | r |
Mit Hilfe von # lassen sich einfach Überschriften in Markdowndokumenten erstellen. Mehrere # bedeuten eine untergeordnete Ebene von Überschriften. Nach den # muss ein Leerzeichen sein, damit die Überschriften korrekt erkannt werden:
# Ebene 1
## Ebene 2
### Ebene 3
#### Ebene 4
##### Ebene 5
###### Ebene 6
wird zu:
In Markdowndokumente können sehr leicht Links zu Webseiten eingebaut werden, indem man folgenden Code benutzt:
[Meine Github Seite](http://www.github.com/ctreffe)
In den eckigen Klammern steht der Text, welcher später mit dem Link hinterlegt ist (auf den man also klicken muss, um zur verlinkten Seite zu kommen). In den runden Klammern dahinter steht dann die URL, auf die der Link zeigen soll. Im gerenderten Dokument sieht das wie folgt aus:
Das einfügen von Bildern unterscheidet sich kaum vom Einfügen eines Links. Wichtig ist, dass die Bildatei auf einem Webserver liegt, so dass eine Webadresse hinterlegt werden kann:
wird zu
Vor Bildlinks muss ein ! gesetzt werden. In den eckigen Klammern dahinter steht ein Alternativtext, der angezeigt werden kann, wenn das Bild unter der angegebenen Adresse nicht verfügbar ist. In den runden Klammern folgt der Link zur Bildatei. Bei lokalen Markdowndokumenten kann das auch ein normaler Systempfad sein.
Innerhalb von Markdowndokumenten lassen sich auch normale HTML-Tags verwenden, mit denen man Texte, Links, Bilder, etc. formatieren kann. So lassen sich zusätzliche Darstellungsmöglichkeiten nutzen, die HTML bietet:
<font color="red">Farbiges Textbeispiel</font>wird zu
Farbiges Textbeispiel
<font size="5">Großes Textbeispiel</font>wird zu
Großes Textbeispiel
<a href="www.github.com/ctreffe">Meine Github Seite</a>wird zu
Da Markdowndokumente durch das Rendering in Webseiten umgewandelt werden, können HTML-Tags wie man sieht ohne Probleme mitverarbeitet werden. Je nach dem verwendeten Rendering-Tool sind aber eventuell nicht alle HTML-Features oder Objekte verfügbar (z.B. gibt es auf github.com keine iframes und einige Konfigurationsparameter in HTML-Tags werden ignoriert).
Da Markdown Bildlinks keinerlei Konfigurationsmöglichkeiten bezüglich der Anzeige von Bildern bieten, kann es in vielen Fällen sinnvoll sein statt einem Markdown Bildlink einen einfachen HTML Bildlink in Markdowndokumenten zu verwenden. Der größte Vorteil ist dabei die einstellbare Bildgröße:
<img src="http://e-scientifics.de/content/example_kinderbild.jpg" alt="example" width="100">wird zu
Ein großer Vorteil von Markdown ist die Möglichkeit ganze Blöcke von Programmcode unterschiedlicher Programmiersprachen als einheitlichen Block darzustellen und in den meisten Fällen auch die entsprechende Syntax so hervorzuheben, wie es von den meisten Entwicklungsprogrammen ebenfalls gemacht wird. Codeblocke wie folgt gekennzeichnet:
Eine Zeile über dem Block: ```
Eine Zeile unter dem Block: ```
Um nun das Syntaxhighlighting zu aktivieren braucht man lediglich die verwendete Programmiersprache zu Beginn eines Codeblocks zu deklarieren:
Ein Beispiel geschrieben mit r!
Eine Zeile über dem Block: ```s
Eine Zeile unter dem Block: ```
Im folgenden Codeblock ist nun das R Syntaxhighlighting aktiviert. Zahlen werden und Strings (also Zeichenketten, die von " umschlossen werden) werden nun z.B. in unterschiedlichen Farben hervorgehoben. Kommentare werden ebenfalls anders dargestellt. Wie genau ein Codeblock mit aktiviertem Syntaxhighlighting dargestellt wird, hängt von der zum Rendern benutzten Software ab:
s = "R syntax highlighting"
n = 100 # Dies ist ein KommentarCodeblöcke mit Syntaxhighlighting machen Markdown zu einem tollen Werkzeug, mit dem Programmierer Anleitungen schreiben oder Code dokumentieren können. Ohne viel Aufwand erhält man so gelayoutete und präsentierbare Dokumente, die übersichtlich gestaltet und gut strukturiert sind. Diese Eigenschaften von Markdown sind auch für das Arbeiten mit R sehr interessant.
Die Arbeit mit R beinhaltet in aller Regel das Erstellen von Skripten mit der R Syntax. R Skripte werden aber nicht automatisch gerendert und bieten kaum Layoutmöglichkeiten (Außer durch das Arbeiten mit Kommentarzeilen etc.), da es sich hier um reine Textdokumente handelt.
R Markdown wurde entwickelt, um auch R Skripte in präsentierbare Dokumente umwandeln zu können. Im Prinzip handelt es sich bei Dokumenten, die in R Markdown erstellt werden, um ganz normale Markdowndokumente, in die spezielle R Codeblöcke integriert werden. Die Codeblöcke in R Markdowndokumenten nennen wir Chunks. R Markdown Chunks unterscheiden sich von herkömmlichen R Codeblöcken (wie weiter oben beschrieben) nur durch eine andere Syntaxdeklaration:
Ein R Chunk startet mit: ```{r}
Der Chunk endet mit: ```
Im restlichen Skript werden wir R Chunks immer wie folgt darstellen:
` ` `{r}
` ` `
Dabei ist zu beachten, dass in einem R Chunk keine Leerzeichen zwischen die `` gehören. Wir machen das im Folgenden nur, damit wir der Chunk-Code korrekt angezeigt werden kann. Wir sehen nun, dass ein R Chunk zunächst einmal genau so dargestellt wird, wie ein normaler R Codeblock:
s = "R syntax highlighting"
n = 100Es gibt aber einen ersten wichtigen Unterschied, der zwar nicht aus dem gerenderten Dokument, wohl aber aus der RStudio Oberfläche ersichtlich ist. R Chunks werden anders dargestellt als herkömmliche R Codeblöcke.
Hier ein Screenshot von einem Chunk und einem Codeblock in der RStudio Oberfläche:
Wie man sieht wird der R Chunk von RStudio farblich unterlegt, während der herkömmliche Codeblock nicht weiter hervorgehoben wird. Zusätzlich haben wir im R Chunk Syntaxhighlighting für den Code. Dennoch sehen beide Codeblöcke im gerenderten Dokument identisch aus (siehe den Codeblock über dem Screenshot)!
Bislang haben wir gesehen, dass sich R Chunks zumindest in ihrem Aussehen in RStudio von herkömmlichen R Codeblöcken unterscheiden. Der wesentliche Unterschied zwischen Chunks und normalen Codeblöcken liegt aber darin, dass R Code in Chunks ausgeführt wird, bevor ein gerendertes R Markdowndokument erstellt wird. Das Ergebnis der Codeausführung, welches in der R-Konsole angezeigt wird, wird dann ebenfalls in unserem gerenderten Markdowndokument als Codebblock dargestellt:
n = 100
n + n + n## [1] 300
Wir sehen in der unteren Box die Konsolenausgabe, die wir auch durch Ausführen eines normalen R-Skripts erhalten würden. Durch diese Ausführung des R Codes lassen sich nun Dokumente erzeugen, die durch Markdown gelayoutet werden und zusätzlich R Code und dessen Ergebnisse enthalten. Dadurch haben Benutzer z. B. die Möglichkeit dynamischer Ergebnisberichte zu erstellen und können R Skripte und auch die Konsolenausgabe mit gelayouteten Texten stark aufwerten, was Struktur, Beschreibung und Übersichtlichkeit angeht.
In Ergebnisberichten iinteressieren uns häufig nur die Ergebnisse statistischer Analysen, nicht aber die R-Syntax, die der Analyse zu Grunde liegt. Daher lässt sich für jedes Chunk mit R Code einstellen, ob es im gerenderten Dokument angezeigt werden soll, oder eben nicht. Hierzu übergeben wir dem R Chunk den zusätzlichen Parameter echo und setzen diesen auf FALSE:
` ` `{r, echo=FALSE}
` ` `
## [1] 300
Wie wir sehen wird nun lediglich das Ergebnis aus der R-Konsole angezeigt, nicht aber die eigentliche Syntax.
Wir können R Chunks durch die Übergabe zusätzlicher Parameter in der Chunkdeklaration auch so konfigurieren, dass keine Ausführung des eigentlichen R Codes stattfindet. Dies ist oftmals der Fall, wenn wir in Anleitungen oder Skripten Beispiele für fehlerhaften R-Code anzeigen wollen, ohne die entstehenden Fehlermeldungen zu erhalten. Der Parameter eval ermöglicht es uns, die Ausführung des Codeblocks zu unterbinden und diesen lediglich anzuzeigen:
` ` `{r, eval=FALSE}
` ` `
n = 100
n + n + nNun wird uns lediglich die Syntax und nicht das Ergebnis einer Ausführung angezeigt.
Bislang haben wir nur die Möglichkeit kennen gelernt uns in R Markdowndokumenten Codeblöcke anzeigen zu lassen, die exakt das enthalten, was die Konsole uns bei einer normalen Ausführung des Chunks als R Skript zurückmelden würde. Wir können für die Darstellung von Ergebnissen in R Markdown Dokumenten aber auch zusätzliche Wege nutzen, die die Darstellung weiter verbessern. Eine Möglichkeit ist hierbei der direkte Zugriff aus der Markdown Syntax auf Variablen, die in R Chunks erzeugt wurden. Dieses wird durch inline Codeblöcke ermöglicht.
n = 100
# Ein inline Codeblock: `r n`Wenn wir den inline Codeblock in unsere Markdown Syntax einfügen erhalten wir den Wert der Variablen n im Text:
Der Wert von n beträgt: 100
Auf diese Art und Weise lassen sich natürlich auch einzelne Ergebnisse von statistischen Analysen im Text darstellen oder innerhalb von Markdown Tabellen. Somit sind Benutzer nicht mehr nur auf den Konsolen-Output bei der Darstellung ihrer Ergebnisse angewiesen.
Zusätzlich zu der Möglichkeit, eigene Tabellen für die Darstellung von Daten und Ergebnissen mittels Markdown zu bauen, bietet die Bibliothek pander die Möglichkeit eine Vielzahl von R Objekten in fertige Markdown Tabellen umzuwandeln. Damit die ausgegebenen Tabellen allerdings auch als Markdown gerendert werden und nicht als Konsolen-Output, muss ein R Chunk so konfiguriert werden, dass sein Ergebnis als Markdown interpretiert wird. Dies erreicht man mit dem zusätzlichen Parameter results, dem man den wert 'asis' zuweisen muss.
Im R Chunk selbst wird nach dem Laden der Bibliothek der Befehl pander() verfügbar. Damit pander() uns eine Tablle ausgibt, die mit R Markdown kompatibel ist, muss mit Hilfe des Parameters style noch die Ausgabe auf R Markdown umgestellt werden (style="rmarkdown"). Im folgenden Beispiel werden die ersten 5 Spalten des mtcars Datensatzes als Markdown Tabelle ausgegeben:
` ` `{r, results='asis'}
` ` `
library(pander)## Warning: package 'pander' was built under R version 3.0.3
##
## Attaching package: 'pander'
##
## Das folgende Objekt ist maskiert from 'package:knitr':
##
## pandoc
pander(mtcars[, 1:5], style = "rmarkdown")| mpg | cyl | disp | hp | drat | |
|---|---|---|---|---|---|
| Mazda RX4 | 21 | 6 | 160 | 110 | 3.9 |
| Mazda RX4 Wag | 21 | 6 | 160 | 110 | 3.9 |
| Datsun 710 | 22.8 | 4 | 108 | 93 | 3.85 |
| Hornet 4 Drive | 21.4 | 6 | 258 | 110 | 3.08 |
| Hornet Sportabout | 18.7 | 8 | 360 | 175 | 3.15 |
| Valiant | 18.1 | 6 | 225 | 105 | 2.76 |
| Duster 360 | 14.3 | 8 | 360 | 245 | 3.21 |
| Merc 240D | 24.4 | 4 | 146.7 | 62 | 3.69 |
| Merc 230 | 22.8 | 4 | 140.8 | 95 | 3.92 |
| Merc 280 | 19.2 | 6 | 167.6 | 123 | 3.92 |
| Merc 280C | 17.8 | 6 | 167.6 | 123 | 3.92 |
| Merc 450SE | 16.4 | 8 | 275.8 | 180 | 3.07 |
| Merc 450SL | 17.3 | 8 | 275.8 | 180 | 3.07 |
| Merc 450SLC | 15.2 | 8 | 275.8 | 180 | 3.07 |
| Cadillac Fleetwood | 10.4 | 8 | 472 | 205 | 2.93 |
| Lincoln Continental | 10.4 | 8 | 460 | 215 | 3 |
| Chrysler Imperial | 14.7 | 8 | 440 | 230 | 3.23 |
| Fiat 128 | 32.4 | 4 | 78.7 | 66 | 4.08 |
| Honda Civic | 30.4 | 4 | 75.7 | 52 | 4.93 |
| Toyota Corolla | 33.9 | 4 | 71.1 | 65 | 4.22 |
| Toyota Corona | 21.5 | 4 | 120.1 | 97 | 3.7 |
| Dodge Challenger | 15.5 | 8 | 318 | 150 | 2.76 |
| AMC Javelin | 15.2 | 8 | 304 | 150 | 3.15 |
| Camaro Z28 | 13.3 | 8 | 350 | 245 | 3.73 |
| Pontiac Firebird | 19.2 | 8 | 400 | 175 | 3.08 |
| Fiat X1-9 | 27.3 | 4 | 79 | 66 | 4.08 |
| Porsche 914-2 | 26 | 4 | 120.3 | 91 | 4.43 |
| Lotus Europa | 30.4 | 4 | 95.1 | 113 | 3.77 |
| Ford Pantera L | 15.8 | 8 | 351 | 264 | 4.22 |
| Ferrari Dino | 19.7 | 6 | 145 | 175 | 3.62 |
| Maserati Bora | 15 | 8 | 301 | 335 | 3.54 |
| Volvo 142E | 21.4 | 4 | 121 | 109 | 4.11 |
Pander ermöglicht über eine Vielzahl von Optionen das Aussehen und Verhalten von Tabellen zu beeinflussen. Ein Beispiel ist die Möglichkeit, bestimmte Reihen oder Zeilen in fetter Schrift darzustellen:
emphasize.strong.cols(2) # Fette Schrift
emphasize.rows(3) # Kursive Schrift
pander(mtcars[, 1:5], style = "rmarkdown")| mpg | cyl | disp | hp | drat | |
|---|---|---|---|---|---|
| Mazda RX4 | 21 | 6 | 160 | 110 | 3.9 |
| Mazda RX4 Wag | 21 | 6 | 160 | 110 | 3.9 |
| Datsun 710 | 22.8 | 4 | 108 | 93 | 3.85 |
| Hornet 4 Drive | 21.4 | 6 | 258 | 110 | 3.08 |
| Hornet Sportabout | 18.7 | 8 | 360 | 175 | 3.15 |
| Valiant | 18.1 | 6 | 225 | 105 | 2.76 |
| Duster 360 | 14.3 | 8 | 360 | 245 | 3.21 |
| Merc 240D | 24.4 | 4 | 146.7 | 62 | 3.69 |
| Merc 230 | 22.8 | 4 | 140.8 | 95 | 3.92 |
| Merc 280 | 19.2 | 6 | 167.6 | 123 | 3.92 |
| Merc 280C | 17.8 | 6 | 167.6 | 123 | 3.92 |
| Merc 450SE | 16.4 | 8 | 275.8 | 180 | 3.07 |
| Merc 450SL | 17.3 | 8 | 275.8 | 180 | 3.07 |
| Merc 450SLC | 15.2 | 8 | 275.8 | 180 | 3.07 |
| Cadillac Fleetwood | 10.4 | 8 | 472 | 205 | 2.93 |
| Lincoln Continental | 10.4 | 8 | 460 | 215 | 3 |
| Chrysler Imperial | 14.7 | 8 | 440 | 230 | 3.23 |
| Fiat 128 | 32.4 | 4 | 78.7 | 66 | 4.08 |
| Honda Civic | 30.4 | 4 | 75.7 | 52 | 4.93 |
| Toyota Corolla | 33.9 | 4 | 71.1 | 65 | 4.22 |
| Toyota Corona | 21.5 | 4 | 120.1 | 97 | 3.7 |
| Dodge Challenger | 15.5 | 8 | 318 | 150 | 2.76 |
| AMC Javelin | 15.2 | 8 | 304 | 150 | 3.15 |
| Camaro Z28 | 13.3 | 8 | 350 | 245 | 3.73 |
| Pontiac Firebird | 19.2 | 8 | 400 | 175 | 3.08 |
| Fiat X1-9 | 27.3 | 4 | 79 | 66 | 4.08 |
| Porsche 914-2 | 26 | 4 | 120.3 | 91 | 4.43 |
| Lotus Europa | 30.4 | 4 | 95.1 | 113 | 3.77 |
| Ford Pantera L | 15.8 | 8 | 351 | 264 | 4.22 |
| Ferrari Dino | 19.7 | 6 | 145 | 175 | 3.62 |
| Maserati Bora | 15 | 8 | 301 | 335 | 3.54 |
| Volvo 142E | 21.4 | 4 | 121 | 109 | 4.11 |
Darüber hinaus bietet die Funktion panderOptions() weitere Einstellungsmöglichkeiten, die die Darstellung verändern. IM folgenden Beispiel wird die Anzahl an Zeichen, ab der eine Tabelle in mehrere Tabellen (die dann untereinander dargestellt werden) aufgeteilt wird. So lassen sich mehr Spalten aus dem mtcars Datensatz in einer Tabelle anzeigen als zuvor.
Standardmäßig beträgt die Anzahl von Zeichen in einer Spalte, aber der eine Tabelle von pander geteilt wird, genau 80. Dadurch werden oftmals tabellen geteilt, die eigentlich komfortabel ungeteilt angezeigt werden könnten:
pander(mtcars[1:5, 1:8], style = "rmarkdown")| mpg | cyl | disp | hp | drat | |
|---|---|---|---|---|---|
| Mazda RX4 | 21 | 6 | 160 | 110 | 3.9 |
| Mazda RX4 Wag | 21 | 6 | 160 | 110 | 3.9 |
| Datsun 710 | 22.8 | 4 | 108 | 93 | 3.85 |
| Hornet 4 Drive | 21.4 | 6 | 258 | 110 | 3.08 |
| Hornet Sportabout | 18.7 | 8 | 360 | 175 | 3.15 |
Table: Table continues below
| wt | qsec | vs | |
|---|---|---|---|
| Mazda RX4 | 2.62 | 16.46 | 0 |
| Mazda RX4 Wag | 2.875 | 17.02 | 0 |
| Datsun 710 | 2.32 | 18.61 | 1 |
| Hornet 4 Drive | 3.215 | 19.44 | 1 |
| Hornet Sportabout | 3.44 | 17.02 | 0 |
Durch das erhöhen der Zeichenzahl pro Zeile auf 120 über panderOptions() lässt sich die gleiche Tabelle ungeteilt darstellen:
panderOptions("table.split.table", 120)
pander(mtcars[1:5, 1:8], style = "rmarkdown")| mpg | cyl | disp | hp | drat | wt | qsec | vs | |
|---|---|---|---|---|---|---|---|---|
| Mazda RX4 | 21 | 6 | 160 | 110 | 3.9 | 2.62 | 16.46 | 0 |
| Mazda RX4 Wag | 21 | 6 | 160 | 110 | 3.9 | 2.875 | 17.02 | 0 |
| Datsun 710 | 22.8 | 4 | 108 | 93 | 3.85 | 2.32 | 18.61 | 1 |
| Hornet 4 Drive | 21.4 | 6 | 258 | 110 | 3.08 | 3.215 | 19.44 | 1 |
| Hornet Sportabout | 18.7 | 8 | 360 | 175 | 3.15 | 3.44 | 17.02 | 0 |
Pander ermöglicht auch die Ausgabe von verschiedenen R Ergebnisobjekten. Die Ergebnisse von Regressions- oder Varianzanalysen lassen sich so komfortable in Tabellenform ausgeben:
pander(t.test(mpg ~ vs, data = mtcars), style = "rmarkdown")| Test statistic | df | P value | Alternative hypothesis |
|---|---|---|---|
| -4.667 | 22.72 | 0.0001098 * * * | two.sided |
Table: Welch Two Sample t-test: mpg by vs
pander(aov(mpg ~ vs + cyl, data = mtcars), style = "rmarkdown")| Df | Sum Sq | Mean Sq | F value | Pr(>F) | |
|---|---|---|---|---|---|
| vs | 1 | 496.5 | 496.5 | 47.06 | 1.551e-07 |
| cyl | 1 | 323.6 | 323.6 | 30.67 | 5.695e-06 |
| Residuals | 29 | 306 | 10.55 |
Table: Analysis of Variance Model
Es gibt aktuell ein Problem mit der Darstellung von Regressionsanalysen! In diesem Fall muss die Ausgabe von pander nachbearbeitet werden (Alle | müssen Aus den Kofpzeilen genommen werden.), da die Darstellung ansonsten fehlerhaft ist. Im folgenden Beispiel steht der Ausdruck Pr(>|t|) in einem Spaltenkopf. Da | von R Markdown fälschlicherweise als Steuerzeichen in der Tabelle erkannt wird, wird diese nun nicht mehr richtig dargestellt:
pander(lm(mpg ~ vs, data = mtcars), style = "rmarkdown")| Estimate | Std. Error | t value | Pr(>|t|) | |
|---|---|---|---|---|
| vs | 7.94 | 1.632 | 4.864 | 3.416e-05 |
| (Intercept) | 16.62 | 1.08 | 15.39 | 8.847e-16 |
Table: Fitting linear model: mpg ~ vs
Umgehen lässt sich der Fehler momentan nur, in dem man die normale pander Ausgabe nachträglich bearbeitet. Dazu muss die Ausgabe mittels pander.return() in eine eigene Variable gespeichert werden. Daraufhin lassen sich einzelne Elemente der Tabelle mit gsub() ersetzen. Zum Schluss wird die bearbeitete Tabelle mit cat() ausgegeben, wobei auf die korrekte Einstellung von sep geachtet werden muss:
pander_out <- pander.return(lm(mpg ~ vs, data = mtcars), style = "rmarkdown") # Abfangen der normalen pander Ausgabe
test <- gsub(">.t.", ">t", pander_out) # Ersetzen der problematischen Zeichen
cat(test, sep = "\n") # Erneute Ausgabe der Tabelle mit geeignetem sep Parameterwert| Estimate | Std. Error | t value | Pr(>|t|) | |
|---|---|---|---|---|
| vs | 7.94 | 1.632 | 4.864 | 3.416e-05 |
| (Intercept) | 16.62 | 1.08 | 15.39 | 8.847e-16 |
Table: Fitting linear model: mpg ~ vs
So lassen sich momentane Probleme mit der pander Ausgabe beseitigen. Es gibt noch sehr viele weitere Optionen und Funktionen, im pander Paket. Für eine komplette Übersicht eignet sich die offizielle pander Referenz:
Um in RStudio eine neue R Markdowndatei (Dateieindung .rmd) zu erstellen benutzen wir einfach das Systemmenü:
Hier ein Screenshot eines neu erstellten R Markdowndokuments mit dem Standardinhalt, der einfach gelöscht werden kann:
Um ein R Markdowndokument zu rendern (also ein gelayoutetes HTML-Dokument zu erstellen), klicken wir auf den entsprechenden Button oben am Skript:
RStudio zeigt uns die gerenderte HTML-Datei in einem neuen Fenster an:
In RStudio lassen sich R Chunks genau so ausführen wie normale R-Skripte. Das bedeutet, dass man als Benutzer nicht immer erst das Markdowndokument rendern lassen muss, um zu sehen, ob der eigene R Code funktioniert. Es gibt zwei nützliche Tastenkombinationen, die die Arbeit mit R Markdown in RStudio sehr vereinfachen:
- Mit STRG+ALT+C lässt sich der Chunk ausführen, in dem der Cursor sich momentan befindet
- Mit STRG+ALT+R lassen sich alle Chunks im R Markdowndokument nacheinander ausführen (Also ganzes Script ausführen!)
Allerdings kann man keine Markdownabschnitte ausführen, dies führt einfach zu Fehlermeldungen in der R-Konsole. Hier noch eine offizielle Einführung in R Markdown von der RStudio Webseite:
R Markdowndokumente werden von RStudio beim Rendern zunächst in normale Markdowndokumente und dann erst in HTML-Dokumente umgewandelt. Die enstehenden Markdowndokumente werden dabei automatisch in dem Ordner mit abgespeichert, in dem sich auch die Rmd-Datei des R Markdowndokumentes befindet. Diese Markdowndatei kann genutzt werden, um R Markdowndokumente z.B. auf github.com in ein Wiki einzubinden, genau wie das vorliegende Skript. Bevor allerdings ein Upload zu Github möglich ist, muss das Markdowndokument vorbereitet werden und auch schon bei der Erstellung des R Markdowndokuments kann dafür gesorgt werden, dass die Anpassung später unproblematisch ist.
Ein R Markdowndokument, welches später als einfaches Markdowndokument genutzt werden soll, z.B. für den Upload auf Github, sollte so gestaltet werden, dass später möglichst wenig händische Anpassungen des von RStudio erstellten Markdowndokuments notwendig sind. Das hat vor allem den Grund, dass bei jeder Änderung des R Markdowndokumentes zunächst ein neues einfaches Markdowndokument erstellt wird, welches dann jedes Mal wieder aufs Neue angepasst werden muss. Dadurch vereinfacht sich der Umgang mit den entsprechenden Dokumenten enorm. In den folgenden Abschnitten werden einige Möglichkeiten beschrieben, die den späteren Anpassungsaufwand verringern.
Screenshots und andere externe Bilddateien, die in einem R Markdowndokument verwendet werden sollen, können bereits in RStudio sowohl von lokalen Quellen als auch von Online-Quellen geladen werden. Da beim späteren Upload eines Markdowndokuments auf Github keine lokalen Quellen mehr zur Verfügung stehen, sollte man externe Bilddateien immer schon im R Markdowndokument aus einer Online-Quelle laden. Dadurch entfällt später die Notwendigkeit, die lokalen Bildlinks im Markdowndokument durch Links zu Online-Quellen zu ersetzen.
Bei der Erstellung von Plots in R Markdowndokumenten generiert RStudio lokale Bilddateien (meistens im Unterordner figure, der im selben Ordner liegt wie die entsprechende Rmd-Datei), welche dann als lokale Bildlinks in das einfache Markdowndokument eingebunden werden. Bevor Benutzer also Markdowndokumente mit Plots auf Github online stellen können, müssen diese lokalen Bildlinks in den von RStudio erstellten Markdowndokumenten durch Online-Bildlinks ersetzt werden. Andernfalls würden die Plots auf Github später nicht angezeigt. Die entsprechenden Bilddateien, die R-Studio erstellt, müssen dementsprechend auf einen Server hochgeladen werden, von dem aus sie dann als Online-Quelle erreichbar sind.
Eine Möglichkeit, wie Benutzer verhindern können, diesen aufwendigen Anpassungsprozess bei jeder Veränderung des R Markdowndokuments erneut durchzuführen, ist die Vorab-Einbindung der entsprechenden R Plots als externen Bildlink. Hierzu nehmen wir zunächst ein einfaches Plot-Beispiel aus dem mtcars Datensatz:
plot(mtcars$mpg, mtcars$cyl, main = "Beispielplot")
Jeder R plot sollte in R Markdowndokumenten in einem gesonderten Chunk erstellt werden, innerhalb dessen keine anderen Berechnungen und Anweisungen ausgeführt werden, als solche, die zur Erstellung des Plots notwendig sind. Der obige Codeblock enthält ausschließlich den Befehl plot() zur Erstellung einer einfachen Grafik. Sobald der Chunk fertiggestellt wurde und das R Markdowndokument von RStudio einmal gerendert worden ist, befindet sich die von RStudio erstellte Bilddatei mit dem Plot wie bereits erläutert im Unterordner "figure" des Ordners, in dem auch die Rmd-Datei liegt. Diese Bilddatei kann nun auf einen Server hochgeladen werden, von dem aus sie als Online-Quelle erreichbar ist. Anschließend kann der Plot einfach als externes Bild in das R Markdowndokument direkt unterhalb des R Chunks eingebunden werden, in dem der Plot zuvor erstellt wurde. Damit nun beim erneuten Rendern nicht zwei Plots im Markdowndokument erscheinen kann einfach die Chunkoption eval auf FALSE gesetzt werden. Der Chunk, welcher die Plotanweisung erhält, wird nun von RStudio beim Rendern nicht mehr ausgewertet und dennoch erscheint der zuvor als Online-Quelle eingebundene Plot. Ob der Codeblock darüber hinaus angezeigt werden soll oder nicht, kann der Benutzer mit der Chunkoption echo bestimmen. Hier ein Beispiel für den entsprechenden Code im R Markdowndokument:
` ` `{r, eval=FALSE}
plot(mtcars$mpg, mtcars$cyl, main='Beispielplot')
` ` `
wird zu
plot(mtcars$mpg, mtcars$cyl, main = "Beispielplot")Wie wir sehen entspricht die untere Darstellung des Codeblocks und des Plots exakt der oberen Darstellung, bei der die Bilddatei auf herkömmlichem Wege in das R-Markdowndokument eingebettet wurde. In der unteren Variante ist allerdings keinerlei Anpassung des einfachen Markdowndokumentes notwendig, während bei der oberen Variante wie beschrieben vor dem Upload auf Github die Ersetzung der lokalen Bildlinks durch Online-Quellen vorgenommen werden musste. Wenn man bei der Erstellung von R Markdowndokumenten mit Plots entsprechend der obigen Beschreibung vorgeht, muss man eine wichtige Sache beachten:
Bei jeder Veränderung des Plots muss dieser neu erstellt und hochgeladen werden, da ein Markdowndokument auf Github sonst mit veralteten Grafiken dargestellt würde!
Es bietet sich deshalb an, die Chunkoption eval bei der Erstellung des Skripts zunächst auf TRUE zu belassen. Dadurch werden zwar immer zwei Plots statt einem angezeigt, aber man hat sofort den Vergleich der Online-Quelle mit dem lokalen Plot und kann sehen, welche Online-Plots aktualisiert werden müssen. Erst unmittelbar vor dem finalen Rendering des fertigen Dokuments kann man dann eval auf FALSE setzen.
Nachdem RStudio aus dem R Markdowndokument ein einfaches Markdowndokument erstellt hat, müssen alle lokalen Bildlinks müssen durch Bildlinks zu Online-Quellen ersetzt werden, bevor ein Upload auf Github erfolgen kann. Sofern sich Benutzer an die vorherigen Hinweise und Beschreibungen gehalten haben, sollte dieser Punkt jedoch entfallen.
Zuletzt muss eine Veränderung an den R Codeblöcken vorgenommen werden, damit das Syntaxhighlighting auch auf Github funktioniert. Die Kennzeichnung der Codeblöcke mit r wird von Github nicht verstanden, daher muss der Alias s für das korrekte Syntaxhighlighting genutzt werden:
` ` `r
` ` `
muss ersetzt werden durch:
` ` `s
` ` `
Dies lässt sich sehr leicht mit der Suchen-und-Ersetzen-Funktion eines beliebigen Editors durchführen. Dabei braucht nur der Anfang des Codeblocks verändert zu werden. Sobald die Codeblöcke im einfachen Markdowndokument entsprechend angepasst wurden, kann der Upload auf Github erfolgen.