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