Org-babel-R

Org-babel support for R

Requirements
- Emacs Speaks Statistics
Language-specific Features
- Graphical output
Additions to Org-babel
- Header Arguments
Tips for usage

Requirements Update

Emacs Speaks Statistics

Required for session-based evaluation.

Language-specific Features Write

Graphical output Fix

If a :file filename.ext header arg is provided to an R block, then graphical output from the source block is captured on disk, and the output of the source block is a link to the resulting file (as is also the case with the graphics-only languages such as gnuplot, ditaa, dot, and asymptote.)

An attempt is made to find an R graphics device corresponding to the file extension. Currently, the following extensions are recognized: .png, .jpg, .jpeg, .tiff, .bmp, .pdf, .ps, .postscript, and .svg. If the extension of the file name passed to :file is not recognized, png format output is created by default.

Additionally, values for several arguments to the R graphics device can be passed using header args:

:width :height :bg :fg :units :pointsize :antialias :quality :compression :res :type :family
:title :fonts :version :paper :encoding :pagecentre :colormodel :useDingbats :horizontal

See the R help page for the graphics devices (e.g. using ?png, ?pdf) for explanations of these arguments.

Arguments to the R graphics device can also be passed as a string in R argument syntax, using the header arg :R-dev-args. This is useful for graphics device arguments that don't have an Org-babel header argument counterpart.

The following example source block illustrates use of :R-dev-args to pass background and foreground colors. Note that both of these arguments can also be passed directly as header args, using :fg and :bg.

#+begin_src R :file z.pdf :width 8 :height 8 :R-dev-args bg="olivedrab", fg="hotpink"
  plot(matrix(rnorm(100), ncol=2), type="l")
#+end_src

Additions to Org-babel Write

Header Arguments

R support introduces a large number of header arguments to Org-babel. Most of these set parameters of R graphic devices, as described above.

It is also possible to include column names during export of data frames.


Header arg	Meaning
:colnames yes	Include column names in output

Tips for usage

Debugging

This section contains some tips on how to proceed if your R code is not doing what you had hoped.

Use `:session`

Evaluate your code using the :session header argument, then visit the R buffer (i.e. the buffer containing the "inferior ESS" process). Then you can inspect the objects that have been created, and try out some lines of code. Useful R functions for inspecting objects include (as always in R, type a "?" followed by the name of the function to get help with the function)

str
dim
summary

Use ESS to step through evaluation line-by-line

Use C-c ' to visit the edit buffer for your code block
Use ess-eval-line-and-step to evaluate each line in turn

In addition to ess-eval-line-and-step, there are several other ESS functions with names beginning ess-eval-*. They evaluate lines and regions in different ways; it's worth looking at their descriptions (C-h f).

LaTeX code from R

This example summarises a linear regression fit. Usually the org-babel user should not have to be involved in latex code generation, as this is the responsibility of org-mode's latex export engine. But in this example, neither the printed representation nor the value of summary(lm(y ~ x)) is at all tabular, and it would therefore require some work to get the information in to an org table. However, the xtable package can be used to output a latex table. Using ':results latex' in org-babel ensures that this is stored as a latex block in the org buffer and thus can be included correctly in latex-based export targets.

library(xtable)
x <- rnorm(100)
y <- x + rnorm(100)
xtable(summary(lm(y ~ x)))

Org output from R

David Hajage's ascii R package creates appropriate plain text representations of many R objects, and features an option to specify that the plain text representations should be in Org format. This can be particularly useful for retrieving non-tabular R data structures in Org.

In R:

> library(ascii)
> options(asciiType = "org")
> library(Hmisc)
> ascii(describe(esoph))
#+CAPTION: esoph
- 5 Variable
- 88 Observations

*agegp*
|  n | missing | unique |
| 88 |       0 |      6 |

|           | 25-34 | 35-44 | 45-54 | 55-64 | 65-74 | 75+ |
| Frequency |    15 |    15 |    16 |    16 |    15 |  11 |
| %         |    17 |    17 |    18 |    18 |    17 |  12 |

*alcgp*
|  n | missing | unique |
| 88 |       0 |      4 |

 0-39g/day (23, 26%), 40-79 (23, 26%), 80-119 (21, 24%), 120+ (21, 24%)

*tobgp*
|  n | missing | unique |
| 88 |       0 |      4 |

 0-9g/day (24, 27%), 10-19 (24, 27%), 20-29 (20, 23%), 30+ (20, 23%)

*ncases*
|  n | missing | unique |  Mean | .05 | .10 | .25 | .50 | .75 | .90 | .95 |
| 88 |       0 |     10 | 2.273 | 0.0 | 0.0 | 0.0 | 1.0 | 4.0 | 5.3 | 6.0 |

|           |  0 |  1 |  2 |  3 | 4 | 5 | 6 | 8 | 9 | 17 |
| Frequency | 29 | 16 | 11 |  9 | 8 | 6 | 5 | 1 | 2 |  1 |
| %         | 33 | 18 | 12 | 10 | 9 | 7 | 6 | 1 | 2 |  1 |

*ncontrols*
|  n | missing | unique |  Mean | .05 | .10 | .25 | .50 |  .75 |  .90 |  .95 |
| 88 |       0 |     30 | 11.08 | 1.0 | 1.0 | 3.0 | 6.0 | 14.0 | 29.1 | 40.0 |

 lowest:  1  2  3  4  5, highest: 40 46 48 49 60

From Org-babel:

library(ascii)
options(asciiType="org")
ascii(summary(table(1:4, 1:4)))

Loading required package: proto

Number of cases in table: 4
Number of factors: 2
Test for independence of all factors:
- Chisq = 12, df = 9, p-value = 0.2133
- Chi-squared approximation may be incorrect

ess-switch-to-end-of-ESS

When in an org mode R code edit buffer with an associated R session, ess-switch-to-end-of-ESS will bring the R session buffer into view and place point at the prompt. ESS binds this to C-c C-z and C-M-r by default.