How to Use Emacs Org-Babel Mode to Write Literate Programming Document in R Language

1 Introduction
2 How to Use

1 Introduction

We introduce the use of emacs org-babel model in this document. Emacs Org-Babel mode is a literate programming tool (aka. active document), which can embed multiple programming languages, inlcuding R, in one document. Another popular literate programming tool for statisticians is the Sweave document, which can embed only R code.

First we clarify the following terminologies:

Emacs: The extensible, customizable, self-documenting real-time display editor.
Org-mode: An Emacs Mode for keeping notes, maintaining ToDo lists, doing project planning, and authoring with a fast and effective plain-text system.
Babel: It is Org-mode's ability to execute source code within Org-mode documents.

2 How to Use

2.1 Installation

(August 5, 2011) Babel is available after Org-mode version 7.0, while Emacs version 23.2.1 still only has Org-mode version 6.33x. Thus you need to update Org-mode (currenly at version 7.7) from Org Home Page. You can use Emacs Package Manager to install Org-mode easily following this instruction.

2.2 Keyboard Shortcuts

To write a code block in a .org file, you can simple type <s followed by TAB key. Then a skeleton like the following is automatically inserted:

#+begin_src 

#+end_src

All you need to do next is type a single letter R in the header and begin typing R code:

#+begin_src R
  ## Edit Your R Code Here.
  x <- rnorm(100)
  summary(x)
#+end_src

I recommend you to edit R code in ESS (Emacs Speaks Statistics) mode by typing "C-c '" (i.e. C-c and single quote) within the code block, which brings up a separate window with ESS enabled. After editing, you can type "C-c '" again to return to the main file buffer.

Once you finish writing the code, you can execute them immediately by pressing C-c C-c and see the R output being inserted into the document. Alternatively, you can press C-c C-o to see the R output in a separate window.

To generate (export to) HTML document, press C-c C-e b. Note other document options are available upon pressing C-c C-e.

2.3 Emacs Customization Settings

The Org-Babel mode can be customized through the emacs menu item "Org", which can be saved to your ".emacs" file for future use. Some useful Org-Babel settings for statisticians are:

(custom-set-variables
 '(org-babel-load-languages (quote ((emacs-lisp . t) (R . t))))
 '(org-confirm-babel-evaluate nil))

which specifies R language to be loaded and R code to be evaluated without prompt.

I also specify a "skeleton" in my ".emacs" file so as to start writing Org file quickly:

(define-skeleton org-skeleton
  "Header info for a emacs-org file."
  "Title: "
  "#+TITLE:" str " \n"
  "#+AUTHOR: Your Name\n"
  "#+email: address@hidden"
  "#+INFOJS_OPT: \n"
  "#+BABEL: :session *R* :cache yes :results output graphics :exports both :tangle yes \n"
  "-----"
 )
(global-set-key [C-S-f4] 'org-skeleton)

where

The #+INFOJS_OPT option will generat a HTML document that is foldable and follows the style of GNU/INFO document.
The :session *R* option makes sure all the R code is run in the same session so objects generated in one code block can be accessed from other code blocks.
the :cache yes option is used to avoid re-evaluating unchanged code blocks. This can save significant time when you revise a document with a lot of R code frequently.
The :results output graphics :exports both option will put both the R code and its text and graphics output in the generated document.
The :tangle yes option allows the document to be "tangled" to generate pure code file. The short-cut key for tangling is C-c C-v t, which generates a .R file with all the R code extracted.
Note the "–—" string will generate a horizontal line in HTML file.
Finally, a hotkey C-S-f4 (while pressing Ctrl and Shift keys, press F4 key) is assigned to invoke this skeleton quickly.

2.4 A Complete Example

We use the following file test.org as an example file.

#+TITLE:Test 
#+AUTHOR: Your Name
#+EMAIL: address@hidden
#+BABEL: :session *R* :cache yes :results output graphics :exports both :tangle yes 

* Example of Org-Babel for R Literate Programming
** R text output
A simple summary. 
#+begin_src R 
  x <- rnorm(10)
  summary(x)
#+end_src

** R graphics output
Note we use the object =x= generated in previous code block, thanks to
the header option =:session *R*=.  The output graphics file is
=a.png=. 

#+begin_src R  :file a.png
  y <- rnorm(10)
  plot(x, y)
#+end_src

Same plot with larger dimension:

#+begin_src R  :file b.png :width 800 :height 800
  plot(x, y)
#+end_src

The exported HTML file is shown as test.html.

2.5 Caveats

Keep the code block indented correctly. Otherwise the graph will not be embedded in the HTML export file.
Always have the contents and plots under a section heading to avoid certain exporting errors.
It makes things easier if the working directory in R session buffer is the same as the directory of the .org file that you are writing. In this way, the plot files can easily be found.
The macro option (#+MACRO:) cannot be used to save the typing of header options for code blocks. For example, it does NOT work if you try to use
```
#+MACRO: p  :file $1.png :width 1000 :height 800
```
to shorten the header to
```
#+begin_src R {{{p(plot)}}}
```

From:	Feiming Chen
Subject:	[O] Org-Babel Mode : a suggestion and a contribution article [Babel]
Date:	Tue, 9 Aug 2011 14:17:56 -0700 (PDT)

[O] Org-Babel Mode : a suggestion and a contribution article [Babel]

Test

Table of Contents

1 Example of Org-Babel for R Literate Programming

1.1 R text output

1.2 R graphics output