pwquint24/org-babel-r

R-Quellcodeblöcke in Org Babel

Die Verwendung von R mit Org Babel bietet eine Umgebung für statistisches Rechnen, Datenanalyse, Grafikerstellung und reproduzierbare Forschungspapiere. R-Codeblöcke im Org-Modus integrieren sich mit ESS (Emacs Speaks Statistics), um interaktive Ausführung, gemeinsame Zustandsnutzung über mehrere Blöcke, publikationsreife Grafiken und strukturierte Tabellenexporte zu unterstützen.

---

1. Einrichtung und Umgebungskonfiguration

1.1 Voraussetzungen

1. Eine funktionierende R-Installation (CRAN-Binär oder aus dem Quellcode erstellt).
2. ESS (Emacs Speaks Statistics) installiert über MELPA (erforderlich für sitzungsbasierte Auswertung und Schritt-für-Schritt-Ausführung).
3. ob-R aktiviert in org-babel-load-languages.

1.2 Emacs-Konfigurationsvorlage

Fügen Sie Folgendes zu Ihrer init.el hinzu:

;; 1. MELPA konfigurieren
(require 'package)
(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t)
(package-initialize)

;; 2. Sicherstellen, dass ESS geladen ist
(unless (package-installed-p 'ess)
  (package-refresh-contents)
  (package-install 'ess))
(require 'ess-r-mode)

;; 3. R in Org Babel aktivieren
(org-babel-do-load-languages
 'org-babel-load-languages
 '((emacs-lisp . t)
   (R          . t)))

;; 4. Optional: Blöcke ohne interaktive Sicherheitsbestätigungen ausführen
(setq org-confirm-babel-evaluate nil)

1.3 Windows-spezifische Einrichtung

Unter Microsoft Windows, wenn Emacs The system cannot find the path specified meldet, setzen Sie explizit den Pfad zur R-Binärdatei (einschließlich der Standard-Babel-Flags --slave --no-save):

;; Für 64-Bit-Windows:
(setq org-babel-R-command "C:/Progra~1/R/R-4.3.0/bin/x64/R --slave --no-save")

Hinweis: Bei Verwendung von :session wird org-babel-R-command ignoriert und stattdessen inferior-ess-R-program von ESS verwendet.

---

2. Ausführungsmodi: Sitzungen und ESS-Integration

2.1 Keine Sitzung (:session none, Standard)

Wird in einem separaten Batch-R-Prozess ausgeführt (R --slave --no-save). Sauber, isoliert und nebenwirkungsfrei, führt aber jedes Mal alle Bibliotheken und Datenladeprozesse erneut aus.

2.2 Interaktive Sitzungen (:session <name>)

Wird innerhalb eines untergeordneten ESS-R-Prozesses ausgeführt (*<name>*).

• Datensätze, Bibliotheken, Modelle und Variablen bleiben über mehrere Blöcke hinweg erhalten, die denselben Sitzungsnamen verwenden.
• Ermöglicht interaktive Inspektion, Debugging und schnelle iterative Arbeitsabläufe.

#+PROPERTY: header-args:R :session *r-analysis* :results value :exports both

2.3 Interaktives Debugging und Schritt-für-Schritt-Ausführung mit ESS

Bei der Fehlerbehebung von R-Blöcken:

1. Zur Sitzung wechseln: Mit dem Cursor in einem R-Block drücken Sie M-<down> (org-babel-pop-to-session) oder C-c C-z (ess-switch-to-end-of-ESS), um zum R-REPL-Puffer zu springen.
2. Umgebung inspizieren: Verwenden Sie ls(), str(x), dim(x), summary(x) oder head(x).
3. Schritt-für-Schritt-Ausführung:
   • Drücken Sie C-c ' (org-edit-special) innerhalb des Org-Blocks, um den dedizierten ESS-R-Puffer zu öffnen.
   • Verwenden Sie C-c C-n (ess-eval-line-and-step) oder C-c C-c (ess-eval-region-or-function-or-paragraph), um Code Zeile für Zeile im laufenden R-Prozess durchzugehen.
   • Drücken Sie C-c ', um zum Org-Dokument zurückzukehren.

---

3. Ergebnisverarbeitung: Data Frames, Werte und Tabellen

3.1 Zurückgeben von Tabellendaten (:results value table)

Beim Zurückgeben von Data Frames, Matrizen oder Vektoren konvertiert Org Babel diese direkt in native Org-Tabellen:

#+NAME: mtcars_summary
#+BEGIN_SRC R :session *r* :results value table :colnames yes
  aggregate(mpg ~ cyl + gear, data=mtcars, FUN=mean)
#+END_SRC

#+RESULTS: mtcars_summary
| cyl | gear |              mpg |
|-----+------+------------------|
|   4 |    3 |            21.5  |
|   6 |    3 | 19.7500000000000 |
|   8 |    3 | 15.0500000000000 |
|   4 |    4 |            26.92 |
|   6 |    4 |            19.75 |
|   4 |    5 |             28.2 |
|   6 |    5 |             19.7 |
|   8 |    5 |            15.4  |

• Fügen Sie :colnames yes immer hinzu, wenn Sie mit Data Frames arbeiten, um Spaltennamen korrekt zu erhalten und anzuzeigen.
• In R wird der Wert des zuletzt ausgewerteten Ausdrucks automatisch zurückgegeben (kein explizites return() erforderlich).

3.2 Erfassen der Konsolenausgabe (:results output)

Verwenden Sie :results output, um stdout, Modellausdrucke oder Zusammenfassungsstatistiken zu erfassen:

#+BEGIN_SRC R :session *r* :results output
  fit <- lm(mpg ~ wt + hp, data=mtcars)
  summary(fit)$coefficients
#+END_SRC

#+RESULTS:
:               Estimate Std. Error   t value     Pr(>|t|)
: (Intercept) 37.2272694 1.59878754 23.284688 2.565459e-20
: wt          -3.8778307 0.63273349 -6.128695 1.119647e-06
: hp          -0.0317729 0.00902971 -3.518708 1.451229e-03

---

4. Grafiken und Visualisierungen

4.1 Basis-Grafikregel (Org $\ge$ 9.3)

Um Grafiken zu erzeugen, geben Sie sowohl file als auch graphics in :results sowie den Ausgabedateinamen in :file an:

:results graphics file :file <pfad.endung>

Unterstützte Dateierweiterungen und entsprechende R-Geräte:

• Vektor: .pdf, .svg, .ps / .postscript, .tex (TikZ)
• Raster: .png, .jpg / .jpeg, .tiff, .bmp
• Standard-Fallback: .png

#+BEGIN_SRC R :file figures/base_plot.png :results graphics file :width 600 :height 400 :res 120
  plot(mtcars$wt, mtcars$mpg, pch=19, col="darkblue",
       xlab="Gewicht (1000 lbs)", ylab="Meilen pro Gallone",
       main="Kraftstoffverbrauch")
  abline(lm(mpg ~ wt, data=mtcars), col="red", lwd=2)
#+END_SRC

#+RESULTS:
[[file:figures/base_plot.png]]

4.2 Die kritische Regel für ggplot2 / Lattice („Grid Graphics“)

Falle: Lattice (xyplot) und ggplot2-Funktionen geben grafische Objekte zurück. Bei nicht-interaktiver Batch-Auswertung (ohne Sitzung) erzeugt die Rückgabe des Objekts ohne Drucken eine leere/beschädigte Grafikdatei!

Es gibt drei zuverlässige Methoden, um ggplot2 / Lattice-Diagramme in Org Babel darzustellen:

Methode A: Explizites print() (Empfohlen für Nicht-Sitzungen)

#+BEGIN_SRC R :file figures/dist.png :results graphics file
  library(ggplot2)
  p <- ggplot(mtcars, aes(x=mpg)) + geom_histogram(bins=10, fill="steelblue")
  print(p)  # Explizites print() löst das Rendern des Grafikgeräts aus
#+END_SRC

Methode B: :session verwenden (Druckt automatisch interaktiv)

#+BEGIN_SRC R :session *r* :file figures/dist.png :results graphics file
  library(ggplot2)
  ggplot(mtcars, aes(x=mpg)) + geom_histogram(bins=10, fill="steelblue")
#+END_SRC

Methode C: :results output graphics file verwenden

#+BEGIN_SRC R :file figures/dist.png :results output graphics file
  library(lattice)
  xyplot(mpg ~ wt, data=mtcars)
#+END_SRC

---

5. R-Grafikgerät-Kopfargumente

Org Babel bietet erstklassige Kopfargumente, die direkt auf Parameter von R-Grafikgeräten (png(), pdf(), svg(), etc.) abbilden:

Kopfargument	Standard	Beschreibung und zulässige Werte
:width	7 (in) / 480 (px)	Gerätebreite.
:height	7 (in) / 480 (px)	Gerätehöhe.
:units	px (Raster), in (PDF)	Einheiten: "px", "in", "cm", "mm".
:res	72	Nominelle Auflösung in Pixeln pro Zoll (DPI). (Wesentlich für scharfe Rastergrafiken: Verwenden Sie 150-300).
:bg	"white"	Hintergrundfarbe (z. B. "transparent", "#f7f7f7").
:fg	"black"	Vordergrundfarbe.
:pointsize	12	Basis-Punktgröße für die Textdarstellung.
:family	"Helvetica"	Schriftfamilie ("Helvetica", "Times", "Palatino", "Courier", "sans", "serif", "mono").
:quality	75	JPEG-Qualitätsprozentsatz (1-100).
:type	Plattformstandard	Bitmap-Renderer: "cairo", "quartz" oder "Xlib".
:paper	"special"	PDF-Papierformat: "special", "a4", "letter", "a4r" usw.
:R-dev-args	nil	Roher Text zusätzlicher R-Geräteargumente, die direkt an die Gerätefunktion übergeben werden.

Beispiel: High-DPI Cairo-SVG/PNG mit benutzerdefinierten Abmessungen

#+NAME: custom_styled_plot
#+HEADER: :width 8 :height 5 :units in :res 300 :type cairo
#+HEADER: :R-dev-args bg="#fcfcfc"
#+BEGIN_SRC R :session *r* :file figures/styled_plot.png :results graphics file
  library(ggplot2)
  ggplot(diamonds[1:1000, ], aes(x=carat, y=price, color=cut)) +
    geom_point(alpha=0.6) +
    theme_minimal(base_family="sans") +
    labs(title="Diamantpreise nach Karat und Schliff")
#+END_SRC

5.3 TikZ-LaTeX-Grafiken für passende Dokumentenschriftarten

Um Diagramme zu erstellen, deren Achsenbeschriftungen und mathematische Anmerkungen exakt dieselbe LaTeX-Schriftart wie Ihr Dokument verwenden:

#+BEGIN_SRC R :file figures/model_plot.tex :results graphics file
  plot(1:10, type="b", main="\\textbf{TikZ-Diagramm mit Mathematik: } $\\int_0^1 x^2 dx$")
#+END_SRC

Beim Export nach LaTeX/PDF wird die .tex-Datei nativ über \input{figures/model_plot.tex} eingebunden!

---

6. Erweiterte formatierte Ausgaben (ASCII, Org und LaTeX)

6.1 Formatierte Org-Ausgabe mit dem Paket ascii

Das R-Paket ascii kann komplexe, nicht-tabellarische R-Objekte (wie describe(), table() oder summary()) in native Org-Syntax umwandeln:

#+BEGIN_SRC R :session *r* :results output org
  library(ascii)
  options(asciiType = "org")
  tab <- table(mtcars$cyl, mtcars$gear)
  ascii(tab, caption="Zylinder vs. Vorwärtsgänge")
#+END_SRC

#+RESULTS:
#+BEGIN_ORG
#+CAPTION: Zylinder vs. Vorwärtsgänge
|   | 3  | 4 | 5 |
|---+----+---+---|
| 4 | 1  | 8 | 2 |
| 6 | 2  | 4 | 1 |
| 8 | 12 | 0 | 2 |
#+END_ORG

6.2 Publikationstabellen mit xtable für den LaTeX-Export

Für Dokumente, die über LaTeX-Export auf PDF abzielen, verwenden Sie xtable mit :results output latex:

#+BEGIN_SRC R :results output latex :exports results
  library(xtable)
  fit <- lm(mpg ~ wt + hp, data=mtcars)
  print(xtable(summary(fit), caption="Regressionsschätzungen", label="tab:reg"),
        comment=FALSE)
#+END_SRC

#+RESULTS:
#+BEGIN_LaTeX
\begin{table}[ht]
\centering
\begin{tabular}{rrrrr}
  \hline
 & Estimate & Std. Error & t value & Pr($>$$|$t$|$) \\ 
  \hline
(Intercept) & 37.2273 & 1.5988 & 23.28 & 0.0000 \\ 
  wt & -3.8778 & 0.6327 & -6.13 & 0.0000 \\ 
  hp & -0.0318 & 0.0090 & -3.52 & 0.0015 \\ 
   \hline
\end{tabular}
\caption{Regressionsschätzungen} 
\label{tab:reg}
\end{table}
#+END_LaTeX

---

7. Fehlerbehebung und häufige Fallstricke

Problem	Ursache	Lösung
ggplot2 oder Lattice erzeugt leeres/beschädigtes Bild	Das zurückgegebene Grafikobjekt wurde im Nicht-Sitzungsmodus nicht explizit gedruckt	Wickeln Sie das Diagramm in print(p), wechseln Sie zu :session, oder fügen Sie output zu :results output graphics file hinzu.
Grafikdatei erstellt, aber kein Link eingefügt	Fehlendes Schlüsselwort file oder graphics	Stellen Sie sicher, dass der Header :results graphics file enthält (beide Wörter erforderlich in Org $\ge$ 9.3).
The system cannot find the path specified (Windows)	R-Ausführbare Datei nicht im PATH oder an benutzerdefiniertem Ort gefunden	Setzen Sie (setq org-babel-R-command "pfad/zu/R --slave --no-save") in der init.el.
Spalten werden in Zeile 0 von R-Data-Frames konvertiert	Tabellenkopfzeilen werden als Beobachtungsdaten behandelt	Fügen Sie :colnames yes zu den Block-Kopfargumenten hinzu.
Sitzungs-R hängt bei großer Berechnung	Der Block blockiert den Emacs-Prozess	Wechseln Sie zum untergeordneten ESS-Puffer (C-c C-z), um den Fortschritt zu überwachen, oder unterbrechen Sie mit C-c C-c.
Verschwommene Diagramme in exportierten Dokumenten	Standard-Raster-DPI (72) ist zu niedrig	Fügen Sie :res 300 hinzu und passen Sie :width und :height entsprechend an.