emacs-orgmode
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


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)

I wonder if it is possible to use the macro option (#+MACRO:) to save the typing of header options (of code blocks).  For example, currently it does NOT work if I try to use
#+MACRO: p  :file $1.png :width 1000 :height 800

to shorten the header of a code block to

#+begin_src R {{{p(plot)}}}
Anyway,  I found Org-Babel Mode to be a great tool since Sweave for writing R literate program document.   I wrote a how-to article on its use (see attached file "how-to-use-*.html", other files are raw and support files).  Hopefully it can be useful to some users. 

Sincerely,
Feiming Chen

Attachment: test.org
Description: Lotus Organizer

Test

Table of Contents

1 Example of Org-Babel for R Literate Programming

1.1 R text output

A simple summary.

x <- rnorm(10)
summary(x)
   Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
 -2.120  -0.229   0.478   0.113   0.822   0.947

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

y <- rnorm(10)
plot(x, y)

a.png

Same plot with larger dimension:

plot(x, y)

b.png

Date: 2011-08-09 17:08:05 EDT

Author: Your Name

Org version 7.7 with Emacs version 23

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

Table of Contents

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

Date: 2011-08-09 17:16:42 EDT

Author: Feiming Chen

Org version 7.7 with Emacs version 23

Attachment: how-to-use-Org-Babel-for-R.org
Description: Lotus Organizer


reply via email to

[Prev in Thread] Current Thread [Next in Thread]