pwquint24/org-babel-r

Blocos de Código Fonte R no Org Babel

Usar R com Org Babel fornece um ambiente para computação estatística, análise de dados, geração de gráficos e pesquisa reproduzível. Blocos de código R no Org Modo integram-se com ESS (Emacs Speaks Statistics) para suportar execução interativa, compartilhamento de estado entre blocos, gráficos de qualidade para publicação e exportação estruturada de tabelas.

---

1. Configuração e Ambiente de Desenvolvimento

1.1 Pré-requisitos

1. Uma instalação funcional do R (binário CRAN ou compilado a partir do código-fonte).
2. ESS (Emacs Speaks Statistics) instalado via MELPA (necessário para avaliação baseada em sessão e depuração passo a passo).
3. ob-R habilitado em org-babel-load-languages.

1.2 Modelo de Configuração do Emacs

Adicione o seguinte ao seu init.el:

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

;; 2. Certifique-se de que o ESS está carregado
(unless (package-installed-p 'ess)
  (package-refresh-contents)
  (package-install 'ess))
(require 'ess-r-mode)

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

;; 4. Opcional: Executar blocos sem confirmação de segurança interativa
(setq org-confirm-babel-evaluate nil)

1.3 Configuração Específica para Windows

No Microsoft Windows, se o Emacs reportar The system cannot find the path specified, defina explicitamente o caminho do binário R (incluindo as flags padrão do Babel --slave --no-save):

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

Nota: Ao usar :session, org-babel-R-command é ignorado e o inferior-ess-R-program do ESS é usado no lugar.

---

2. Modos de Execução: Sessões e Integração ESS

2.1 Sem Sessão (:session none, padrão)

Executa em um processo R batch separado (R --slave --no-save). Limpo, isolado e sem efeitos colaterais, mas recarrega todas as bibliotecas e dados a cada execução.

2.2 Sessões Interativas (:session <nome>)

Executa dentro de um processo R inferior do ESS (*<nome>*).

• Conjuntos de dados, bibliotecas, modelos e variáveis persistem entre múltiplos blocos que compartilham o mesmo nome de sessão.
• Permite inspeção interativa, depuração e fluxos de trabalho iterativos rápidos.

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

2.3 Depuração Interativa e Passo a Passo com ESS

Ao depurar blocos R:

1. Mude para a Sessão: Com o ponto em um bloco R, pressione M-<down> (org-babel-pop-to-session) ou C-c C-z (ess-switch-to-end-of-ESS) para pular para o buffer REPL do R.
2. Inspecione o Ambiente: Use ls(), str(x), dim(x), summary(x) ou head(x).
3. Execução Passo a Passo:
   • Pressione C-c ' (org-edit-special) dentro do bloco Org para entrar no buffer ESS R dedicado.
   • Use C-c C-n (ess-eval-line-and-step) ou C-c C-c (ess-eval-region-or-function-or-paragraph) para percorrer o código linha por linha no processo R ativo.
   • Pressione C-c ' para retornar ao documento Org.

---

3. Tratamento de Resultados: Data Frames, Valores e Tabelas

3.1 Retornando Dados Tabulares (:results value table)

Ao retornar data frames, matrizes ou vetores, o Org Babel os converte diretamente em tabelas 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  |

• Sempre adicione :colnames yes ao trabalhar com data frames para preservar e exibir corretamente os nomes das colunas.
• Em R, o valor da última expressão avaliada é retornado automaticamente (nenhum return() explícito é necessário).

3.2 Capturando Saída de Console Impressa (:results output)

Use :results output para capturar stdout, impressões de modelo ou estatísticas de resumo:

#+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 e Visualizações

4.1 Regra Base para Gráficos (Org >= 9.3)

Para produzir gráficos, especifique ambos file e graphics em :results, além do nome do arquivo de saída em :file:

:results graphics file :file <caminho.ext>

Extensões de arquivo suportadas e dispositivos R correspondentes:

• Vetoriais: .pdf, .svg, .ps / .postscript, .tex (TikZ)
• Raster (bitmap): .png, .jpg / .jpeg, .tiff, .bmp
• Padrão alternativo: .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 A Regra Crítica para ggplot2 / Lattice ("Grid Graphics")

Armadilha: Funções Lattice (xyplot) e ggplot2 retornam objetos gráficos. Na avaliação batch não interativa (não-sessão), retornar o objeto sem imprimi-lo cria um arquivo gráfico vazio/corrompido!

Existem três maneiras confiáveis de renderizar gráficos ggplot2 / Lattice no Org Babel:

Método A: print() Explícito (Recomendado para não-sessão)

#+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 aciona a renderização do dispositivo gráfico
#+END_SRC

Método B: Use :session (Auto-impressão interativa)

#+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: Use :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 Cabeçalho do Dispositivo Gráfico R

O Org Babel fornece argumentos de cabeçalho de primeira classe que mapeiam diretamente para parâmetros de dispositivos gráficos R (png(), pdf(), svg(), etc.):

Argumento de Cabeçalho	Padrão	Descrição e Valores Permitidos
:width	7 (pol) / 480 (px)	Largura do dispositivo.
:height	7 (pol) / 480 (px)	Altura do dispositivo.
:units	px (raster), in (PDF)	Unidades: "px", "in", "cm", "mm".
:res	72	Resolução nominal em pixels por polegada (DPI). (Essencial para gráficos raster nítidos: use 150-300).
:bg	"white"	Cor de fundo (ex.: "transparent", "#f7f7f7").
:fg	"black"	Cor do primeiro plano (texto).
:pointsize	12	Tamanho base do ponto para renderização de texto.
:family	"Helvetica"	Família da fonte ("Helvetica", "Times", "Palatino", "Courier", "sans", "serif", "mono").
:quality	75	Percentual de qualidade JPEG (1-100).
:type	Padrão da plataforma	Renderizador de bitmap: "cairo", "quartz" ou "Xlib".
:paper	"special"	Tamanho do papel PDF: "special", "a4", "letter", "a4r", etc.
:R-dev-args	nil	String bruta de argumentos adicionais do dispositivo R passados diretamente para a função do dispositivo.

Exemplo: Cairo SVG/PNG de Alta Resolução com Dimensões 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="Diamond Prices by Carat and Cut")
#+END_SRC

5.3 Gráficos TikZ LaTeX para Corresponder às Fontes do Documento

Para gerar gráficos onde rótulos de eixos e anotações matemáticas compartilham a mesma fonte LaTeX exata do seu documento:

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

Ao exportar para LaTeX/PDF, o arquivo .tex é incluído nativamente via \input{figures/model_plot.tex}!

---

6. Saídas Avançadas Formatadas (ASCII, Org e LaTeX)

6.1 Saída Org Formatada com o Pacote ascii

O pacote R ascii pode converter objetos R complexos não-tabulares (como describe(), table() ou summary()) em sintaxe 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 Avante")
#+END_SRC

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

6.2 Tabelas para Publicação com xtable para Exportação LaTeX

Para documentos destinados a PDF via exportação LaTeX, use xtable com :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="Estimativas de Regressão", 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{Estimativas de Regressão} 
\label{tab:reg}
\end{table}
#+END_LaTeX

---

7. Solução de Problemas e Armadilhas Comuns

Problema	Causa	Solução
ggplot2 ou lattice produz imagem em branco/corrompida	Objeto gráfico retornado não foi explicitamente impresso no modo não-sessão	Envolva o gráfico em print(p), ou mude para :session, ou adicione output a :results output graphics file.
Arquivo gráfico produzido, mas nenhum link inserido	Faltando a palavra-chave file ou graphics	Certifique-se de que o cabeçalho tenha :results graphics file (ambas as palavras são necessárias no Org >= 9.3).
The system cannot find the path specified (Windows)	Executável R não encontrado no PATH ou local personalizado	Defina (setq org-babel-R-command "caminho/para/R --slave --no-save") em init.el.
Colunas convertidas para a linha 0 em data frames R	Cabeçalhos de coluna da tabela tratados como dados de observação	Adicione :colnames yes aos argumentos de cabeçalho do bloco.
R em sessão trava em computação pesada	Bloco está bloqueando o processo do Emacs	Mude para o buffer ESS inferior (C-c C-z) para monitorar o progresso ou interrompa com C-c C-c.
Gráficos borrados em documentos exportados	DPI raster padrão (72) é muito baixo	Adicione :res 300 e ajuste :width e :height adequadamente.