pwquint24/org-babel-r

Bloques de Código R en Org Babel

El uso de R con Org Babel proporciona un entorno para computación estadística, análisis de datos, generación de gráficos e investigación reproducible. Los bloques de código R en Org Mode se integran con ESS (Emacs Speaks Statistics) para admitir ejecución interactiva, estado compartido entre bloques, gráficos de calidad de publicación y exportación estructurada de tablas.

---

1. Configuración del Entorno

1.1 Prerrequisitos

1. Una instalación funcional de R (binario CRAN o compilado desde fuente).
2. ESS (Emacs Speaks Statistics) instalado vía MELPA (requerido para evaluación basada en sesiones y ejecución paso a paso).
3. ob-R habilitado en org-babel-load-languages.

1.2 Plantilla de Configuración de Emacs

Añade lo siguiente a tu init.el:

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

;; 2. Asegurar que ESS esté cargado
(unless (package-installed-p 'ess)
  (package-refresh-contents)
  (package-install 'ess))
(require 'ess-r-mode)

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

;; 4. Opcional: Ejecutar bloques sin confirmación de seguridad interactiva
(setq org-confirm-babel-evaluate nil)

1.3 Configuración Específica para Windows

En Microsoft Windows, si Emacs reporta The system cannot find the path specified, establece explícitamente la ruta del binario de R (incluyendo las banderas predeterminadas de Babel --slave --no-save):

;; Para Windows de 64 bits:
(setq org-babel-R-command "C:/Progra~1/R/R-4.3.0/bin/x64/R --slave --no-save")

Nota: Cuando se usa :session, se ignora org-babel-R-command y se utiliza inferior-ess-R-program de ESS.

---

2. Modos de Ejecución: Sesiones e Integración con ESS

2.1 Sin Sesión (:session none, predeterminado)

Se ejecuta en un proceso R por lotes separado (R --slave --no-save). Limpio, aislado y sin efectos secundarios, pero recarga todas las librerías y datos cada vez.

2.2 Sesiones Interactivas (:session <nombre>)

Se ejecuta dentro de un proceso R inferior de ESS (*<nombre>*).

• Los conjuntos de datos, librerías, modelos y variables persisten a través de múltiples bloques que comparten el mismo nombre de sesión.
• Permite inspección interactiva, depuración y flujos de trabajo iterativos rápidos.

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

2.3 Depuración Interactiva y Paso a Paso con ESS

Al depurar bloques R:

1. Cambiar a la Sesión: Con el cursor en un bloque R, presiona M-<down> (org-babel-pop-to-session) o C-c C-z (ess-switch-to-end-of-ESS) para saltar al búfer REPL de R.
2. Inspeccionar el Entorno: Usa ls(), str(x), dim(x), summary(x) o head(x).
3. Ejecución Línea por Línea:
   • Presiona C-c ' (org-edit-special) dentro del bloque Org para entrar en el búfer ESS R dedicado.
   • Usa C-c C-n (ess-eval-line-and-step) o C-c C-c (ess-eval-region-or-function-or-paragraph) para ejecutar el código línea por línea en el proceso R activo.
   • Presiona C-c ' para regresar al documento Org.

---

3. Manejo de Resultados: Data Frames, Valores y Tablas

3.1 Devolver Datos Tabulares (:results value table)

Al devolver data frames, matrices o vectores, Org Babel los convierte directamente en tablas Org nativas:

#+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  |

• Siempre añade :colnames yes cuando trabajes con data frames para preservar y mostrar correctamente los nombres de las columnas.
• En R, el valor de la última expresión evaluada se devuelve automáticamente (no se requiere return() explícito).

3.2 Capturar Salida de Consola (:results output)

Usa :results output para capturar stdout, resúmenes de modelos o estadísticas:

#+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. Gráficos y Visualizaciones

4.1 Regla Base para Gráficos (Org $\ge$ 9.3)

Para generar gráficos, especifica tanto file como graphics en :results, además del nombre de archivo en :file:

:results graphics file :file <ruta.ext>

Extensiones de archivo soportadas y dispositivos R correspondientes:

• Vectoriales: .pdf, .svg, .ps / .postscript, .tex (TikZ)
• Raster: .png, .jpg / .jpeg, .tiff, .bmp
• Predeterminado: .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="Peso (1000 lbs)", ylab="Millas por Galón",
       main="Economía de Combustible")
  abline(lm(mpg ~ wt, data=mtcars), col="red", lwd=2)
#+END_SRC

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

4.2 La Regla Crítica de ggplot2 / Lattice (Gráficos de Cuadrícula)

Trampa: Las funciones de Lattice (xyplot) y ggplot2 devuelven objetos gráficos objetos. En la evaluación por lotes no interactiva (sin sesión), devolver el objeto sin imprimirlo crea un archivo gráfico vacío o corrupto.

Existen tres formas fiables de renderizar gráficos de ggplot2 / Lattice en Org Babel:

Método A: print() Explícito (Recomendado para sin sesión)

#+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() explícito activa el renderizado del dispositivo gráfico
#+END_SRC

Método B: Usar :session (Se imprime automáticamente de forma interactiva)

#+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

Método C: Usar :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. Argumentos de Cabecera para Dispositivos Gráficos R

Org Babel proporciona argumentos de cabecera de primera clase que se asignan directamente a parámetros de los dispositivos gráficos R (png(), pdf(), svg(), etc.):

Argumento de Cabecera	Predeterminado	Descripción y Valores Permitidos
:width	7 (in) / 480 (px)	Ancho del dispositivo.
:height	7 (in) / 480 (px)	Alto del dispositivo.
:units	px (raster), in (PDF)	Unidades: "px", "in", "cm", "mm".
:res	72	Resolución nominal en píxeles por pulgada (DPI). (Esencial para gráficos raster nítidos: usar 150-300).
:bg	"white"	Color de fondo (ej. "transparent", "#f7f7f7").
:fg	"black"	Color de primer plano.
:pointsize	12	Tamaño base de punto para renderizado de texto.
:family	"Helvetica"	Familia de fuente ("Helvetica", "Times", "Palatino", "Courier", "sans", "serif", "mono").
:quality	75	Porcentaje de calidad JPEG (1-100).
:type	Predeterminado de la plataforma	Renderizador de mapa de bits: "cairo", "quartz" o "Xlib".
:paper	"special"	Tamaño de papel PDF: "special", "a4", "letter", "a4r", etc.
:R-dev-args	nil	Cadena sin procesar de argumentos adicionales del dispositivo R que se pasan directamente a la función del dispositivo.

Ejemplo: SVG/PNG Cairo de Alto DPI con Dimensiones Personalizadas

#+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="Precios de Diamantes por Quilate y Corte")
#+END_SRC

5.3 Gráficos TikZ LaTeX para Fuentes de Documento Coincidentes

Para generar gráficos donde las etiquetas de los ejes y las anotaciones matemáticas compartan la misma fuente LaTeX que tu documento:

#+BEGIN_SRC R :file figures/model_plot.tex :results graphics file
  plot(1:10, type="b", main="\\textbf{Gráfico TikZ con Matemáticas: } $\\int_0^1 x^2 dx$")
#+END_SRC

Cuando se exporta a LaTeX/PDF, el archivo .tex se incluye de forma nativa mediante \input{figures/model_plot.tex}.

---

6. Salidas Formateadas Avanzadas (ASCII, Org y LaTeX)

6.1 Salida Org Formateada con el Paquete ascii

El paquete R ascii puede convertir objetos R complejos no tabulares (como describe(), table() o summary()) en sintaxis Org nativa:

#+BEGIN_SRC R :session *r* :results output org
  library(ascii)
  options(asciiType = "org")
  tab <- table(mtcars$cyl, mtcars$gear)
  ascii(tab, caption="Cilindros vs Marchas Adelante")
#+END_SRC

#+RESULTS:
#+BEGIN_ORG
#+CAPTION: Cilindros vs Marchas Adelante
|   | 3  | 4 | 5 |
|---+----+---+---|
| 4 | 1  | 8 | 2 |
| 6 | 2  | 4 | 1 |
| 8 | 12 | 0 | 2 |
#+END_ORG

6.2 Tablas de Publicación con xtable para Exportación a LaTeX

Para documentos destinados a PDF mediante exportación a LaTeX, usa xtable con :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="Estimaciones de Regresión", 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{Estimaciones de Regresión} 
\label{tab:reg}
\end{table}
#+END_LaTeX

---

7. Solución de Problemas y Errores Comunes

Problema	Causa	Solución
ggplot2 o lattice produce imagen en blanco o corrupta	El objeto gráfico devuelto no se imprimió explícitamente en modo sin sesión	Envuelve el gráfico en print(p), cambia a :session o añade output a :results output graphics file.
Archivo gráfico generado pero sin enlace insertado	Falta la palabra clave file o graphics	Asegúrate de que la cabecera tenga :results graphics file (ambas palabras requeridas en Org $\ge$ 9.3).
The system cannot find the path specified (Windows)	El ejecutable de R no se encuentra en PATH o en una ubicación personalizada	Establece (setq org-babel-R-command "ruta/a/R --slave --no-save") en init.el.
Columnas convertidas en fila 0 en data frames R	Los encabezados de columna de la tabla se tratan como datos de observación	Añade :colnames yes a los argumentos de cabecera del bloque.
R en sesión se cuelga en cálculos grandes	El bloque bloquea el proceso de Emacs	Cambia al búfer inferior de ESS (C-c C-z) para monitorear el progreso o interrumpir con C-c C-c.
Gráficos borrosos en documentos exportados	El DPI raster predeterminado (72) es demasiado bajo	Añade :res 300 y ajusta :width y :height en consecuencia.