Anhang B — Kommunikation

Es ist sehr einfach und effizient, mit RStudio Berichte zu erstellen, sie werden Reports, Notebooks oder Markdowns genannt. R-Berechnungen können nahtlos in den Text eingefügt werden, auch mathematische Ausdrücke kann man in die Reports integrieren, und zwar sowohl im Fließtext als auch in Form von eingerückten Formeln. Der R-Code kann im Report ein- oder ausgeblendet werden. Der R-Output (z.B. Grafiken oder Tabellen) wird gut lesbar angezeigt. Mathematische Ausdrücke werden in der üblichen LaTeX-Schreibweise notiert (siehe Kapitel B.6). Reports werden in RStudio als sogenannte Quarto-Dokumente oder RMarkdown-Dokument geschrieben. Eine ausführlichere Beschreibung finden Sie im Learnweb.

B.1 Notebooks erstellen

Um einen neuen Report zu erstellen, klickt man im RStudio-Menu auf “File”/“New File”/“Quarto Document…”. Es erscheint ein Fenster, in dem Sie für das Dokument den Titel und die Namen der Autoren eintragen können. Außerdem können Sie in diesem Fenster das Ausgabeformat festlegen. Die Standardeinstellung ist HTML.

Nun einscheint ein weitgehend leeres Dokument. Die Angaben zum Titel (title) und Autor (author) sind bereits im Kopf des Dokuments eingetragen. Ergänzen kann man hier zum Beispiel das Datum (date).

Der Haupttext wird als sogenanntes Markdown-Dokument geschrieben. Einen kompakten Überblick über die verschiedenen Möglichkeiten der Textformatierung in Markdown-Dokumenten bietet das RMarkdown-Cheat-Sheet oder auch das umfangreichere, aber etwas unübersichtlichere Cheat-Sheet.

Wenn Sie den Report speichern, sollten Sie als Endung .qmd (für Quarto-Markdown) wählen. Beachten Sie den Unterschied zwischen Script-Dateien, die ausschließlich reinen R-Code enthalten und die Endung .R haben, und Quarto-Dateien, in denen Text, Tabellen, Grafiken und R-Code miteinander verwoben sind und die die Endung .qmd haben.

Gewöhnlicher Text wird mit beliebigen Zeilenumbrüchen geschrieben, die Formatierung des Outputs erfolgt später automatisch im Browser. Absätze werden durch eine Leerzeile angezeigt. Kursiv zu druckender Text wird durch Sternchen (*Sternchen*) eingerahmt, fett zu druckender Text durch doppelte Sternchen (**Sternchen**).

Überschriften beginnen mit einem oder mehreren Hash-Zeichen:

# Kapitelname

## Abschnittname

### Unterabschnittname

Theoretisch kann man bis zur sechsten Ebene gehen, aber in fast allen Anwendungen sind drei Ebenen (meist sogar zwei) ausreichend.

Nicht numerierte Auflistungen können durch Striche oder Sternchen am Zeilenanfang gekennzeichnet werden, z.B. wird

- Erster Punkt
- Zweiter Punkt
- Dritter Punkt

zum Output

  • Erster Punkt
  • Zweiter Punkt
  • Dritter Punkt

In die Reports können Links auf URLs eingefügt werden. Der farbig hervorgehobene Link-Text wird in eckigen Klammern eingegeben, direkt im Anschluss an die schließende Klammer folgt in runden Klammern die URL (also eine Internetadresse), z.B. wird

[Verweis auf Wikipedia](www.wikipedia.de)

angezeigt als: Verweis auf Wikipedia.

Die wichtigste Funktionalität von Markdown ist die nahtlose Integration von R-Code in das Dokument. Wenn man Ctrl-Alt-I bzw. Strg-Alt-I eintippt oder auf das grüne Kästchen mit dem “C” (für Chunk) in der Mitte klickt (in der oberen Leiste des Scriptfensters), dann wird ein sogenannter R-Chunk eingefügt. Dabei handelt es sich um einen Bereich, in dem R-Code wie in einem Skript eingegeben wird. Der Beginn eines Chunks besteht aus einer Zeile mit der Zeichenfolge ```{r}, das Chunk-Ende wird durch eine Zeile mit der Zeichenfolge ``` markiert.

```{r}
# R-Code, der in den Chunks steht, kann ausgeführt werden.
# Der R-Code und der Output werden in das Dokument eingefügt.


```

Von R generierte Tabellen oder Grafiken werden automatisch und mit einer meist gut lesbaren Formatierung in das Dokument eingefügt. Wenn Sie in einem Report den R-Code erklären, sollten Sie den Code darum in R-Chunks setzen.

Es gibt eine Reihe von Optionen, um zu steuern, wie die Chunks zu behandeln sind. Beispielsweise kann man mit Option echo: FALSE festlegen, dass der R-Code eines Chunks nicht im Dokument angezeigt wird, sondern nur der Output (z.B. eine Grafik). Chunk-Optionen stehen in den ersten Zeilen des Chunks. Optionszeilen werden durch das Hash-Zeichen und einen senkrechten Strich markiert. Die erste Zeile lautet dann

```{r}
#| echo: FALSE
# Der Output wird gezeigt, der Code hingegen nicht.

```

Es ist auch möglich, den Code zwar zu zeigen, aber nicht ausführen zu lassen.

```{r}
#| eval: FALSE
# Der Code wird gezeigt, aber nicht ausgeführt.

```

Schließlich ist es möglich, Angaben zu den Eigenschaften von Grafiken zu machen, z.B. zur Größe der Grafik. weiterführende Details zu den Optionen findet man im Cheat-Sheet zu Quarto/Markdown oder auf der Quarto-Homepage.

Das Arbeitsverzeichnis für die Report-Berechnungen ist immer das Verzeichnis, in dem die Report-Datei (.qmd) liegt, und zwar auch dann, wenn das Arbeitsverzeichnis, das in der Konsole mit getwd() angezeigt wird, ein anderes ist! Es ist daher empfehlenswert alle Dateien (z.B. die Daten oder Bilder), die zu einem Report gehören, in einem Verzeichnis zusammenzufassen.

Wenn Sie ausprobieren möchten, ob der R-Code funktioniert, können Sie ihn ausführen lassen, ohne dass der Output mit dem sonstigen Text zu einem Dokument gestrickt wird. Einzelne Chunks kann man durch Klicken auf das Wiedergabezeichen in der oberen rechten Ecke des Chunks ausführen lassen. In der Menu-Leiste des Skriptfensters gibt es unter “Run” ein Drop-down-Menu, in dem andere Möglichkeiten aufgelistet sind, wie man die Chunks ablaufen lassen kann. Einzelne Zeilen eines Chunks können Sie ausführen lassen, indem Sie den Cursor in die Zeile setzen und Ctrl-Enter drücken.

B.2 Konvertieren

Der R-Code wird in den Chunks ausgeführt und automatisch zusammen mit dem sonstigen Text zu einem Dokument gestrickt, wenn man am oberen Rand des Scriptfensters auf “Render” klickt. In welchem Format das “gestrickte” Dokument ausgegeben werden soll, legt die Option format im Kopf des Markdown-Dokuments fest.

Das “gestrickte” Dokument wird standardmäßig als HTML-Datei ausgegeben und unmittelbar danach angezeigt. Die HTML-Datei greift auf einige Hilfsdateien zurück. Sowohl die HTML-Datei als auch die Hilfsdateien werden in dem Ordner gespeichert, in dem das Quarto-Dokument (qmd) liegt.

Wenn Sie beim Anlegen des Dokuments ein anderes Format (z.B. pdf) gewählt haben, wird der Output in dem gewählten Format erzeugt und in dem Ordner gespeichert, in dem das Quarto-Dokument liegt. Die Konvertierung in ein pdf-Dokument funktioniert nur, wenn auf Ihrem Rechner eine Version des Textsatzprogramms LaTeX installiert ist. Sollte das nicht der Fall sein, können Sie es sehr einfach installieren. Dafür empfiehlt sich das R-Paket tinytex. Um die LaTeX-Version tinytex zu installieren, geben Sie in der RStudio-Konsole folgendes ein und führen es aus:

install.packages('tinytex')
tinytex::install_tinytex()

Diesen Schritt brauchen Sie nur ein einziges Mal auszuführen. Anschließend ist LaTeX dauerhaft verfügbar und die Konvertierung nach pdf sollte problemlos möglich sein. Weitere Informationen zu tinytex finden Sie hier. Sobald das Quarto-Dokument in das pdf-Format konvertiert ist, öffnet sich die pdf-Datei in einem pdf-Viewer.

Ein weniger eleganter, aber gangbarer Weg zum Erstellen eines pdf-Dokuments besteht darin, das Quarto-Dokument zuerst als HTML-Dokument ausgeben zu lassen und anschließend das HTML-Dokument in das pdf-Format zu konvertieren. Dazu eignet sich fast jeder übliche Browser. Öffnen Sie das HTML-Dokument in Ihrem Browser. Drucken Sie es anschließend in eine pdf-Datei.

B.3 Tabellen

Angenommen, Sie möchten den Dataframe

D <- data.frame(VarName1 = c(1,2,3,4,5,6),
                VarName2 = c("A","B","C","D","E","F"),
                VarName3 = c(120,0.9,-43,9999,0,0.00001))

in Ihrem Report in tabellelarischer Form anzeigen lassen.

Dataframes werden in einem Quarto-Dokument in etwa so angezeigt, wie in der Konsole von RStudio, also z.B.

D
  VarName1 VarName2   VarName3
1        1        A  120.00000
2        2        B    0.90000
3        3        C  -43.00000
4        4        D 9999.00000
5        5        E    0.00000
6        6        F    0.00001

Es gibt Pakete, die eine elegantere und flexible Art der Darstellung erlauben. Zu diesen Paketen gehören u.a. xtable oder stargazer. Sie brauchen diese Pakete aber in diesem Kurs nicht zu benutzen und wir gehen auch nicht näher darauf ein. Ein recht einfacher Weg, Tabellen zu erzeugen, die zumindest etwas schöner sind als ein roher Dataframe-Output, besteht darin, den Dataframe in die Funktion kable des R-Pakets knitr einzusetzen.

library(knitr)
kable(D)
VarName1 VarName2 VarName3
1 A 120.00000
2 B 0.90000
3 C -43.00000
4 D 9999.00000
5 E 0.00000
6 F 0.00001

Sehr einfache kleine Tabellen kann man auch “per Hand” eingeben. Die Syntax dafür ist denkbar simpel.

Kopf1   Kopf2   Kopf3
-----   -----   -----
A       1       0.1
B       2       0.01
C       3       0.001
D       4       0.0001

Im fertigen Report ergibt sich daraus der Output:

Kopf1 Kopf2 Kopf3
A 1 0.1
B 2 0.01
C 3 0.001
D 4 0.0001

Weitere Details zur Formatierung finden Sie unter https://pandoc.org/MANUAL.html#tables. Als generelle Regel ist es aber sinnvoll, nicht zu viel Zeit auf Formatierungsdetails zu verwenden.

B.4 Grafiken

Ein großer Vorteil von Quarto ist die extrem einfach Art, in R generierte Grafiken in den Text einzubinden, nämlich in Form eines Chunks. Ein Streudiagramm, das für den Dataframe imdb die beiden Variablen budget und avgvote gegeneinander abträgt, erzeugt man so:

```{r}
ggplot(imdb, aes(x=budget, y=avgvote)) + geom_point() 
```

Die Breite der Grafik kann mit der Option out-width verändert werden.

```{r}
#| out-width: "75%"
ggplot(imdb, aes(x=budget, y=avgvote)) + geom_point() 
```

Es ist auch möglich, externe Grafiken einzubindenn sofern Sie das Paket knitr installiert haben. Dazu speichern Sie die Grafikdatei in einem typischen Grafik-Format (z.B. png oder jpg) im gleichen Verzeichnis wie die Quarto-Datei und fügen die folgenden Zeilen in Ihr Dokument ein:

```{r}
#| echo: FALSE
#| out-width: "75%"
knitr::include_graphics("grafikdatei.jpg")
```

Noch einfacher (und auch ohne das Paket knitr verfügbar) ist die folgende Möglichkeit:

```{r}
![Unterschriftentext](grafikdatei.png)
```

Mehr dazu finden Sie auf den Quarto-Seiten zu Abbildungen. Auch hier gilt jedoch: Verlieren Sie Ihre Zeit nicht damit, die Grafiken oder den Text besonders schön und ausgefallen zu formatieren.

B.5 R im Fließtext

Manchmal möchte man Angaben zu einem Datensatz gerne in den Fließtext einbauen, z.B. den Umfang des Datensatzes, den Mittelwert einer Variablen oder bestimmte Datumsangaben. Es ist empfehlenswert diese Angaben bei der Textkompilierung automatisch einfügen zu lassen, denn wenn diese Angaben “per Hand” in den Text geschrieben werden, kann es passieren, dass bei einer Änderung oder Aktualisierung des Datensatzes die Werte nicht mehr stimmen.

Im Fließtext kann ein R-Objekt X durch `r X` eingefügt werden. Dabei darf X auch ein R-Befehl sein, z.B. wird aus `r sqrt(n)` der Output 2.236068, wenn n den Wert 5 hat.

B.6 LaTeX

In vielen Textverarbeitungsprogrammen ist es schwierig, mathematische Sonderzeichen und Formeln einzugeben. Und das Ergebnis sieht in vielen Fällen nicht besonders schön aus. Ein traditioneller, inzwischen weit verbreiteter Weg zur Notation von mathematischen Ausdrücken bietet das Textsatzsystem LaTeX. Die LaTeX-Notation hat sich weltweit in der Wissenschaft zu einer Art Standard entwickelt. Auch in Reports kann man mathematische Ausdrücke in dieser Notation einfügen. Im Folgenden werden darum die wichtigsten Grundlagen der LaTeX-Notation knapp erklärt. Wie der Text dann letztlich vom Browser dargestellt wird, hängt teilweise vom Browser und seinen Einstellungen ab.

B.6.1 Mathematische Ausdrücke

Mathematische Ausdrücke können im Fließtext oder als eingerückte Formeln erscheinen. Im Fließtext werden sie durch ein Dollarzeichen eingeleitet und durch ein weiteres Dollarzeichen abgeschlossen.

Beispiel:

Die Variable $X$ erscheint im Fließtext.

Die Variable \(X\) erscheint im Fließtext.

Eingerückte Formeln werden durch doppelte Dollarzeichen eingeschlossen. Um den Code lesbar zu halten, sollte man eingerückte Formeln über mehrere Zeilen eingeben.

Beispiel:

Die Summe
$$
X+Y
$$
erscheint als eingerückte Formel.

Die Summe \[X+Y\] erscheint als eingerückte Formel.

B.6.2 Indizes

Tief- und hochgestellte Indizes generiert man durch den Unterstrich (_) und das Caret-Zeichen (^). Wenn in dem Index mehr als ein Zeichen steht, fasst man die Zeichen durch geschweifte Klammern zusammen.

Beispiele:

$x_1, x_2, x_{it}, a^2, a^j, a^{i+j}, Y_t^{netto}$

\(x_1, x_2, x_{it}, a^2, a^j, a^{i+j}, Y_t^{netto}\)

$$
a^2+b^2 = c^2
$$

\[a^2+b^2=c^2\]

B.6.3 Summen- und Wurzelzeichen

Das Summenzeichen heißt in LaTeX \sum, der Backslash zeigt in LaTeX an, dass ein LaTeX-Befehl vorliegt. Der Befehl \sum erzeugt das Summenzeichen. Man kann oben und/oder unten Indizes hinzufügen. Im Fließtext werden die Indizes rechts an das Summenzeichen gesetzt, in eingerückten Formeln über und unter das Summenzeichen.

Beispiel:

$$
\sum_{i=1}^n x_i
$$

\[\sum_{i=1}^n x_i\]

Das Wurzelzeichen wird durch \sqrt{} (square root) erzeugt. Es erstreckt sich über alle Zeichen, die in den geschweiften Klammern stehen.

Beispiel:

$$
\sqrt{x_i y_j},
\sqrt{s_X^2}
$$

\[\sqrt{x_i y_j}, \sqrt{s_X^2}\]

B.6.4 Einige Sonderzeichen

Die folgende Tabelle zeigt LaTeX-Befehle für einige wichtige Sonderzeichen, mathematische Symbole und griechische Buchstaben. Sehr ausführliche Auflistungen zu Sonderzeichen und mathematischen Symbolen bietet Wikipedia.

Name LaTeX code Aussehen
Auslassungspunkte \ldots \(\ldots\)
vertikale Punkte \vdots \(\vdots\)
Multiplikationspunkt \cdot \(\cdot\)
Multiplikationszeichen \times \(\times\)
Doppelkreuz \# \(\#\)
Geschweifte Klammer auf \{ \(\{\)
Geschweifte Klammer zu \} \(\}\)
Querbalken \bar{x} \(\bar{x}\)
Dach \hat{x} \(\hat{x}\)
Kleiner, größer <, > \(<\), \(>\)
Kleiner gleich \le \(\le\)
Größer gleich \ge \(\ge\)
Ungleich \neq \(\neq\)
alpha \alpha \(\alpha\)
beta \beta \(\beta\)
gamma \gamma \(\gamma\)
Gamma \Gamma \(\Gamma\)
\(\vdots\) \(\vdots\) \(\vdots\)
omega \omega \(\omega\)
Omega \Omega \(\Omega\)

B.6.5 Brüche

Der LaTeX-Befehl für einen Bruch ist \frac{}{}, wobei in den ersten geschweiften Klammern der Zähler steht und in den zweiten Klammern der Nenner.

Beispiele:

$$
\frac{1}{n}\sum_{i=1}^n (x_i-\bar x)^2
$$

\[\frac{1}{n}\sum_{i=1}^n (x_i-\bar x)^2\]

$$
\frac{\sum_{i=1}^n p_1^{(i)} x_0^{(i)}}
     {\sum_{i=1}^n p_0^{(i)}x_0^{(i)}}
$$

\[\frac{\sum_{i=1}^n p_1^{(i)}x_0^{(i)}}{\sum_{i=1}^n p_0^{(i)}x_0^{(i)}}\]

B.6.6 Funktionsnamen

Es gibt einige Standardfunktionen, die in LaTeX als Befehle vorhanden sind. Dazu gehören \ln (natürlicher Logarithmus), \log (Logarithmus), \exp (Exponentialfunktion) und die trigonometrischen Funktionen wie z.B. \sin, \cos. Es ist empfehlenswert nicht ln(x), sondern \ln(x) zu schreiben, weil ohne den Backslash die Zeichen ln kursiv gesetzt werden. Kursive Zeichen sind in der gängigen Satztechnik für Variablen vorgesehen, nicht für Funktionsnamen.

Beispiel:

$\ln(x^{2n}) = 2n\ln(x)$

\(\ln(x^{2n}) = 2n\ln(x)\)

B.6.7 Elastische Klammern

Die runden und eckigen Klammern können beliebig gesetzt werden. Vor geschweiften Klammern muss ein Backslash stehen. Es sieht nicht schön aus, wenn der Ausdruck zwischen den Klammern höher als die Klammern ist, z.B. \[ (\sum_{i=1}^n x_i)^2 \] In so einer Situation sollten die Klammern so hoch sein, dass sie den Ausdruck in der Mitte komplett umschließen. Das lässt sich in LaTeX leicht erreichen, indem man elastische Klammern einfügt. Elastische Klammern treten immer paarweise auf, und zwar als \left( und \right) bzw. \left[ und \right]. Ihre Größe wird so berechnet, dass sie so hoch sind wie der Ausdruck zwischen ihnen.

Beispiele:

$$
\left(\sum_{i=1}^n x_i\right)^2, 
\sin\left(\frac{\pi}{2}\right)
$$

\[\left(\sum_{i=1}^n x_i\right)^2, \sin\left(\frac{\pi}{2}\right)\]

B.6.8 Mehrzeilige Formeln

Wenn mathematische Ausdrücke, z.B. Herleitungen, sich über mehrere Zeilen erstrecken, ist es oft sinnvoll sie an bestimmten Zeichen auszurichten, z.B. an Gleichheitszeichen. In LaTeX gibt es dafür die align*-Umgebung. Sie wird durch die Befehl \begin{align*} und \end{align*} umschlossen. Jede Zeile hat das Format

linker Teil & rechter Teil \\

Die Zeilen werden an den &-Zeichen ausgerichtet. Es ist erlaubt, dass der linke oder rechte Teil leer sind. Der doppelte Backslash zeigt das Zeilenende an, er darf nicht fehlen (das ist ein häufiger Fehler). Das ganze ist am einfachsten an einem Beispiel zu verstehen.

Beispiel:

\begin{align*}
\bar{x} &= (x_1 + \ldots + x_n)/n \\
        &= \frac{1}{n}\sum_{i=1}^n x_i
\end{align*}

\[\begin{align*} \bar{x} &= (x_1 + \ldots + x_n)/n \\ &= \frac{1}{n}\sum_{i=1}^n x_i \end{align*}\]