Chap-Einrichtung.Rmd

---
output:
  pdf_document: default
  html_document: default
---
# Einrichtung {#einrichtung}

```{r, include=FALSE, message=F, warning=FALSE}
knitr::opts_chunk$set(comment = "#>", warning = F, message = F)
library(here)
```

## Installation von R und R-Studio

Die Installation von R ist in der Regel unproblematisch.
Auf der [R homepage](https://www.r-project.org/) wählt man unter dem Reiter 
'Download' den Link 'CRAN' aus, wählt einen Server in der Nähe und lädt sich 
dann die R Software herunter. 
Danach folgt man den Installationshinweisen.

Im zweiten Schritt muss noch das Programm 'R-Studio' installiert werden. 
Hierbei handelt es sich um eine grafische Oberfläche für R, welche uns die 
Arbeit enorm erleichtern wird.
Das Programm kann [hier](https://www.rstudio.com/products/rstudio/download/) 
heruntergeladen werden.
Bitte darauf achten 'RStuio Desktop' zu installieren.

## Die R Studio Oberfläche

Nach dem Installationsprozess öffnen wir R Studio zum ersten Mal.
Abbildung \@ref(fig:gui) zeigt die verschiedenen Elemente der Oberfläche, deren 
Funktion im Folgenden kurz erläutert wird.
Vieles ergibt sich hier aber auch durch *learning by doing*.
Im Folgenden werden nur die Bereiche der Oberfläche beschrieben, die am Anfang 
unmittelbar relevant für uns sind.

```{r gui, echo=FALSE, fig.align='center', out.width='100%', fig.cap="Die Benutzeroberfläche von R-Studio."}
knitr::include_graphics(
  here::here("figures/Einrichtung/r-studio-light-marked.png"), 
  auto_pdf = T)
```

* Der **Skriptbereich** (1) ist ein Texteditor wie Notepad - nur mit 
zusätzlichen Features wie Syntax Highlighting für R, sodass es uns leichter 
fällt R Code zu schreiben.
Hier werden wir unsere Skripte verfassen.

* Die **Konsole** (2) erlaubt es uns über R direkt mit unserem Computer zu
interagieren.
R ist eine Programmiersprache. Das bedeutet, wenn wir den Regeln der Sprache 
folgen und uns in einer für den Computer verständlichen Art und Weise ausdrücken, 
versteht der Computer was wir von ihm wollen und führt unsere Befehle aus. 
Wenn wir in die Konsole z.B. `2+2` eingeben, dann ist das valider R Code. 
Wenn wir dann Enter drücken versteht der Computer unseren Befehl und führt die 
Berechnung aus.
Die Konsole ist sehr praktisch um den Effekt von R Code direkt zu beobachten.
Wenn wir etwas in der Console ausführen wollen, das wir vorher im 
**Skriptbereich** geschrieben haben, können wir den Text markieren und dann auf 
den Button `Run` (3) drücken: dann kopiert R Studio den Code in die Konsole und 
führt ihn aus.

* Für den Bereich oben rechts haben wir in der Standardkonfiguration von R 
Studio drei Optionen, die wir durch Klicken auf die Reiter auswählen können.
Der Reiter **Environment** (4) zeigt uns alle bisher definierten Objekte an 
(mehr dazu später). 
Der Reiter **History** (5) zeigt an, welchen Code wir in der Vergangenheit 
ausgeführt haben.
Der Reiter **Connections** (6) braucht uns aktuell nicht zu interessieren.

* Auch für den Bereich unten rechts haben wir mehrere Optionen: 
Der Bereich **Files** (7) zeigt uns unser Arbeitsverzeichnis mit allen Ordnern 
und Dateien an. 
Das ist das Gleiche, was wir auch über den File Explorer unseres Betriebssystems 
sehen würden.
Der Bereich **Plots** (8) zeigt uns eine Vorschau der Abbildungen, die wir durch 
unseren Code produzieren.
Die anderen Bereiche brauchen uns aktuell noch nicht zu interessieren.

* Wenn wir ein neues R Skript erstellen wollen, können wir das über den Button 
**Neu** (9) erledigen.
Wir klicken darauf und wählen die Option 'R Skript'. 
Mit den alternativen Dateiformaten brauchen wir uns aktuell nicht beschäftigen.

* Der Botton **Neues Projekt anlegen** (10) erstellt eine neues R Studio 
Projekt - mehr dazu in Kürze.

* Der Button **Öffnen** (11) öffnet Dateien im Skriptbereich.

* Die beiden Buttons **Speichern** (12) und **Alles speichern** (13) speichern 
das aktuelle, bzw. alle im Skriptbereich geöffnenten Dateien.

Die restlichen Buttons und Fenster in R Studio werden wir im Laufe der Zeit 
kennenlernen.

Es macht Sinn, sich einmal die möglichen Einstellungsmöglichkeiten für R Studio 
anzuschauen und gegebenenfalls eine andere Darstellungsversion zu wählen.

## Einrichtung eines R Projekts

Im Folgenden werden wir lernen wie man ein neues R Projekt anlegt, R Code 
schreiben und ausführen kann.

Wann immer wir ein neues Programmierprojekt starten, sollten wir dafür einen 
eigenen Ordner anlegen und ein sogenanntes 'R Studio Projekt' erstellen.
Das hilft uns den Überblick über unsere Arbeit zu behalten, und macht es einfach 
Code untereinander auszutauschen.

Ein Programmierprojekt kann ein Projekt für eine Hausarbeit sein, die 
Mitschriften für eine Vorlesungseinheit, oder einfach der Versuch ein bestimmtes 
Problem zu lösen, z.B. einen Datensatz zu visualisieren.

Die Schritte zur Erstellung eines solchen Projekts sind immer die gleichen:

1. Einen Ordner für das Projekt anlegen.
2. Ein R-Studio Projekt in diesem Ordner erstellen.
3. Relevante Unterordner anlegen.

Wir beschäftigen uns mit den Schritten gleich im Detail, müssen vorher aber noch
die folgenden Konzepte diskutieren:
(1) das Konzept eines *Arbeitsverzeichnisses* (*working directory*) und 
(2) die Unterscheidung zwischen *absoluten* und *relativen* Pfaden.

### Arbeitsverzeichnisse und Pfade

Das **Arbeitsverzeichnis** ist ein Ordner auf dem Computer, in dem R 
standardmäßig sämtlichen Output speichert und von dem aus es auf Datensätze und
anderen Input zugreift. 
Wenn wir mit Projekten arbeiten ist das Arbeitsverzeichnis der Ordner, in dem das 
R-Projektfile abgelegt ist, ansonsten ist es das Benutzerverzeichnis.
Wir können uns das Arbeitsverzeichnis mit der Funktion `getwd()` anzeigen lassen.
In meinem Fall ist das Arbeitsverzeichnis das Folgende:

```{r, echo=FALSE}
getwd()
```

Wenn ich R nun sagen würde, es solle ein File unter dem Namen `test.pdf` speichern, 
dann würde es am folgenden Ort gespeichert werden:

```{r, echo=FALSE}
paste0(getwd(), "/test.pdf")
```

R geht in einem solchen Fall immer vom Arbeitsverzeichnis aus.
Da wir im vorliegenden Fall den Speicherort relativ zum Arbeitsverzeichnis 
angegeben haben, sprechen wir hier von einem **relativen Pfad**.

Alternativ können wir den Speicherort auch als **absoluten Pfad** angeben. In
diesem Fall geben wir den kompletten Pfad, ausgehend vom 
[Root Verzeichnis](https://de.wikipedia.org/wiki/Stammverzeichnis) des
Computers, an. 
Wir würden R also *explizit* auffordern, das File an folgendem Ort zu 
speichern:

```{r, echo=FALSE}
paste0(getwd(), "/test.pdf")
```

Im vorliegenden Fall sind die resultierenden Pfade identisch.
Wir können bei absoluten Pfaden aber jeden beliebigen Pfad angeben.
Wir könnten die Datei z.B. auch an folgendem Ort speicher, wenn wir genau 
diesen absoluten Pfad angeben:

```
~/claudius-projekte/R-Projekt/output/test.pdf
```

Wir werden hier **immer** relative Pfade verwenden. 
Relative Pfade sind fast immer die bessere Variante, da ihre Verwendung es uns 
erlaubt den gleichen Code auf verschiedenen Computern zu verwenden. 
Denn wie man an den absoluten Pfaden erkennen kann, sehen diese auf jedem 
Computer anders aus und es ist dementsprechend schwierig, Code miteinander zu
teilen.

Wir lernen mehr über dieses Thema wenn wir uns später mit Dateninput und -output 
beschäftigen.

### Schritt 1: Projektordner anlegen

Zuerst müssen Sie sich für einen Ordner auf Ihrem Computer entscheiden, in dem
alle Daten, die mit ihrem Projekt zu tun haben, also Daten, Skripte, Abbildungen, 
etc. gespeichert werden sollen und diesen Ordner gegebenenfalls neu erstellen.
Es macht Sinn, einen solchen Ordner mit einem informativen Namen ohne Leer- und
Sonderzeichen zu versehen, z.B. `Learning-R`.

Dieser Schritt kann theoretisch auch gemeinsam mit Schritt 2 erfolgen.

### Schritt 2: Ein R-Studio Projekt im Projektordner erstellen

Wir möchten nun R Studio mitteilen den in Schritt 1 erstellten Ordner als R
Projekt zu behandeln. 
Damit wird nicht nur dieser Ordner als Root-Verzeichnis festgelegt, man kann
auch die Arbeitshistorie eines Projekts leicht wiederherstellen und es ist 
einfacher, das Projekt auf verschiedenen Computern zu bearbeiten.

Um ein neues Projekt zu erstellen klicken Sie in R Studio auf den Button 
`Neues Projekt` (Nr. 10 in Abbildung \@ref(fig:gui)) und Sie sollten das in 
Abbildung \@ref(fig:newproj1) dargestellte Fenster sehen.

```{r newproj1, echo=FALSE, fig.align='center', out.width='60%', fig.cap="Ein neues Projekt erstellen."}
knitr::include_graphics(
  here::here("figures/Einrichtung/r-studio-new-project.png"), auto_pdf = T)
```

Falls Sie in Schritt 1 den Projektordner bereits erstellt haben wählen Sie hier
`Existing Directory`, ansonsten erstellen Sie einen neuen Projektordner gleich 
gemeinsam mit dem Projektfile indem Sie `New Directory` auswählen.

Falls Sie `Existing Directory` gewählt haben, landen Sie in einem Fenster, welches 
dem linken Feld der Abbildung \@ref(fig:newproj2) entspricht. Hier wählen Sie
einfach den vorher erstellten Ordner aus und klicken auf `Create Project`.

```{r newproj2, echo=FALSE, fig.align='center', out.width='40%', fig.show = 'hold', fig.cap="Ein neues R-Projekt aus einem existierenden (links) oder in einem neuen Projektordner (rechts) erstellen."}
knitr::include_graphics(
  here::here("figures/Einrichtung/r-studio-new-project-exis-dir.png"), 
  auto_pdf = T)
knitr::include_graphics(
  here::here("figures/Einrichtung/r-studio-new-project-new-dir.png"), 
  auto_pdf = T)
```

Falls Sie `New Directory` gewählt haben, landen Sie dann auf dem rechten in 
Abbildung \@ref(fig:newproj2) dargestellten Fenster.
Hier wählen Sie `New Project` aus, geben dem Projekt im folgenden Fenster einen
Namen (das wird der Name des Projektordners sein), wählen den Speicherort für den
Ordner aus und klicken auf `Create Project`.

In beiden Fällen wurde nun ein Ordner erstellt, in dem sich ein File `*.Rproj`
befindet. Damit ist die formale Erstellung eines Projekts abgeschlossen. 
Es empfiehlt sich jedoch dringend, gleich eine sinnvolle Unterordnerstruktur mit
anzulegen.

### Schritt 3: Relevante Unterordner erstellen {#unterordner}

Eine sinnvolle Unterordnerstruktur hilft (1) den Überblick über das eigene 
Projekt nicht zu verlieren, (2) mit anderen über verschiedene Computer hinweg
zu kollaborieren und (3) Kollaborationsplattformen wie Github zu verwenden und
replizierbare und für andere nachvollziehbare Forschungsarbeit zu betreiben.

Die folgende Ordnerstruktur ist eine Empfehlung. 
In manchen Projekten werden Sie nicht alle hier vorgeschlagenen Unterordner
brauchen, in anderen bietet sich die Verwendung von mehr Unterordnern an.
Nichtsdestotrotz ist es ein guter Ausgangspunkt, den ich in den meisten meiner
Forschungsprojekte auch so verwende.

Insgesamt sollten die folgenden Ordner im Projektordner erstellt werden:

* Ein Ordner `data`, der alle Daten enthält, die im Rahmen des Projekts 
verwendet werden. Hier empfiehlt es sich zwei Unterordner anzulegen:
Einen Ordner `raw`, der die Rohdaten enthält, so wie sie aus dem Internet 
runtergeladen wurden. Diese Rohdaten sollten **niemals** verändert werden, 
ansonsten wird Ihre Arbeit nicht vollständig replizierbar werden und es kommt 
gegebenenfalls zu irreparablen Schäden. Alle Veränderungen der Daten sollten durch Skripte
dokumentiert werden, die die Rohdaten als Input, und einen modifizierten 
Datensatz als Output generieren. Dieser modifizierte Datensatz sollte dann im 
Unterordner `tidy` gespeichert werden.

> Beispiel: Sie laden sich Daten zum BIP in Deutschland von Eurostat und 
Daten zu Arbeitslosigkeit von AMECO herunter. Beide Datensätze sollten im 
Unterordner `data/raw` gespeichert werden. Mit einem Skript lesen Sie beide
Datensätze ein und erstellen den kombinierten Datensatz `macro_data.csv`, den
Sie im Ordner `data/tidy` speichern und für die weitere Analyse verwenden.
Dadurch kann jede*r nachvollziehen wie die von Ihnen verwendeten Daten sich aus
den Rohdaten ergeben haben und Ihre Arbeit bleibt komplett transparent. 

* Ein Ordner `R`, der alle R Skripte enthält, also alle Textdokumente, die R 
Code enthalten.

* Ein Ordner `output`, in dem der Output ihrer Berechnungen, z.B. Tabellen oder
Plots, gespeichert werden können. Der Inhalt dieses Ordners sollte sich komplett
mit den Inhalten der Ordner `data` und `R` replizieren lassen.

* Ein Ordner `text`, in dem Sie Ihre Verschriftlichungen speichern, z.B. das
eigentliche Forschungspapier, ihre Hausarbeit oder Ihre Vorlesungsmitschriften.

* Einen Ordner `misc` in den Sie alles packen, was in keinen der anderen 
Ordner passt. Ein solcher Ordner ist wichtig und Sie sollten nicht zuordbare
Dateien bis auf wenige Ausnahmen nicht in den übergeordneten Projektordner 
als solchen speichern. Ausnahmen sind z.B. die `.Rproj`-Datei, ggf. die 
Lizenz ihres Programmes oder eine Readme-Datei, welche die Funktion ihres
Codes und ihre Ordnerstruktur erklärt.

Wenn wir annehmen unser Projektordner heißt `Methodenprojekt` ergibt sich damit 
insgesamt die in Abbildung \@ref(fig:folder) dargestellte Ordner und Datenstruktur.

```{r folder, echo=FALSE, fig.align='center', out.height='50%', fig.cap="Die vorgeschlagene Ordnerstruktur für R-Projekte."}
knitr::include_graphics(
  here::here("figures/Einrichtung/wd-structure.png"), auto_pdf = T)
```

In einem vierten Schritt sollten Sie nun noch eine `.here`-Datei erstellen.
Da dies jedoch die Verwendung von Paketen voraussetzt sollten Sie den nächsten
Abschnitt zunächst überspringen, wenn Sie noch nicht wissen wie man R-Pakete
verwendet und den Abschnitt zu einem späteren Zeitpunkt lesen (R-Pakete werden
in Abschnit \@ref(es:pakete) von Kapitel \@ref(basics) eingeführt).

## Optional: Schritt 4 und das here-Paket

Es gibt einen weiteren Schritt, den Sie bei der Einrichtung eines neuen Projekts
immer durchführen sollten. 
Dieser Schritt beinhaltet die Verwendung des R-Pakets 
[here](https://github.com/r-lib/here) [@here].
Falls Sie noch nicht mit der Verwendung von R-Paketen vertraut sind, sollten Sie
diesen Abschnitt zunächst überspringen. 
Pakete werden in Abschnitt \@ref(es:pakete) in Kapitel \@ref(basics) eingeführt 
und es macht Sinn, wenn Sie später nach Lektüre dieses Abschnitts noch einmal 
hierher zurückkehren.

Wie weiter oben beschrieben sollten Sie in der alltäglichen Arbeit immer
*relative* Pfade verwenden. 
In zwei Situationen kann die Verwendung von relativen Pfaden aber problematisch
sein: (1) in der Zusamenarbeit mit anderen und (2) bei der Verwendung von 
R-Markdown.^[Mit R Markdown können Sie in R direkt Texte schreiben und somit
die statistische Analyse und die Beschreibung der Ergebnisse in einem Dokument
integrieren. Dieses Buch ist z.B. auch vollständig in R-Markdown geschrieben.
Eine kurze Einführung finden Sie in Kapitel \@ref(markdown).]

Gerade wenn Sie ein Skript einmal an eine\*n Kollege\*in schicken wollen und 
diese\*r nicht das ganze R Projekt öffnet kommt es schnell zu Fehlermeldungen.
Glücklicherweise gibt es eine recht einfache Lösung für alle derartigen 
Probleme: das Paket [here](https://github.com/r-lib/here) [@here].
Durch Einlesen des Pakets erhalten Sie Zugriff auf die Funktion (Überraschung!) 
`here()`.
Diese Funktion nimmt nur ein einziges Argument und zwar einen relativen Pfad.
Die Funktion wandelt diesen relativen Pfad automatisch in einen absoluten Pfad um.
Dabei berücksichtigt sie die individuelle Ordnerstruktur von dem Computer, auf
dem sie aktuell ausgeführt wird. 
Das bedeutet, dass Sie für unterschiedliche Computer unterschiedliche Ergebnisse
liefert.
Anhand eines Beispiels lässt sich das am einfachsten nachvollziehen.
Gehen wir davon aus, dass Birte und Claudius gemeinsam an einem R-Skript 
arbeiten.
Im Code kommt dabei folgende Zeile vor:

```{r, eval=FALSE}
write(c(1,2,3), file = "output/vektor.txt")
```

Hier wird ein Vektor in einer Textdatei im Unterordner `output/` gespeichert.
Damit R die Datei am richtigen Ort speichert müssen Birte und Claudius das gleiche
Arbeitsverzeichnis verwenden, sonst wirkt der relative Pfad auf ihren jeweiligen
Computern anders. 
Alternativ könnte Claudius den Pfad auch absolut angeben:

```{r, eval=FALSE}
write(c(1,2,3), 
      file = "/Users/claudius/projekte/R-Projekt-Birte/output/vektor.txt")
```

Dann würde die Datei auf seinem Computer immer am richtigen Ort gespeichert,
egal in welchem Arbeitsverzeichnis er sich gerade befindet.
Wenn Birte nun allerdings diesen Code bei sich ausführt wird sie mit ziemlicher
Sicherheit eine Fehlermeldung erhalten. 
Denn auf ihrem Computer liegt das Skript bestimmt an einem anderen Ort. 
Sie müsste also z.B. schreiben:

```{r, eval=FALSE}
write(c(1,2,3), 
      file = "/Users/birte/projekte/R-Projekt-Claudius/output/vektor.txt")
```

Dieser Code wiederum würde bei Claudius nicht funktionieren.
Natürlich könnten die beiden den Code immer individuell vor dem Ausführen auf 
ihrem Computer anpassen.
Das wäre allerdings nervig und Sie sollten Ihren Code immer so schreiben, 
dass er ohne Modifikation auf unterschieldlichen Computern funktioniert.
Sonst macht Zusammenarbeit wenig Spaß.

Die Funktion `here()` löst dieses Problem.
Hier könnten die beiden einfach schreiben:

```{r, eval=FALSE}
write(c(1,2,3), file = here::here("output/vektor.txt"))
```

Die Funktion `here()` baut dann automatisch einen absoluten Pfad.
Der Output von `here("output/vektor.txt")` sähe auf Claudius' Computer so aus:

```
~/claudius-projekte/R-Projekt-Birte/output/vektor.txt
```

Und auf Birte's Computer aber so:

```
~/birte-projekte/R-Projekt-Claudius/output/vektor.txt
```

So können die beiden den Code einfach untereinander tauschen ohne den Code jeweils
auf ihren Computern verändern zu müssen.
Daher, und aufgrund einiger anderer potenzieller Schwierigkeiten, denen wir
erst später begegnen werden, lohnt es sich immer das Paket `here` zu verwenden
und relative Pfade immer gemeinsam mit der Funktion `here()` anzugeben.
Das ist ein kleiner Mehraufwand, der auf Dauer aber viel Ärger spart.

Damit das problemlos funktioniert lohnt es sich, dem `here` Paket den 
Ausgangspunkt für die relativen Pfade explizit mitzuteilen. 
Dafür muss beim Erstellen eines Arbeitsverzeichnis *einmalig* eine Datei 
`.here` erstellt werden, und zwar in dem Ordner, der als Ausgangspunkt für
die relativen Pfade fungieren soll. 
Das ist in aller Regel der Ordner, in dem auch die `.Rproj` Datei liegt.^[
Strikt genommen ist das Erstellen der `.here` Datei nicht nötig, da 
`here()` im Zweifel von dem Ordner als Ausgangspunkt ausgeht, in dem es die
nächste `.Rproj`-Datei findet. Es ist aber besser hier explizit zu seine
`.here`-Datei beim Einrichten eines neuen Projekts immer mit zu erstellen.
Dann funktioniert der Code in jedem Fall immer.
]
Damit würde sich die in Abbildung \@ref(fig:folderfinal) dargestellte Ordner- 
und Datenstruktur ergeben.

```{r folderfinal, echo=FALSE, fig.align='center', out.height='50%', fig.cap="Die vorgeschlagene Ordnerstruktur für R-Projekte inklusive der .here-Datei."}
knitr::include_graphics(
  here::here("figures/Einrichtung/wd-structure-here.png"), auto_pdf = T)
```

dargestellte Struktur.

Dazu führen wir nach Schritt 3 noch folgende Befehle aus:

```{r, eval=FALSE}
here::here()
```

Wenn der angezeigte Pfad mit dem Pfad zu Ihrem gewünschten Arbeitsverzeichnis
übereinstimmt, führen Sie nun folgenden Befehl aus:

```{r, eval=FALSE}
here::set_here()
```

Falls nicht geben Sie der Funktion `here::set_here()` den absoluten Pfad
zu Ihrem Arbeitsverzeichnis als Argument, z.B.:

```{r, eval=FALSE}
here::set_here("/Users/claudius/projekte/R-Projekt-Birte")
```

Sie sollten nun eine Nachricht bekommen haben, dass in Ihrem Arbeitsverzeichnis
eine neue Datei `.here` erstellt wurde.
Damit ist die Einrichtung Ihres Projekts vollständig abgeschlossen.


## Abschließende Bemerkungen

Eine gute Ordnerstruktur ist nicht nur absolut essenziell um selbst einen 
Überblick über seine Forschungsprojekte zu behalten, sondern auch wenn man
mit anderen Menschen kollaborieren möchte, da jegliche Kollaboration durch eine gut durchdachte Ordnerstruktur massiv erleichtert wird.
In einem solchen Fall sollte man auf jeden Fall eine Versionskontrolle wie Git 
und GitHub verwenden.
Eine (optionale) kurze Einführung in Git und Github finden Sie in Kapitel
\@ref(git).