org-contrib/babel/how-to-use-Org-Babel-for-R.org

   1 #+TITLE:How to Use Emacs Org-Babel Mode to Write Literate Programming Document in R Language
   2 #+AUTHOR: Feiming Chen
   3 #+EMAIL: fullname at yahoo
   4 #+BABEL: :session *R* :cache yes :results output graphics :exports both :tangle yes
   5
   6 * Introduction
   7
   8 We introduce the use of emacs org-babel model in this document.  Emacs
   9 Org-Babel mode is a literate programming tool (aka. active document), which
  10 can embed multiple programming languages, inlcuding R, in one document.
  11 Another popular literate programming tool for statisticians is the Sweave
  12 document, which can embed only R code.
  13
  14 First we clarify the following terminologies:
  15
  16 - [[http://www.gnu.org/software/emacs/][Emacs]] :: The extensible, customizable, self-documenting real-time
  17            display editor.
  18
  19 - [[http://www.gnu.org/software/emacs/][Org-mode]] :: An Emacs Mode for keeping notes, maintaining ToDo lists,
  20               doing project planning, and authoring with a fast and
  21               effective plain-text system.
  22
  23 - [[http://orgmode.org/worg/org-contrib/babel/][Babel]] :: It is Org-mode's ability to execute source code within
  24            Org-mode documents.
  25
  26 * How to Use
  27
  28 ** Installation
  29
  30 (August 5, 2011) =Babel= is available after Org-mode version 7.0, while
  31 Emacs version 23.2.1 still only has Org-mode version 6.33x.  Thus you need
  32 to update Org-mode (currenly at version 7.7) from [[http://orgmode.org][Org Home Page]].  You can
  33 use Emacs Package Manager to install Org-mode easily following [[http://orgmode.org/worg/org-faq.html#installing-via-elpa][this
  34 instruction. ]]
  35
  36 ** Keyboard Shortcuts
  37
  38 To write a code block in a =.org= file, you can simple type =<s=
  39 followed by TAB key.  Then a skeleton like the following is
  40 automatically inserted:
  41
  42 #+begin_example
  43 #+begin_src
  44
  45 #+end_src
  46 #+end_example
  47
  48 All you need to do next is type a single letter =R= in the header and
  49 begin typing R code:
  50
  51 #+begin_example
  52 #+begin_src R
  53   ## Edit Your R Code Here.
  54   x <- rnorm(100)
  55   summary(x)
  56 #+end_src
  57 #+end_example
  58
  59 I recommend you to edit R code in [[http://ess.r-project.org/][ESS]] (Emacs Speaks Statistics) mode by
  60 typing "C-c '" (i.e. C-c and single quote) within the code block, which
  61 brings up a separate window with ESS enabled. After editing, you can type
  62 "C-c '" again to return to the main file buffer.
  63
  64 Once you finish writing the code, you can execute them immediately by
  65 pressing =C-c C-c= and see the R output being inserted into the document.
  66 Alternatively, you can press =C-c C-o= to see the R output in a separate
  67 window.
  68
  69 To generate (export to) HTML document, press =C-c C-e b=.  Note other
  70 document options are available upon pressing =C-c C-e=.
  71
  72 ** Emacs Customization Settings
  73
  74 The Org-Babel mode can be customized through the emacs menu item "Org",
  75 which can be saved to your ".emacs" file for future use. Some useful
  76 Org-Babel settings for statisticians are:
  77
  78 #+begin_example
  79 (custom-set-variables
  80  '(org-babel-load-languages (quote ((emacs-lisp . t) (R . t))))
  81  '(org-confirm-babel-evaluate nil))
  82 #+end_example
  83
  84 which specifies =R= language to be loaded and R code to be evaluated
  85 without prompt.
  86
  87 I also specify a "skeleton" in my ".emacs" file so as to start writing
  88 Org file quickly:
  89
  90 #+begin_example
  91 (define-skeleton org-skeleton
  92   "Header info for a emacs-org file."
  93   "Title: "
  94   "#+TITLE:" str " \n"
  95   "#+AUTHOR: Your Name\n"
  96   "#+email: your-email@server.com\n"
  97   "#+INFOJS_OPT: \n"
  98   "#+BABEL: :session *R* :cache yes :results output graphics :exports both :tangle yes \n"
  99   "-----"
 100  )
 101 (global-set-key [C-S-f4] 'org-skeleton)
 102 #+end_example
 103
 104 where
 105
 106 - The =#+INFOJS_OPT= option will generat a HTML document that is
 107   foldable and follows the style of =GNU/INFO= document.
 108 - The =:session *R*= option makes sure all the R code is run in the
 109   same session so objects generated in one code block can be accessed
 110   from other code blocks.
 111 - the =:cache yes= option is used to avoid re-evaluating unchanged
 112   code blocks.  This can save significant time when you revise a
 113   document with a lot of R code frequently.
 114 - The =:results output graphics :exports both= option will put both
 115   the R code and its text and graphics output in the generated
 116   document.
 117 - The =:tangle yes= option allows the document to be "tangled" to
 118   generate pure code file.  The short-cut key for tangling is =C-c C-v
 119   t=, which generates a =.R= file with all the R code extracted.
 120 - Note the "-----" string will generate a horizontal line in HTML
 121   file.
 122 - Finally, a hotkey =C-S-f4= (while pressing Ctrl and Shift keys,
 123   press F4 key) is assigned to invoke this skeleton quickly.
 124
 125 ** A Complete Example
 126
 127 We use the following file =test-for-how-to-use-Org-Babel-for-R.org= as an
 128 example file.
 129
 130 #+INCLUDE: "test-for-how-to-use-Org-Babel-for-R.org" example
 131
 132 # The exported HTML file is shown as [[file:test.html][test.html]].
 133
 134 ** Caveats
 135
 136 - Keep the code block indented correctly. Otherwise the graph will not
 137   be embedded in the HTML export file.
 138 - Always have the contents and plots under a section heading to avoid
 139   certain exporting errors.
 140 - It makes things easier if the working directory in *R* session
 141   buffer is the same as the directory of the .org file that
 142   you are writing.  In this way, the plot files can easily be found.
 143 - The macro option (=#+MACRO:=) cannot be used to save the typing
 144   of header options for code blocks.  For example, it does NOT work if
 145   you try to use
 146
 147   #+begin_example
 148   #+MACRO: p  :file $1.png :width 1000 :height 800
 149   #+end_example
 150
 151   to shorten the header to
 152
 153   #+begin_example
 154   #+begin_src R {{{p(plot)}}}
 155   #+end_example
 156