-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy path11_reports.Rmd
271 lines (215 loc) · 19.7 KB
/
11_reports.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
---
title: "Reports in R Markdown"
author: CorrelAid e.V.
date: "`r Sys.Date()`"
authors:
- Lisa Reiber
- Emma Morlock
- Jonas Lorenz
output:
html_document:
toc: true
toc_depth: 2
toc_float: true
theme: flatly
css: www/style.css
includes:
after_body: ./www/favicon.html
language: de
runtime: shiny_prerendered
---
```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = FALSE, message = FALSE, warning = FALSE)
library(learnr)
library(gradethis)
source("R/setup/gradethis-setup.R")
source("R/setup/tutorial-setup.R")
# Read app parameters
params <- yaml::yaml.load_file("www/app_parameters.yml")
# Benötigte Daten laden
source("R/setup/functions.R")
```
```{r results='asis'}
cat(get_license_note(rmarkdown::metadata$title, rmarkdown::metadata$authors))
```
# **Einführung in R Markdown**
## **Zusammenfassung**
- R Markdown ist ein **Framework**, das es ermöglicht, **reproduzierbare Reports** mit R Code zu schreiben.
- Es ist so beliebt, weil es ermöglicht, **alle Schritte einer Datenanalyse an einem Ort** zu sammeln. Durch die **Kombination von Text, Code und Code-Output** werden z. B. Präsentationen verständlicher, da wir Anmerkungen und Erklärungen zu unseren Analysen hinzufügen können.
- Die **Code-Chunks**, in denen der Code steht und die den Code-Output erzeugen, sind in Rmd-Dateien **grau** hinterlegt, während der **Markdown-Teil weiß** hinterlegt ist.
- Außerdem können wir **berechnete Kennzahlen** integrieren, die bei einer Aktualisierung der Daten automatisch aktualisiert werden – Gleiches gilt für den restlichen **Code-Output**.
- Der Export eines Berichts ist in **PDF**, **HTML** und **Word** möglich. Für **statistische Berichte** ist meistens das **PDF** die richtige Wahl, aber auch eine **HTML-Datei** kann sinnvoll sein.
- R-Studio bietet eine sehr gute [**Hilfeseite**](https://rmarkdown.rstudio.com/lesson-1.html){target="_blank"} zu vielen Themen rund um R Markdown in englischer Sprache an - unter anderem ein tolles Einführungsvideo (1min).
- Daneben gibt es auch noch diesen [**Schummelzettel (dt.)**](https://github.com/CorrelAid/rlernen_umwelt/blob/main/cheatsheets/09_cheatsheet-rmarkdown-2.pdf){target="_blank"}, diesen [**Schummelzettel (engl.)**](https://github.com/CorrelAid/rlernen_umwelt/blob/main/cheatsheets/09_cheatsheet-rmarkdown-1.pdf){target="_blank"} und dieses tolle [**Nachschlagewerk (engl.)**](https://github.com/CorrelAid/rlernen_umwelt/blob/main/cheatsheets/09_cheatsheet-rmarkdown-3.pdf){target="_blank"}
## **Quiz**
```{r 10quiz_reports_allg}
quiz(caption = NULL,
question("Welche dieser Beschreibungen treffen zu? R Markdown ist... ",
answer("...📦 ein R-Paket namens rmarkdown.", correct = TRUE),
answer("...️Zauberei 🧙"),
answer("...ein Dateiformat zum Erstellen dynamischer Dokumente mit R.", correct = TRUE),
answer("...ein Tool zum Integrieren von Prosa, Code und Ergebnissen.", correct = TRUE),
correct = "Richtig, R Markdown ist ein R-Paket und ein vielseitiges Format, das es ermöglicht, Text, R-Code und Ergebnisse in einem Dokument zu vereinen.",
incorrect = "Leider falsch, versuche es einfach nochmal oder schau im Video nach!",
allow_retry = TRUE,
try_again_button = "Nochmal versuchen"),
question("Aus welchen drei Hauptkomponenten setzen sich R Markdown-Dateien zusammen?",
answer("YAML Abschnitt, Inhalt und Code Chunks", correct = TRUE),
answer("Überschriften, Texte und Bilder"),
answer("Code, Tabellen und Grafiken"),
answer("R, Mark und Down"),
correct = "Richtig, eine R Markdown-Datei besteht hauptsächlich aus einem YAML-Abschnitt zur Definition von Metadaten, dem Inhaltsbereich für Prosa und Erläuterungen, und den Code Chunks, die ausführbaren Code enthalten.",
incorrect = "Leider falsch, versuche es nochmal oder schau im Video nach!",
allow_retry = TRUE,
try_again_button = "Nochmal versuchen"
)
)
```
---
# **Interaktive Übung**
In den folgenden Abschnitten dieser Übung werden wir uns die grundlegenden Elemente einer R Markdown-Datei noch einmal anschauen. Dabei soll es vor allem um die Inhalte eines Reports, einschließlich der Struktur von Text, Code Blöcken und der YAML-Kopfzeile gehen. Wir werden uns unter anderem auch damit beschäftigen, wie man R-Code ausführt und das Layout sowie Metadaten des Dokuments steuert. Am Ende werden wir hoffentlich alle ein funktionierendes R Markdown-Dokument erstellen.
---
## **1. Markdown (Inhalt)**
In R Markdown-Dateien steht das **md** in der Dateiendung `meine_datei.Rmd` für **Markdown**. Markdown (ohne R) ist eine einfache **Auszeichnungssprache**, die es ermöglicht, Text mit minimalen Formatierungsbefehlen zu strukturieren. Sie wird häufig in Dokumentationen, Blogs und README-Dateien verwendet, da sie sich leicht lesen und in HTML umwandeln lässt. Wenn Ihr Euch noch einmal alle Möglichkeiten anschauen wollt, wie Ihr R Markdowns verwenden könnt, dann werft doch gerne noch einen Blick in die [R Studio Galerie](https://rmarkdown.rstudio.com/gallery.html){target="\_blank"} - Fun Fact: Auch diese Lernplattform basiert auf Markdown!
Die Formatierung funktioniert ausschließlich im Textteil, dem **weiß hinterlegten Teil** des Rmds. Mit wenigen Zeichen können wir dabei verschiedene Formatierungen vornehmen, hier ein kleiner Überblick:
<style>
table {
width: 100%;
}
th {
text-align: left; /* Linksbündige Ausrichtung der Überschriften */
}
</style>
| **Formatierung** | **Erstellt mit:** | *Anmerkung* |
|--------------------------|---------------------------|-------------------|
| **H5 Überschrift** | `##### H5 Überschrift` | *Anmerkung: H1 Überschriften benötigen nur ein #, H2 zwei ##, usw.* |
| **Trennlinie** | `---` | *auf ausreichend Zeilenumbrüche davor und danach achten.* |
| **Text** | `*Text in italics*` | wird zu *Text in italics* |
| **Text** | `**Text in bold**` | wird zu **Text in bold** |
| **Einfügen eines Bildes** | `{width="10%" height="10%"}` | {width="10%" height="10%"} |
| **Einfügen eines Hyperlinks** | `[Hyperlinkname](Link){target="_blank"}` | *Mit {target="\_blank"} könnt Ihr festlegen, dass ein neuer Tab geöffnet wird.* |
| **Zeilenumbrüche** | `<br>` | *Notation stammt aus HTML* |
| **Positionierung** | `<center>, <left> und <right>` | *Ebenfalls HTML-Notation* |
| **Backslash** | `\` | *ignoriert Bedeutung von Sonderzeichen, wenn der Backslash vor ihnen steht* |
*Anmerkung: Wie ihr seht, sind einige HTML-Ausdrücke hilfreich, um den Report entsprechend zu optimieren. HTML (Hypertext Markup Language) ist die Standard-Auszeichnungssprache für das Erstellen und Strukturieren von Webseiten. Mithilfe von "Tags" werden Inhalte (z.B. Texte, Bilder, Tabellen und Links) strukturiert, sodass Browser sie visuell darstellen können.*
```{r 10quiz_reports_markdown}
quiz(caption = NULL,
question("Wie formatieren wir Text zu einer Überschrift?",
answer("Mit der gewünschten Anzahl an Hashes (#), eins für H1, zwei für H2, ...", correct = TRUE),
answer("Mit zwei Sternchen (**) vor und hinter der Überschrift."),
answer("Mit einem Sternchen (*) vor und hinter der Überschrift."),
answer("Mit einem Backslash vor und hinter der Überschrift."),
answer("Durch das Umschließen der Überschrift mit eckigen Klammern ([])."),
correct = "Richtig, die Anzahl der Hashes (#) bestimmt die Hierarchie der Überschrift. Ein Hash ist H1, zwei sind H2 und so weiter.",
incorrect = "Leider falsch, versuche es einfach nochmal oder werfe noch einmal einen Blick auf unsere Übersicht.",
allow_retry = TRUE,
try_again_button = "Nochmal versuchen"
)
)
```
Wenn Ihr noch ein bisschen üben wollt, wie Ihr Text mit Hilfe von der Markdown Syntax formatieren könnt, gibt es hier ein [10-minütiges interaktives Tutorial in englischer Sprache](https://commonmark.org/help/){target="\_blank"}, welches wir sehr empfehlen können.
---
## **2. R Code-Blöcke (Chunks)**
In R Markdown-Dateien verwenden wir Code Blöcke (Chunks), um R-Code auszuführen und die Ergebnisse im Dokument zu integrieren. Diese Code Chunks werden in Eurem Rmd **grau hinterlegt**. Es gibt zwei Wege, wie wir Code Chunks in unsere Rmd-Datei einfügen können:
- Die Tastenkombination Strg + Alt + I (OS X: Cmd + Wahl + I) oder
- den Befehl `Chunk hinzufügen` in der Symbolleiste des Editors (grünes C+)
Mithilfe dieser Chunks können wir auch steuern, welche Teile des Codes im Enddokument angezeigt oder ausgeführt werden. Je nachdem wie wir unser Rmd gestalten wollen, müssen wir die **Code Block Argumente** setzen. Dazu setzen wir im Code Chunk innerhalb der geschwungenen Klammer ein Argument und ergänzen dann auf der rechten Seite die richtige Einstellung. Mehrere Argumente werden durch Kommata (",") getrennt. Ein entsprechender Code Block sähe dann beispielsweise so aus: <br>
\`\`\`{r, argument1 = gewünschte_einstellung, ...} <br> Dein Code hier <br> \`\`\` <br>
Grundsätzlich wird in unserem Outputformat nämlich der **gesamte Code, inklusive Code Output, Nachrichten und Warnungen** integriert. Nicht immer ist das gewünscht. Daher können die Argumente sehr hilfreich sein, um unseren Code so übersichtlich wie möglich zu halten. Eine Übersicht über wichtigsten Argumente findet Ihr deshalb hier:
<style>
table {
width: 100%;
}
th {
text-align: left; /* Linksbündige Ausrichtung der Überschriften */
}
</style>
| **Argumente** | **Bedeutung** |
|------------------------------------|------------------------------------|
| `include = FALSE` | Definiert, dass **Code und Code Output** in der fertigen Datei **nicht erscheinen**. R Markdown führt den Code weiterhin im Chunk aus und die Ergebnisse können von anderen Chunks verwendet werden |
| `echo = FALSE` | Definiert, dass **Code nicht angezeigt wird**, aber Code Output (wie Tabellen und Plots) in der fertigen Datei erscheinen. Dies ist eine nützliche Methode zum **Einbetten von Abbildungen** |
| `message = FALSE` | Verhindert, dass **Nachrichten**, die bei der Ausführung des Codes generiert werden, in der fertigen Datei erscheinen |
| `warning = FALSE` | Verhindert, dass **Warnungen**, die bei der Ausführung des Codes generiert werden, im Report erscheinen |
| `fig.cap = "..."` | Fügt den grafischen Ergebnissen eine **Beschriftung** hinzu |
Um eine Option für alle Code Blocks festzulegen, greifen wir auf das Package `knitr` zurück, welches häufig in Verbindung mit R Markdown genutzt wird. Das Package spielt beim Erstellen des Reports eine zentrale Rolle, da es beim Rendern der Rmd-Datei die Aufgabe übernimmt, den R-Code auszuführen und die Ergebnisse (z. B. Grafiken, Tabellen oder Berechnungen) direkt in das Ausgabeformat zu integrieren. Mehr zu diesem Package findet Ihr in der [knitr-Dokumentation](https://yihui.org/knitr/){target="\_blank"}.
Mithilfe der darin enthaltenen Funktion `knitr::opts_chunk$set(argument = ...)` können **global im ersten Setup Code Block** die Optionen für alle folgenden Code Chucks gesetzt werden. <br>
\`\`\`{r setup, include=FALSE} <br> knitr::opts_chunk\$set(argument1 = gewünschte_einstellung, ...) <br> \`\`\` <br>
Knitr behandelt jede Option, die an knitr::opts_chunk\$set übergeben wurde, als globalen Standard, der **in einzelnen Chunk-Headern überschrieben** werden kann.
```{r 10quiz_reports_codechunksettings, echo=FALSE, message=FALSE, warning=FALSE}
quiz(caption = NULL,
question("Wir wollen grundsätzlich, dass nur der Output in unserem PDF-Outputformat angezeigt wird. Code, Nachrichten und Warnungen sollen also nicht sichtbar sein. Was müssen wir tun?",
answer("Im Set-Up Chunk setzen wir die Argumente include, echo, message und warning auf FALSE."),
answer("Im Set-Up Chunk setzen wir die Argumente echo, message und warning auf FALSE.", correct = TRUE),
answer("Im Set-Up Chunk setzen wir die Argumente include, echo, message und warning auf TRUE."),
answer("Im Code-Chunk setzen wir die Argumente echo, message und warning auf FALSE."),
correct = "Richtig, die Argumente setzen wir im Set-Up Chunk innerhalb der Funktion knitr::opts_chunk$set(). In diesem Fall müssen wir die Argumente echo, message und warning, alle auf FALSE setzen, um den Code und die Nachrichten im finalen Dokument zu verbergen",
incorrect = "Leider falsch, versuche es einfach nochmal! Versuche Dich dabei zu erinnern in welchem Code-Chunk wir die grundsätzlichen Einstellungen festlegen können und wie diese lauten müssten.",
allow_retry = TRUE,
try_again_button = "Nochmal versuchen"
),
question("Ausnahmsweise soll nun einmal der Code gezeigt werden. Was müsst Ihr tun?",
answer("Im betroffenen Code Chunk setzen wir das Argument echo auf TRUE.", correct = TRUE),
answer("Im betroffenen Code Chunk setzen wir das Argument echo auf FALSE."),
answer("Im betroffenen Code Chunk setzen wir das Argument include auf FALSE."),
answer("Im betroffenen Code Chunk setzen wir das Argument include auf TRUE."),
correct = "Richtig, indem wir im betroffenen Code Chunk das Argument `echo` auf TRUE setzen, wird der Code im Outputdokument angezeigt.",
incorrect = "Leider falsch, im betroffenen Code Chunk muss das Argument echo auf TRUE gestellt werden. Mit dem Argument include wird übrigens definiert, ob Code und Code Output in das Outputdokument integriert werden sollen. Dieses muss auf TRUE gestellt werden, wenn das geschehen soll, und auf auf FALSE, wenn es nicht geschehen soll.",
allow_retry = TRUE,
try_again_button = "Nochmal versuchen"
)
)
```
---
## **3. YAML Kopfzeile**
Die **YAML-Kopfzeile (Yet Another Markup Language)** in einer R Markdown-Datei befindet sich am Anfang des Dokuments und dient dazu, **Meta-Parameter** wie den Titel, den Autor, das Datum und das Format des Outputs zu definieren. Diese Kopfzeile ist wichtig, um die generierten Dokumente zu steuern und anzupassen. Sie kann auch dazu verwendet werden, den Stil des Outputs zu beeinflussen, etwa durch die Angabe von Themes für HTML-Dateien.
Die **Grundeinstellungen** geben Titel, Autor:in, Datum und Outputformat des geknitteten Dokuments an. Mithilfe der vorgefertigten Themes können wir einfach das Layout anpassen. Wenn Ihr Euch mit HTML und CSS auskennt, könnt Ihr Stylesheets anlegen und auf diese verweisen.
Der YAML-Abschnitt ist immer zu Beginn einer R Markdown Datei und daran zu erkennen, dass er mit `---` umschlossen ist:
```
---
title: "Euer Titel"
date: "Datum"
output: html_document
---
```
Im untenstehenden YAML Code wird eines der Standard Themes von R Markdown namens "Flatly" definiert. Weitere Themes findet Ihr in dieser [R Markdown Theme Gallery](https://www.datadreaming.org/post/r-markdown-theme-gallery/){target="_blank"}.
```
---
title: "Euer Titel"
date: "Datum"
output:
html_document:
theme: "flatly"
highlight: github
---
```
```{r 10quiz_reports_yaml}
quiz(caption = NULL,
question("Welche Einstellungen können im YAML-Header getroffen werden?",
answer("Titel des Outputdokuments.", correct = TRUE),
answer("Autor:in des Outputdokuments.", correct = TRUE),
answer("Datum des Outputdokuments.", correct = TRUE),
answer("Dateiformat.", correct = TRUE),
answer("Layout.", correct = TRUE),
answer("...und vieles mehr!", correct = TRUE),
correct = "Richtig, der YAML-Header übernimmt in Rmds zahlreiche Funktionen rund um Styling und Layout.",
incorrect = "Leider falsch, tatsächlich können wir alle diese Eigenschaften im YAML-Header festlegen.",
allow_retry = TRUE,
try_again_button = "Nochmal versuchen"
)
)
```
Soweit einmal zu den Grundlagen zu Reports mithilfe von R Markdown. Doch das war noch längst nicht alles! Im Rahmen des dieswöchigen [Exkurses](https://rlernen.correlaid.org/11_0_exkurs-automatisierte-reports.html){target="_blank"} möchten wir Euch zeigen, wie Ihr **Reports automatisieren** und **mehrere Reports auf einmal erstellen** könnt. Beides ist super hilfreich und mithilfe von R zu lösen, schaut dort also gerne einmal rein!
---
# **Und jetzt Ihr!**
1. **Lasst Euch inspirieren**: Besucht die [R-Studio R Markdown Galerie](https://rmarkdown.rstudio.com/gallery.html){target="_blank"} und stöbert durch einige Beispiele, die mit R Markdown erstellt wurden. Ihr könnt zwischen Webseiten, PDF-Dokumenten oder Dashboards, Slideshows uvm. wählen. Teilt Euer Lieblingsbeispiel (als Screenshot und/oder mit Link) im Slack Channel und beschreibt in 1-3 Sätzen, was Ihr an dem Report besonders gelungen findet.
2. Passenderweise haben wir diese Woche eine Übungsaufgabe im R Markdown-Format für Euch! Die Datei **Übung 11_reports-uebung.Rmd** befindet sich wie gewohnt im [Übungsordner](https://download-directory.github.io/?url=https://github.com/CorrelAid/rlernen_umwelt/tree/main/uebungen){target="_blank"} unter `11_reports`. Versucht, diese Datei lokal zu bearbeiten.
---
# **Zusätzliche Ressourcen**
- [**Schummelzettel (dt.)**](https://github.com/CorrelAid/rlernen_umwelt/blob/main/cheatsheets/09_cheatsheet-rmarkdown-2.pdf){target="_blank"}
- [**Nachschlagewerk zu RMarkdown (engl.)**](https://github.com/CorrelAid/rlernen_umwelt/blob/main/cheatsheets/09_cheatsheet-rmarkdown-3.pdf){target="_blank"}
- R-Studio bietet eine sehr gute [**Hilfeseite**](https://rmarkdown.rstudio.com/lesson-1.html){target="_blank"}
- Templates für [PDF- und HTML-Dokumente](https://www.rstudio.com/blog/r-markdown-custom-formats/){target="_blank"}
<br>
---
<a class="btn btn-primary btn-back-to-main" href=`r params$links$end_session`>Session beenden</a>