7 Literate programming in R
Beim Literate programming wird Programmcode und Dokumentation miteinander kombiniert, dabei entsteht ein Dokument das eine Mischung Code und Dokumentation ist. Der Programmiercode wird in kleine, verständliche Einheiten (sogenannte Chunks) unterteilt, diese Chunks werden mit Kommentaren und Erklärungen versehen. Diese Einheiten werden dann in einer logischen Reihenfolge angeordnet, die dem Leser den Zweck und die Funktionsweise des Programms vermittelt. Dadurch fördert Literate programming die Wiederverwendbarkeit, Lesbarkeit und Wartbarkeit von Code. Im Rahmen von Datenanalysen entsteht so ein dynamisches Dokument das alle Analyseschritte durchführt und auch gleichzeitig diese Dokumentiert bzw. beschreibt. Dies kann direkt aus R heraus generiert werden. Dies führt dazu, dass Daten, deren Verarbeitung und die Dokumentation und Interpretation in einer Einheit integriert sind. Letztendlich entsteht so die Möglichkeit auch direkt fertig formatierte Publikationen aus R heraus zu generieren.
In R gibt es derzeit drei, eigentlich zweieinhalb, verschiedene Methoden um Literatue Programming durchzuführen. Das klassische RSweave-Format, dass auf der Integration von R-Code und LaTex beruht, das modernere RMarkdown bei dem R-Code und Markdown-Syntax miteinander verbunden werden und die überarbeitete Version von RMarkdown genannt Quarto. Bei Quarto wird wie bei RMarkdown R-Code mit Markdown integriert und mittels spezieller Angaben in einem Header in der sogenannten YAML-Syntax gesteuert. Im Rahmen des Skripts beschäftigen wir uns nur mit Quarto.
Allgemein handelt es sich bei Quarto um ein Open-Source System für wissenschaftliche und technische Veröffentlichungen welches Literate Programming implementiert. Mittels Quarto können eine ganze Reihe von unterschiedlichen Dokumenten erstellt werden von wissenschaftlichen Zeitschriftenartikel bis zu kompletten Bücher und Webseiten. Tatsächlich ist das vorliegende Skriptum ebenfalls mit Quarto erstellt worden.
7.1 R Projekte
Bevor wir mit Quarto anfangen, lernen wir kurz noch R-Projekte kennen, da diese eine deutliche Vereinfachung des Arbeitsprozesses mit R ermöglichen.
Wenn eine Datenanalyse durchführt wird, ist es von großem Vorteil wenn alle für die Analyse notwendigen Informationen wie Daten, Ergebnisse, Zwischenrechnungen usw. an einem gemeinsamen Ort abgespeichert sind. Eine einfache Lösung bietet eine dedizierter Verzeichnisordner der mit Unterordnern so strukturiert ist, dass die Projektdateien systematisch organisiert sind und am Besten bestimmten (möglicherweise eigenen) Konvention folgt. So kann sicher gestellt werden, dass wenn Analysen zu späteren Zeitpunkten wieder durchgeführt werden nahtlos an den letzten Stand angeknüpft werden kann. In RStudio ist speziell zu diesem Zweck ein Prozess erstellt worden der diesen Ansatz formalisiert. RStudio bietet dazu die Möglichkeit ein Project zu erstellen. Unter (File/New Project) kann dazu ein Projekt erstellt werden.
Sobald ein Projekt in RStudio erstellt wurde, d.h. ein Namen vergeben wurde und ein Verzeichnis, das Wurzelverzeichnis, ausgewählt wurde wo das Projekt auf dem Computer hinterlegt ist, springt R in dieses Wurzelverzeichnis und macht das Verzeichnis zum Arbeitsverzeichnis. Da das Wurzelverzeichnis nichts von Standardverzeichnissen auf dem Computer unterscheidet können weitere Unterverzeichniss wie zum Beispiel data, specs, analysis oder was auch immer benötigt wird beliebig erstellen werden. Das Projekt kann in RStudio geöffnet oder geschlossen werden. Beim Öffnen springt R immer automatisch in das Wurzelverzeichnis und stellt so sicher, dass alle relativen Pfade zu Dateien korrekt aufgelöst werden können.
Eine Regel sollte im Umgang mit Projekten beachtet werden. Wann immer auf eine Datei zugriffen wird, dann sollten relative Pfadangabe verwendet werden. Also, anstatt D:/studium/master/data/studie_01.txt, Pfade in der Form /data/studie_01.txt. Durch die Verwendung von relativen Pfade, können Projekte problemlos zwischen Rechnern transferieren (migriert) werden. Die relativen Pfade stellen sicher, dass die Position von Dateien immer in Relation zum Wurzelverzeichnis des Projekt lokalisiert werden.
Wenn ein Projekt in RStudio neu erstellt wird, dann generiert RStudio eine Konfigurationsdatei mit der Endung .Rproj in der noch weitere Einstellungen gespeichert werden. Diese können über die Projekteinstellungen über den Menupunkt (Tools/Project Options) anpassen.
7.2 Quarto-Dokumente
7.2.1 Markdown
Bei Quarto-Dokumenten handelt es sich um Dateien mit der Endung .qmd, die gleichzeitig Text wie auch R-Code enthalten können. Die Textsegmente sind dabei nicht nur einfache Kommentare (#) im Code, sondern vollständig formatierte Textsegmente, wie wir sie aus Word und ähnlichen Programmen kennen. Die Formatierung der Textkomponenten erfolgt mit der sogenannten Markdown-Syntax. Markdown ist eine einfache Auszeichnungssprache die es erlaubt Formatierungsanweisungen in den Text zu integrieren.
Soll zum Beispiel eine Wort fett gedruckt werden, dann wird das Wort mit zwei ** eingeschlossen. In Tabelle 7.1 sind ein paar Beispiel angezeigt.
| Markdown Syntax | Formatierung |
|---|---|
| `kursiv, fett, | kursiv, fett, |
hoch^2^ , tief~2~ |
hoch2 , tief2 |
~~durchgestrichen~~ |
D.h. mittels Markdown wird die Formatierung von Text mit relativ einfach Sonderzeichen durchgeführt. So können beispielsweise Listen mittels der folgenden Formatierung definiert werden (siehe Tabelle 7.2).
| Markdown Syntax | Formatierung |
|---|---|
* ungeordnete Liste + Unterelement 1 + Unterelement 2 - Unterunterelement 1 |
|
1. geordnete Liste 2. Element 2 i) Unterelement 1 A. Unterunterelement 1 |
|
Markdown im Zusammenspiel mit Quarto bietet alle nur erdenklichen Formatierungsmöglichkeiten und Feinheiten um die gewünschten Formatierungen einzustellen. Da die verschiedenen Begriffe den Umfang des Skripts deutlich sprengen würden wird hier darauf verzichtet den gesamten Umfang von Quarto und Markdown zu beschreiben. Da Quarto zudem ein noch relativ neues Projekt ist kommen immer wieder neue Features dazu. Daher sollte die sehr gute Dokumentation von Quarto immer die erste Adresse für alle Fragen sein. Der große Vorteil von Quarto + Markdown besteht letztendlich darin, dass alle Dokumente nichts weiteres als Textdateien sind und letztendlich nicht einmal nur mit RStudio bearbeitet werden müssen sondern mittels jedes beliebigen Texteditor erstellt und verändert werden können.
7.2.2 R-Code in Quarto-Dokumenten
D R-Code in Quarto-Dokumente integriert ist, schaun wir uns noch kurz die Erstellen von Chunks (auch Code blocks genannt) an.
Von R auszuführende Codeblöcke werden ebenfalls mittels spezieller Formatierungszeichen ausgezeichnet. Der Anfang eines Codeblocks wird mit drei backticks (SHIFT+´) gefolgt von {r} eingeleitet. Das Endes des Codeblock wird mittels dreier backticks abgeschlossen. ```{r} R Code). Diese Codeblöcke werden während des rendern, also des Formatierens des Quarto-Dokuments, intern durch R ausgeführt.
In R-Studio ist der short-cut definiert um einen Codeblock an der aktuellen Cursorposition einzufügen.
Ein Beispiel für einen einfachen Codeblock sieht dann wie folgt aus:
```{r}
a <- 3
b <- 4
a + b
```Die Variablen die in den jeweiligen Codeblöcken definiert werden stehen in weiteren, nachfolgenden Codeblöcken in dem Quartodokument zur Verfügung.
Einzelne Codeblöcke können in R-Studio getrennt ausgeführt werden. Dazu muss der Cursor in dem Block sein und entweder mit PLAY-Button oben-recht im Block oder mit dem short-cut . Um das ganze Dokument zu rendern kann entweder der Render-Button oberhalb des Dokuments verwendet werden oder wiederum der short-cut .
Wenn wir unseres vorhergehendes Workflow-Beispiel nehmen, dann könnte ein gekürztes Quarto-Dokument wie folgt aussehen:
---
title: "Analyse des Körperfettgehalts in zwei Gruppen"
author: "Martina Muster"
---
# Einleitung
Nach Schmidt et al. (2023) ist davon auszugehen, dass eine Manipulation von XYZ
dazu führt, dass ... . Diese Hypothese soll anhand einer neuen Stichprobe
überprüft werden.
# Methodik
...
# Analyse
## Bibliotheken
Für die Bearbeitung der Daten, werden die folgenden Bibliotheken benötigt.
```{r}
library(readr)
library(ggplot2)
library(dplyr)
```
## Daten einlesen
Die Rohdaten befinden sich in der Textdatei "bfp_data.txt".
**Achtung**, darauf achten, dass der Dateipfad korrekt ist.
```{r}
bfp <- read_csv(file = 'bfp_data.txt')
```
## Daten bearbeiten
Ein Datenpunkt ist ~fehlerhaft~, und zeigt einen Wert von $BFP > 100$, was
nicht physiologisch plausibel. Daher wird dieser Wert ausgeschlossen.
```{r}
bfp_clean <- filter(bfp, BFP <= 100)
```
Die Daten zur Analyse befinden sich jetzt in der Variablen `bfp_clean`.
# Diskussion
...
# Zusammenfassung
...Zu Beginn des Quarto-Dokuments findet sich ein Abschnitt der mit --- abgegrenzt ist. Dies ist der sogenannte YAML-Header. YAML ist ebenfalls eine einfache Auszeichnungssprache (yet another markup language). Im Header werden verschiedene Formatierungseinstellung für das Quarto-Dokument definiert. Hier können zum Beispiel auch weitere Dokumente wie Zitationsbibliotheken und Zitationsstyle eingebunden werden, da Quarto die Integration von Referenzen und Zitationen innerhalb der Dokumente vollständig unterstützt. Wie bereits erwähnt ist das Quarto-System sehr umfangreich und kann hier leider nicht weiter besprochen werden.