Org Babel 中的 R 源代码块
在 Org Babel 中使用 R 为统计计算、数据分析、图形生成和可重复研究论文提供了一个环境。Org Mode 中的 R 代码块与 ESS（Emacs Speaks Statistics） 集成，支持交互式执行、多块状态共享、出版质量的图形和结构化的表格导出。
1. 设置与环境配置
1.1 前提条件
- 一个可用的 R 安装（CRAN 二进制或从源代码构建）。
- 通过 MELPA 安装 ESS（Emacs Speaks Statistics）（需要用于基于会话的评估和逐步执行）。
- 在
org-babel-load-languages中启用ob-R。
1.2 Emacs 配置模板
将以下内容添加到您的 init.el：
;; 1. 配置 MELPA
(require 'package)
(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t)
(package-initialize)
;; 2. 确保加载 ESS
(unless (package-installed-p 'ess)
(package-refresh-contents)
(package-install 'ess))
(require 'ess-r-mode)
;; 3. 在 Org Babel 中启用 R
(org-babel-do-load-languages
'org-babel-load-languages
'((emacs-lisp . t)
(R . t)))
;; 4. 可选：运行块时无需交互式安全确认提示
(setq org-confirm-babel-evaluate nil)
1.3 Windows 特定设置
在 Microsoft Windows 上，如果 Emacs 报告“系统找不到指定的路径”，请显式设置 R 二进制路径（包括默认的 Babel 标志 --slave --no-save）：
;; 对于 64 位 Windows：
(setq org-babel-R-command "C:/Progra~1/R/R-4.3.0/bin/x64/R --slave --no-save")
注意： 当使用 :session 时，org-babel-R-command 被忽略，而使用 ESS 的 inferior-ess-R-program。
2. 执行模式：会话与 ESS 集成
2.1 非会话模式（:session none，默认）
在单独的批处理 R 进程（R --slave --no-save）中运行。干净、隔离且无副作用，但每次都会重新执行所有库和数据加载。
2.2 交互式会话（:session <name>）
在 inferior ESS R 进程（*<name>*）内运行。
- 数据集、库、模型和变量在共享相同会话名称的多个块之间持久存在。
- 支持交互式检查、调试和快速迭代工作流。
#+PROPERTY: header-args:R :session *r-analysis* :results value :exports both
2.3 使用 ESS 进行交互式调试和逐步执行
在排除 R 块故障时：
- 切换到会话： 将光标置于 R 块内，按
M-<down>（org-babel-pop-to-session）或C-c C-z（ess-switch-to-end-of-ESS）跳转到 R REPL 缓冲区。 - 检查环境： 使用
ls()、str(x)、dim(x)、summary(x)或head(x)。 - 逐行逐步执行：
- 在 Org 块内按
C-c '（org-edit-special）进入专用的 ESS R 缓冲区。 - 使用
C-c C-n（ess-eval-line-and-step）或C-c C-c（ess-eval-region-or-function-or-paragraph）在活动的 R 进程中逐行执行代码。 - 按
C-c '返回 Org 文档。
- 在 Org 块内按
3. 结果处理：数据框、值和表格
3.1 返回表格数据（:results value table）
当返回数据框、矩阵或向量时，Org Babel 会将其直接转换为原生 Org 表格：
#+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 |
- 在处理数据框时，始终添加
:colnames yes以正确保留和显示列名。 - 在 R 中，最后一个表达式的值会自动返回（无需显式
return()）。
3.2 捕获打印的控制台输出（:results output）
使用 :results output 捕获标准输出、模型打印输出或摘要统计信息：
#+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. 图形与可视化
4.1 基础图形规则（Org ≥ 9.3）
要生成图形，请在 :results 中指定 同时 包含 file 和 graphics，并在 :file 中指定输出文件名：
:results graphics file :file <path.ext>
支持的文件扩展名和相应的 R 设备：
- 矢量：
.pdf、.svg、.ps/.postscript、.tex（TikZ） - 光栅：
.png、.jpg/.jpeg、.tiff、.bmp - 默认回退：
.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="Weight (1000 lbs)", ylab="Miles per Gallon",
main="Fuel Economy")
abline(lm(mpg ~ wt, data=mtcars), col="red", lwd=2)
#+END_SRC
#+RESULTS:
[[file:figures/base_plot.png]]
4.2 关键的 ggplot2 / Lattice “网格图形” 规则
陷阱： Lattice（xyplot）和 ggplot2 函数返回图形 对象。在非交互式批处理评估（非会话）中，返回对象而不打印它会导致图形文件为空或损坏！
在 Org Babel 中渲染 ggplot2 / Lattice 图形有三种 可靠的方式：
方法 A：显式 print()（非会话模式推荐）
#+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) # 显式 print() 触发图形设备渲染
#+END_SRC
方法 B：使用 :session（交互式自动打印）
#+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
方法 C：使用 :results output graphics file
#+BEGIN_SRC R :file figures/dist.png :results output graphics file
library(lattice)
xyplot(mpg ~ wt, data=mtcars)
#+END_SRC
5. R 图形设备头部参数
Org Babel 提供了一流的头部参数，直接映射到 R 图形设备（png()、pdf()、svg() 等）的参数：
| 头部参数 | 默认值 | 描述与允许值 |
|---|---|---|
:width | 7 (英寸) / 480 (像素) | 设备宽度。 |
:height | 7 (英寸) / 480 (像素) | 设备高度。 |
:units | px (光栅), in (PDF) | 单位："px"、"in"、"cm"、"mm"。 |
:res | 72 | 标称分辨率，以每英寸像素数（DPI）为单位。（对于清晰的光栅图形至关重要：使用 150-300）。 |
:bg | "white" | 背景色（例如 "transparent"、"#f7f7f7"）。 |
:fg | "black" | 前景色。 |
:pointsize | 12 | 文本渲染的基础点大小。 |
:family | "Helvetica" | 字体系列（"Helvetica"、"Times"、"Palatino"、"Courier"、"sans"、"serif"、"mono"）。 |
:quality | 75 | JPEG 质量百分比（1-100）。 |
:type | 平台默认 | 位图渲染器："cairo"、"quartz" 或 "Xlib"。 |
:paper | "special" | PDF 纸张尺寸："special"、"a4"、"letter"、"a4r" 等。 |
:R-dev-args | nil | 直接传递给设备函数的额外 R 设备参数的原始字符串。 |
示例：高 DPI Cairo SVG/PNG 及自定义尺寸
#+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="Diamond Prices by Carat and Cut")
#+END_SRC
5.3 用于匹配文档字体的 TikZ LaTeX 图形
要生成轴标签和数学注释与文档共享完全相同 LaTeX 字体的图形：
#+BEGIN_SRC R :file figures/model_plot.tex :results graphics file
plot(1:10, type="b", main="\\textbf{TikZ Plot with Math: } $\\int_0^1 x^2 dx$")
#+END_SRC
当导出为 LaTeX/PDF 时，.tex 文件通过 \input{figures/model_plot.tex} 原生包含！
6. 高级格式化输出（ASCII、Org 和 LaTeX）
6.1 使用 ascii 包格式化 Org 输出
R 包 ascii 可以将复杂的非表格 R 对象（如 describe()、table() 或 summary()）转换为原生 Org 语法：
#+BEGIN_SRC R :session *r* :results output org
library(ascii)
options(asciiType = "org")
tab <- table(mtcars$cyl, mtcars$gear)
ascii(tab, caption="Cylinders vs Forward Gears")
#+END_SRC
#+RESULTS:
#+BEGIN_ORG
#+CAPTION: Cylinders vs Forward Gears
| | 3 | 4 | 5 |
|---+----+---+---|
| 4 | 1 | 8 | 2 |
| 6 | 2 | 4 | 1 |
| 8 | 12 | 0 | 2 |
#+END_ORG
6.2 使用 xtable 生成用于 LaTeX 导出的出版级表格
对于针对通过 LaTeX 导出为 PDF 的文档，请使用 xtable 和 :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="Regression Estimates", 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{Regression Estimates}
\label{tab:reg}
\end{table}
#+END_LaTeX
7. 故障排除与常见陷阱
| 问题 | 原因 | 解决方案 |
|---|---|---|
| ggplot2 或 lattice 生成空白/损坏的图像 | 在非会话模式下未显式打印返回的图形对象 | 将图形包裹在 print(p) 中，或切换到 :session，或将 output 添加到 :results output graphics file 中。 |
| 生成了图形文件但未插入链接 | 缺少 file 或 graphics 关键字 | 确保头部包含 :results graphics file（在 Org ≥ 9.3 中两个单词都需要）。 |
| “系统找不到指定的路径”（Windows） | R 可执行文件不在 PATH 中或位于自定义位置 | 在 init.el 中设置 (setq org-babel-R-command "path/to/R --slave --no-save")。 |
| R 数据框中的列被转换为第 0 行 | 表格列标题被视为观测数据 | 在块头部参数中添加 :colnames yes。 |
| 会话内 R 在大计算时挂起 | 块正在阻塞 Emacs 进程 | 切换到 inferior ESS 缓冲区（C-c C-z）以监控进度或使用 C-c C-c 中断。 |
| 导出文档中的图形模糊 | 默认光栅 DPI（72）太低 | 添加 :res 300 并相应调整 :width 和 :height。 |