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

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

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 h h. Note other document options are available upon pressing C-c C-e.

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: your-email@server.com\n"
  "#+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.

We use the following file test-for-how-to-use-Org-Babel-for-R.org as an example file.

#+TITLE: Test
#+AUTHOR: Your Name
#+EMAIL: your-email@server.com
#+PROPERTY: session *R* 
#+PROPERTY: cache yes 
#+PROPERTY: results graphics 
#+PROPERTY: exports both 
#+PROPERTY: tangle yes 

# This file is released by its authors and contributors under the GNU
# Free Documentation license v1.3 or later, code examples are released
# under the GNU General Public License v3 or later.

* 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

• 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)}}}