R Lernplattform - 25  R Markdown (2024)

25.1.1 YAML

Gehen wir nochmal einen Schritt zurück und schauen uns das Rmd genauer an. Der Code ganz oben im Dokument ist der YAML Header. In diesem legen wir globale Dokument-Optionen fest. Nachfolgend sehen wir einige.

Achtung: Standardmäßig steht hier output: html-document (bzw. output: pdf_document oder output: word_document) hintereinander in einer Zeile. Um weitere YAML Optionen ergänzen zu können, müssen wir html_document (bzw. pdf_document oder word_document) in eine neue Zeile schreiben und einen Doppelpunkt dahinter ergänzen. Die YAML Optionen kommen jeweils auch in eine eigene Zeile.

Mit toc: true können wir eine Gliederung (table of contents) einfügen.

Diese können wir permanent anzeigen lassen, sodass sie trotz Scrollen immer an der gleichen Stelle (links) bleibt. Dazu ergänzen wir toc_float: true.

Achtung: Diese Option funktioniert nur in html.

Wir können unsere Überschriften auch automatisch nummerieren lassen indem wir number_sections: true nutzen.

Die Gestaltung können wir mit der Option theme anpassen. Hier wurde das Theme journal genutzt. Hier finden wir eine Übersicht über alle bestehenden Möglichkeiten.

Achtung: Diese Option funktioniert nur in html.

Einen Überblick über bestehende YAML Optionen finden wir hier.

25.2.1 Überschriften

Um Überschriften zu setzen, schreiben wir ein bzw. mehrere # an den Anfang einer Zeile. Die Überschrift wird dann im Rmd farblich hervorgehoben. Je mehr # wir setzen, desto kleiner wird die Überschrift. Wie die einzelnen Überschriften aussehen, hängt von unserem Design (theme im YAML Header oder Template) ab.

Achtung: Im R-Skript konnten wir # zum Kommentieren nutzen. Das funktioniert hier auch, aber nur in den Code Chunks. Um Textpassagen auszukommentieren, können wir den html-Kommentar-Tag <!-- --> nutzen. Mit folgendem Kurzbefehl können wir sowohl Text als auch Code auskommentieren (funktioniert in html und pdf):

• Windows/Linux: Ctrl + Shift + C
• Mac: Cmd + Shift + C

25.2.2 Hervorhebung

Wir können unseren Text auch fett und kursiv schreiben.

Es gibt zwei verschiedenen Optionen (* oder _) damit wir beide kombinieren können, d.h. fett und kursiv schreiben können. Dabei ist Reihenfolge (ob zuerst fett oder kursiv) egal. Wir müssen nur darauf achten, dass das Zeichen, welches zuletzt eingefügt wurde, auch zuerst beendet wird (z.B. **_eine Möglichkeit_**).

25.2.3 Zeilenumbruch

Es gibt mehrere Möglichkeiten, einen Zeilenumbruch herbeizuführen. Entweder wir machen mindestens zwei Leerzeichen ans Ende einer Zeile oder wir nutzen einen Backslash (\).

25.2.4 Verlinkung

Wir können in unserem Output-Dokument auch auf externe (Web-)Quellen verlinken. Dazu nutzen wir [verlinkter Text](http://example.com).

Wenn unser Output-Dokument ein html ist, ist es benutzerfreundlicher, wenn sie die Webseite in einem neuen Fenster öffnet. Dazu nutzen wir den html Tag <a href="http://example.com" target="_blank">verlinkter Text</a>.

In html haben wir zusätzlich die Möglichkeit, innerhalb eines Dokuments zu verlinken. Am einfachsten ist es, auf eine Überschrift zu verlinken. Dazu nutzen wir einfach eckige Klammern, in die wir den Namen einer Überschrift schreiben: [Überschrift].

25.2.5 Formeln

Wir können Formeln und mathematische Symbole mittels LaTex integrieren. Bei der Installation von dem Paket rmarkdown wird (standarmäßig) automatisch das Paket tinytex heruntergeladen. Das ermöglicht uns die Nutzung von LaTex. Das machen wir mit $ und speziellem LaTex-Code. Einen guten Überblick darüber, wie wir wichtige mathematische Symbole in LaTex schreiben, gibt uns diese Seite.

Um Formeln im Fließtext zu schreiben (sog. Inline Formeln), nutzen wir einfache Dollarzeichen z.B. $\alpha=0.05$ wird zu \(\alpha=0.05\).

Um Formeln als (zentrierten) Blocksatz zu schreiben nutzen wir doppelte Dollarzeichen z.B.

$$ \sigma^2= \sum_{i =1}^{n} \frac{(x_i - \bar{x}) ^2}{n-1} $$ wird zu \[ \sigma^2= \sum _{i =1} ^{n} \frac{(x_i - \bar{x}) ^2} {n-1} \]

Achtung: Leerzeichen haben im LaTex Code keinen Einfluss. Sie sind hier nur der Übersichtlichkeit halber eingefügt. Wenn wir in den Formeln Leerzeichen ahben wollen, müssen wir dafür speziellen LaTex Code nutzen.

25.3.1 Code Chunk

Allen Code, denn wir sonst in ein R-Skript geschrieben haben, und der dann in der Konsole ausgeführt wurde (und ggf. im Viewer angezeigt wurde, d.h. Plots), schreiben wir in sogenannte Code Chunks.

Wir können Code Chunks einfügen indem wir auf Insert > R klicken …

… oder einen Kurzbefehl nutzen:

• Windows: Ctrl + Alt + I
• Mac: Alt + Cmd + I

Im Rmd sind die Code Chunks (in der Standardeinstellung) grau hinterlegt.

Wenn wir auf den Pfeil ganz rechts klicken, können wir den Code in dem Chunk ausführen. Darunter erscheint ggf. der Output des Codes.

Zum Ausführen des Code Chunks gibt es können wir auch einen Kurzbefehl nutzen:

• Windows: Shift + Ctrl + Enter
• Mac: Shift + Cmd + Ctrl Enter

Achtung: Wenn wir beim Knitten Fehlermeldungen angezeigt bekommen, die auf den Code zurückzuführen sind, sollten wir diesen erstmal in einem “normalen” R-Skript ausführen. So können wir schauen, ob das Problem direkt im Code oder in der Einbettung in R Markdown liegt.

Im Output-Dokument werden standarmäßig auch der Code und ggf. der Output angezeigt.

1+2+3

[1] 6

vektor <- c(1, 2, 3)

vektor

[1] 1 2 3

mean(vektor)

[1] 2

Es gibt Optionen zur Einstellung des Verhaltens der Code Chunks, die wir oben im Code Chunk innerhalb der geschweiften Klammern {r, ...} festlegen. Zwei davon werden wir häufiger brauchen: echo und eval.

Mit echo legen wir fest, ob wir den Code im Output-Dokument anzeigen wollen ({r, echo=TRUE}) oder nicht ({r, echo=FALSE}). Mit eval legen wir fest, ob wir den Code ausführen wollen ({r, eval=TRUE}) oder nicht ({r, eval=FALSE}).

Es gibt auch die Möglichkeit, globale Optionen für das Verhalten der Chunks festzulegen. Diese werden auf jeden Code Chunk angewendet (außer wenn wir in einem Code Chunk eine andere Option spezifizieren) und verhindern dadurch überflüssige Wiederholungen. Globale Optionen legen wir mit knitr::opts_chunk$set(...) fest. Die Funktion kommt direkt in den Code Chunk (und nicht wie bei den Chunk-spezifischen Optionen in {r}).

include=FALSE führt den Code aus, zeigt den Output des Codes aber nicht im Output-Dokument an. Das ist eine kürzere Alternative zu {r, echo=FALSE, eval=TRUE}, wenn der Output aus Zeichen besteht (z.B. das Ergebnis einer Rechnung; der Inhalt eines Objektes) bzw. {r, echo=FALSE, fig.show='hide'} wenn der Output eine Grafik ist.

Code Chunks können auch benannt werden, indem in den geschweiften Klammern nach einem Leerzeichen hinter dem r der gewünschte Name eingetragen wird, z.b. {r, ...} für den Namen setup. Das hilft uns bei der Orientierung, weil wir die Namen in der Dokumentübersicht in RStudio angezeigt bekommen. Wir müssen allerdings darauf achten, denselben Namen nicht mehrmals zuzuweisen. Sonst bekommen wir eine Fehlermeldung.

25.3.2 Inline Code

Wenn es sich bei dem Output (von Code) um Zeichen handelt (und nicht um z.B. Tabellen und Grafiken), können wir diesen auch direkt in den Fließtext integrieren. Dazu nutzen wir r ....

Wir können damit z.B. Inhalte eines Objektes oder das Ergebnis einer (mathematischen) Funktion (ohne den Code) ausgeben lassen. Der Output wird außerdem so formatiert wie der Fließtext.

Im vorhergehenden Abschnitt haben wir beispielsweise das Objekt vektor in einem Code Chunk definiert. Dessen Inhalte können wir mit r vector ausgeben lassen: 1, 2, 3

Wir können auch den Mittelwert von vektor berechnen mit r mean(vector): 2

Nur mit den `...` (ohne r) können wir außerdem Text hervorheben.

25.3.3 Grafiken, Bilder und Tabellen

Wir können mit R-Code in den Code Chunks außerdem auch Grafiken und Tabellen erstellen und ausgeben, sowie auch Bilder, die nicht im Rmd erstellt wurden, anzeigen.

Bei Grafiken müssen wir nichts weiter beachten. Wir können denselben R-Code nutzen wie auch in einem R-Skript (.R).

Wenn wir lokal gespeicherte Bilder integrieren wollen, können wir die Funktion include_graphics("dateipfad") aus dem Paket knitr nutzen. Dieses wurde (standardmäßig) automatisch heruntergeladen, als wir rmarkdown installiert haben.

library(knitr)include_graphics("dateipfad")

Schauen wir uns noch Code Chunk Optionen an, die wir für Grafiken und Bilder nutzen können. Diese schreiben wir wieder oben in den Code Chunk in {r, ...}.

Mit out.width (Breite) und out.height (Höhe) können wir die Größe der Abbildungen im Outputdokument kontrollieren. Wir nehmen dafür am besten ‘…px’ (pixel). Wenn wir wollen, dass das Seitenverhältnis beibehalten wird, sollten wir immer nur die Breite oder die Höhe ändern.

Mit fig.align können wir die Ausrichtung beeinflussen. Gültige Optionen sind: 'left', 'right' and 'center'.

Um Tabellen zu erstellen, gibt es verschiedene Funktionen (die nur in Rmd funktionieren). Wir schauen uns im Folgenden eine an (und zwar dieselbe, die auch für die Inhalte der R-Lernplattform genutzt wird).

Zuerst benötigen wir einen Beispieldatensatz. Wir nutzen den Datensatz women, der im Basispaket datasets enthalten ist und den wir mit der Funktion data() in unser Environment bekommen.

data("women")women

 height weight1 58 1152 59 1173 60 1204 61 1235 62 1266 63 1297 64 1328 65 1359 66 13910 67 14211 68 14612 69 15013 70 15414 71 15915 72 164

So sieht es aus, wenn wir den Datensatz einfach ausgeben. Schönere Tabellen erhalten wir mit der Funktion kable() aus dem Paket kableExtra.

install.packages("kableExtra")library(kableExtra)kable(women)

Es gibt noch diverse weitere Optionen, Tabellen zu verschönern. Eine ausführliche Dokumentation dazu gibt es auf dieser Seite.

25.4.1 Templates

Templates (Vorlagen) besitzen ein vorgefertigtes Design und ggf. sogar weitere Funktionalitäten für unser Output-Dokument.

Wenn wir Templates nutzen, sind in diesen ggf. nicht alle bzw. noch zusätzliche YAML Optionen nutzbar.

Wir wollen nun noch zwei Templates vorstellen, die für Projektdokumentation bzw. Veröffentlichungen hilfreich sein können. Für beide müssen wir jeweils ein zusätzliches Paket herunterladen.

Nach der Installation der Pakete finden wir die Templates hier:

install.packages("distill")

install.packages("devtools")library(devtools)install_github("crsh/papaja")

# Installation von citr:install.packages("citr")# Installation von Better BibTex siehe Link

sessionInfo()

R version 4.4.0 (2024-04-24)Platform: x86_64-pc-linux-gnuRunning under: Ubuntu 22.04.4 LTSMatrix products: defaultBLAS: /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3 LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.20.so; LAPACK version 3.10.0locale: [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C [3] LC_TIME=en_US.UTF-8 LC_COLLATE=en_US.UTF-8 [5] LC_MONETARY=en_US.UTF-8 LC_MESSAGES=en_US.UTF-8 [7] LC_PAPER=en_US.UTF-8 LC_NAME=C [9] LC_ADDRESS=C LC_TELEPHONE=C [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C time zone: Etc/UTCtzcode source: system (glibc)attached base packages:[1] stats graphics grDevices utils datasets methods base other attached packages:[1] kableExtra_1.4.0loaded via a namespace (and not attached): [1] digest_0.6.35 R6_2.5.1 fastmap_1.2.0 xfun_0.45 [5] magrittr_2.0.3 glue_1.7.0 stringr_1.5.1 knitr_1.47 [9] htmltools_0.5.8.1 rmarkdown_2.27 lifecycle_1.0.4 xml2_1.3.6 [13] cli_3.6.3 viridisLite_0.4.2 scales_1.3.0 svglite_2.1.3 [17] systemfonts_1.1.0 compiler_4.4.0 rstudioapi_0.16.0 tools_4.4.0 [21] munsell_0.5.1 evaluate_0.24.0 colorspace_2.1-0 yaml_2.3.8 [25] rlang_1.1.4 jsonlite_1.8.8 htmlwidgets_1.6.4 stringi_1.8.4