ob-doc-R.org 16 KB

Org Mode support for R

Template Checklist [12/12] noexport


  • [X] Revise #+TITLE:
  • [X] Indicate #+AUTHOR:
  • [X] Add #+EMAIL:
  • [X] Revise banner source block [3/3]
  • [X] Add link to a useful language web site
  • [X] Replace "Language" with language name
  • [X] Find a suitable graphic and use it to link to the language
  • web site
  • [X] Write an Introduction
  • [X] Describe Requirements and Setup
  • [X] Replace "Language" with language name in Org Mode Features for Language Source Code Blocks
  • [X] Describe Header Arguments
  • [X] Describe support for Sessions
  • [X] Describe Result Types
  • [X] Describe Other differences from supported languages
  • [X] Provide brief Examples of Use
  • R is a free software environment for statistical computing and graphics. R source code blocks are fully supported in Org Mode with a wide variety of R-specific header arguments.

R source code blocks in Org Mode can be used to create R packages, carry out statistical analyses, create graphic displays, and produce reproducible research papers.

Requirements and Setup

R source code blocks in Org Mode require a working R installation. Precompiled binary distributions for Gnu/Linux, Mac OS X, and Windows are available at the Comprehensive R Archive Network, which also makes available the source code for compilation on other platforms.

Org Mode supports graphical output for LaTeX documents using the PGF and TikZ graphics system for TeX. In order to use this facility your R installation will need the tikzDevice package. One way to ensure that this device is loaded is to put the following lines in =.Rprofile=:

old <- getOption("defaultPackages")
options(defaultPackages = c(old, "tikzDevice"))

The Emacs mode, Emacs Speaks Statistics (ESS), is required for session-based evaluation. ESS is designed to support editing of scripts and interaction with various statistical analysis programs such as R, S-Plus, SAS, Stata, and JAGS.

The following two lines in =.emacs= point Emacs to ESS and load it. Note that you will likely need to adjust the load-path accordingly.

(add-to-list 'load-path "~/.emacs.d/src/ess-5.6/lisp") (require 'ess-site)

Finally, you'll need to ensure that =org-babel-load-languages= includes an entry for R. Typically, =org-babel-load-languages= will contain many entries. The example below omits other languages.

(org-babel-do-load-languages 'org-babel-load-languages '((R . t)))

Org Mode Features for R Source Code Blocks

Header Arguments

There are no R-specific default header arguments.

If a :file filename.ext header argument is provided to an R source block, then the output from the source block will go to the named file. What that output is depends on the value of the =:results= header argument.

If the value is :results graphics then "base" graphics output is captured on disk, and a link to the graphics file is inserted into the Org Mode buffer (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=, =.tex=, and =.svg=. If the extension of the file name passed to :file is not recognized, PNG format output is created by default.

For further clarification of :file and :results, see this thread.

There are many R-specific header arguments used to configure R graphics devices. They include:

the width of the graphics region in inches
the height of the graphics region in inches
for raster devices, the units in which width and height
are given -- =px=, =in=, =cm=, or =mm=
the background color defaults to "transparent"
the foreground color defaults to "black"
the default point size in the graphics defaults to 12
the quality of a JPEG image as a percentage
the type of compression to be used
the nominal resolution in pixels per inch
the bitmap type, one of "Xlib", "quartz", or "cairo"
the type of antialiasing to be used when type =
"cairo" or =type= = "quartz"
in normal use, one of "AvantGarde", "Bookman",
"Courier", "Helvetica" (default), "Helvetica-Narrow", "NewCenturySchoolbook", "Palatino", or "Times"
string to embed as the /Title field in the file defaults
to "R Graphics Output"
an R graphics font family name -- "sans", "serif", or "mono"
string describing the PDF version required to view the
output defaults to "1.4"
the target paper size -- "special" (default), "default",
"a4", "letter", "legal", "us", "executive", "a4r", or "USr", where the latter two are rotated to landscape orientation
the name of an encoding file
if paper != "special" then a logical that defaults
to true and determines whether the graphic device region is centered on the page
a character string describing the color model,
"srgb" (default), "gray", "grey", or "cmyk".
if TRUE (default) small circles will be rendered
with the Dingbats font
for the postscript device, a logical that defaults
to true and dtermines the orientation of the printed image
for graphics parameters not directly supported by
Org Mode (see below)

See the R help page for the graphics devices (e.g., using =?png=, =?pdf=, =?postscript= in an R session) for additional information on 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 Mode 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.

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


Sessions are fully supported by R source code blocks. They can be used as one way to preserve state accessed by several source code blocks. Sessions are also useful for debugging, since it is possible to view the values of variables created during the session.

Result Types

R source code blocks can return text or graphical results.

The ascii package coerces R objects to Org Mode, among other markup languages. The Hmisc, xtable and tables packages contain functions to write R objects into LaTeX representations.

R is capable of creating graphical displays in several formats. The outputs supported by R source code blocks in Org Mode include:

bitmap image file format commonly used on Microsoft
Windows and OS/2
jpg, jpeg
Joint Photographics Expert Group method of lossy
compression for digital photography widely used in a number of raster image file formats
output tikz graphics language which can be typeset by
LaTeX so the fonts for text in the plot match the fonts used in the LaTeX document
a sophisticated raster image format that allows multiple
pages in a document
Portable Network Graphics is a lossless raster image file format
Scalable Vector Graphics is an open standard vector format
that can be embedded in web pages and readily edited in open source software applications such as [[http://inkscape.org/][Inkscape]]
Portable Document Format can faithfully produce anything R
graphics can output
ps, postscript
PostScript is a predecessor of PDF that does
not support semitransparent colors or hyperlinking

When using R to produce graphical displays, you will typically set =:results graphics=. However, if you use the ggplot implementation of the grammar of graphics in R, then you will need to set :results output graphics.

Examples of Use


Use :session

Use ESS to step through evaluation line-by-line

    This section contains some tips on how to proceed if your R code is not doing what you had hoped. 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 C-c ' to visit the edit buffer for your code block
  • Use ess-eval-line-and-step to evaluate each line in turn

Org Mode Output from R

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). David Hajage's ascii R package creates appropriate plain text representations of many R objects. It 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 Mode for export.

In R:

> library(ascii) > options(asciiType = "org") > library(Hmisc) > ascii(describe(esoph))

  • 5 Variable
  • 88 Observations
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
n missing unique
88 0 4

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

n missing unique
88 0 4

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

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

The Org Mode source code block specifies :results org so the output is wrapped in #+BEGIN_ORG ... #+END_ORG. This way, arbitrary output can be included and easily replaced on subsequent evaluations of the source code block.

#+begin_src R :results output org
  ascii(summary(table(1:4, 1:4)))

- 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

The results in this case are exported as a nested list structure:

- 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

The caption, header, and include.colnames options are useful.

#+BEGIN_SRC R :results output org
 a <- runif(100)
 c <- "Quantiles of 100 random numbers"
 b <- ascii(quantile(a),header=T,include.colnames=T,caption=c)

#+CAPTION: Quantiles of 100 random numbers
| 0%   | 25%  | 50%  | 75%  | 100% |
| 0.03 | 0.28 | 0.52 | 0.74 | 1.00 |

The output exported to HTML can be quite nice.

#+CAPTION: Quantiles of 100 random numbers
|   0% |  25% |  50% |  75% | 100% |
| 0.03 | 0.28 | 0.52 | 0.74 | 1.00 |

Graphics Produced by ggplot2

When the ggplot2 package is used graphics output requires :results output graphics. The following example writes the graphics output to the file specified in the :file header argument.

,#+name: r-edge-angle-histogram ,#+begin_src R :results output graphics :var x=whole-adzes :file r/adze_edge_angle.png :width 400 :height 300 library(ggplot2) adze.edge.angle <- ggplot(x, aes(edge_angle)) adze.edge.angle + geom_histogram(aes(y=..density..)) geom_density(weight=2) xlab("Measured cutting edge angle (degrees)") ,#+end_src

,#+results: r/adze_edge_angle.png

LaTeX code from R

This example summarises a linear regression fit. Usually the Org Mode user should not have to be involved in LaTeX code generation, because this is the responsibility of Org Mode's LaTeX export engine. In this example, neither the printed representation, nor the value of =summary(lm(y ~ x))= is tabular, and it would therefore require some work to get the information in to an Org Mode table. However, the =xtable= package can be used to output a LaTeX table. Using :results latex as a header argument to the R source code block ensures that this is returned as a LaTeX block in the Org Mode buffer and thus can be included correctly in LaTex-based export targets.

#+begin_src R :results output latex
x <- rnorm(100)
y <- x + rnorm(100)
xtable(summary(lm(y ~ x)))
% latex table generated in R 2.9.2 by xtable 1.5-5 package
% Wed Dec  9 17:17:53 2009
 & Estimate & Std. Error & t value & Pr($>$$|$t$|$) \\ 
(Intercept) & -0.0743 & 0.0969 & -0.77 & 0.4454 \\ 
  x & 1.0707 & 0.0923 & 11.60 & 0.0000 \\ 


When in an Org Mode R code edit buffer with an associated R session, M-x 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.