org-contrib/babel/languages/ob-doc-R.org.old

   1 #+OPTIONS:    H:3 num:nil toc:2 \n:nil @:t ::t |:t ^:{} -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
   2 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate hideblocks
   3 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
   4 #+TAGS:       Write(w) Update(u) Fix(f) Check(c) noexport(n)
   5 #+TITLE:      Org-babel-R
   6 #+AUTHOR:     Eric Schulte, Dan Davison, Tom Dye
   7 #+EMAIL:      schulte.eric at gmail dot com, davison at stats dot ox dot ac dot uk
   8 #+LANGUAGE:   en
   9 #+STYLE:      <style type="text/css">#outline-container-introduction{ clear:both; }</style>
  10
  11 #+begin_html
  12   <div id="subtitle" style="float: center; text-align: center;">
  13   <p>
  14   Org-babel support for
  15   <a href="http://www.r-project.org/">R</a>
  16   </p>
  17   <p>
  18   <a href="http://www.r-project.org/">
  19   <img src="http://www.r-project.org/Rlogo.jpg"/>
  20   </a>
  21   </p>
  22   </div>
  23 #+end_html
  24
  25 * Notes                                                            :noexport:
  26 ** Template Design
  27   - What the user wants to know:
  28     - Required software
  29     - How to install it
  30     - How to configure it in Org-babel
  31     - Org-babel conventions that might affect the language
  32     - How it modifies Org-babel
  33     - Common ways to use it
  34 ** Queries
  35    - Eric, I think you should name your starter kit Literate Emacs
  36      Starter Kit (LESK).  I've taken the liberty of labeling the link
  37      to it that way below.  Is that OK?
  38    - I think LESK is a couple of steps away from being useful to Lisp
  39      illiterates (like me).  I'm thinking of LESK for Lisp
  40      IlliteraTEs, or LESK LITE.  Is that anathema?
  41
  42 ** Comments
  43    - I'm not sure how you two use tags.  I've used :Fix on Dan's
  44      Graphical output, because I think it should be parceled out to
  45      various sections of the template, and not because I think it
  46      needs fixing in and of itself.
  47
  48 * Requirements                                                       :Update:
  49 ** [[http://ess.r-project.org/][Emacs Speaks Statistics]]
  50    Required for session-based evaluation.
  51 *** Installation using  [[http://github.com/eschulte/emacs-starter-kit/tree/master][Literate Emacs Starter Kit]]                    :noexport::Write:
  52     - unpack ess-VERSION.tgz in .emacs.d/src
  53     - for me, this created ess-5.6, need an alias named ess?
  54     - where to put (require 'ess-site)?
  55 * Examples
  56   :PROPERTIES:
  57   :CUSTOM_ID: examples
  58   :END:
  59 Examples demonstrating the use of R code within Org-mode.
  60
  61 - [[file:R/RBabelExample.org][RBabelExample]] ([[http://orgmode.org/w/?p%3Dworg.git%3Ba%3Dblob_plain%3Bf%3Dorg-contrib/babel/languages/R/RBabelExample.org%3Bhb%3DHEAD][.org]], [[http://orgmode.org/w/?p%3Dworg.git%3Ba%3Dblob_plain%3Bf%3Dorg-contrib/babel/languages/R/RBabelExample.pdf%3Bhb%3DHEAD][.pdf]]) -- a short introductory example
  62 - [[file:../uses.org::#foo][foo.org]] ([[http://orgmode.org/w/?p%3Dworg.git%3Ba%3Dblob_plain%3Bf%3Dorg-contrib/babel/examples/foo.org%3Bh%3Dff77d114bd79eb600139d23338910b1948c06332%3Bhb%3DHEAD][.org]], [[http://orgmode.org/w/?p%3Dworg.git%3Ba%3Dblob%3Bf%3Dorg-contrib/babel/examples/foo.pdf%3Bh%3D15d4233e6561b99216c768a9f94ddcbd0c052524%3Bhb%3DHEAD][.pdf]], [[http://orgmode.org/w/?p%3Dworg.git%3Ba%3Dblob_plain%3Bf%3Dorg-contrib/babel/examples/foo.org.html%3Bh%3D3d157d2ac1b361eea9afc71436a3b0a23a5f1070%3Bhb%3DHEAD][preview]]) -- a more complex example
  63
  64 * Configuration in Org-babel                                 :Write:noexport:
  65 ** Variables
  66 * Language-specific Features                                          :Write:
  67 ** Graphical output                                                     :Fix:
  68     If a =:file filename.ext= header argument is provided to an R
  69     source block, then the output from the source block will go to the
  70     named file. What that output is depends on the value of the
  71     =:results= header argument.
  72
  73     If the value is =:results graphics= then "base" graphics output is
  74     captured on disk, and a link to the graphics file is inserted into
  75     the Org-mode buffer (as is also the case with the graphics-only
  76     languages such as gnuplot, ditaa, dot, and asymptote.)  An attempt
  77     is made to find an R graphics device corresponding to the file
  78     extension.  Currently, the following extensions are recognized:
  79     .png, .jpg, .jpeg, .tiff, .bmp, .pdf, .ps, .postscript, and .svg.
  80     If the extension of the file name passed to =:file= is not
  81     recognized, png format output is created by default.
  82
  83
  84     For further clarification of =:file= and =:results=, see [[http://thread.gmane.org/gmane.emacs.orgmode/35396/focus=35766][this
  85     thread]].
  86
  87 # <<r-dev-header-args>>
  88     Additionally, values for several arguments to the R graphics
  89     device can be passed using header args:
  90
  91 #+begin_example
  92     :width :height :bg :fg :units :pointsize :antialias :quality :compression :res :type :family
  93     :title :fonts :version :paper :encoding :pagecentre :colormodel :useDingbats :horizontal
  94 #+end_example
  95
  96     See the R help page for the graphics devices (e.g. using =?png=,
  97     =?pdf=) for explanations of these arguments.
  98
  99     Arguments to the R graphics device can also be passed as a string
 100     in R argument syntax, using the header arg =:R-dev-args=.  This is
 101     useful for graphics device arguments that don't have an Org-babel
 102     header argument counterpart.
 103
 104     The following example source block illustrates use of
 105     =:R-dev-args= to pass background and foreground colors.  Note that
 106     both of these arguments can also be passed directly as
 107     header args, using =:fg= and =:bg=.
 108
 109 #+begin_src org
 110   ,#+header: :width 8 :height 8 :R-dev-args bg="olivedrab", fg="hotpink"
 111   ,#+begin_src R :file z.pdf :results graphics
 112   ,plot(matrix(rnorm(100), ncol=2), type="l")
 113   ,#+end_src
 114 #+end_src
 115
 116 If "base" graphics aren't begin generated, then additional header
 117 arguments might be needed.  For example, with the =ggplot2= package,
 118 graphics output requires =:results output graphics=.  The following
 119 example writes the graphics output to the file specified in the
 120 =:file= header argument.
 121
 122 #+begin_example
 123   ,#+name: r-edge-angle-histogram
 124   ,#+begin_src R :results output graphics :var x=whole-adzes :file r/adze_edge_angle.png :width 400 :height 300
 125     library(ggplot2)
 126     adze.edge.angle <- ggplot(x, aes(edge_angle))
 127     adze.edge.angle + geom_histogram(aes(y=..density..)) +
 128     geom_density(weight=2) + xlab("Measured cutting edge angle (degrees)")
 129   ,#+end_src
 130
 131   ,#+results:
 132   [[file:r/adze_edge_angle.png]]
 133 #+end_example
 134
 135 ** Missing Values                                            :Write:noexport:
 136 * Additions to Org-babel                                              :Write:
 137 ** Header Arguments
 138 R support introduces a large number of header arguments to Org-babel.
 139 Most of these set parameters of R graphic devices, as described [[r-dev-header-args][above]].
 140
 141 It is also possible to include column names during export of data
 142 frames.
 143
 144 | Header arg    | Meaning                        |
 145 |---------------+--------------------------------|
 146 | :colnames yes | Include column names in output |
 147
 148 * Common Idioms                                              :Write:noexport:
 149 * Tips for usage
 150 ** Debugging
 151    This section contains some tips on how to proceed if your R code is
 152    not doing what you had hoped.
 153 *** Use =:session=
 154     Evaluate your code using the =:session= header argument, then
 155     visit the R buffer (i.e. the buffer containing the "inferior ESS"
 156     process). Then you can inspect the objects that have been created,
 157     and try out some lines of code. Useful R functions for inspecting
 158     objects include (as always in R, type a "?" followed by the name
 159     of the function to get help with the function)
 160     - str
 161     - dim
 162     - summary
 163 *** Use ESS to step through evaluation line-by-line
 164     1. Use C-c ' to visit the edit buffer for your code block
 165     2. Use ess-eval-line-and-step to evaluate each line in turn
 166
 167 In addition to ess-eval-line-and-step, there are several other ESS
 168 functions with names beginning ess-eval-*. They evaluate lines and
 169 regions in different ways; it's worth looking at their descriptions
 170 (C-h f).
 171
 172 ** LaTeX code from R
 173 This example summarises a linear regression fit. Usually the org-babel
 174 user should not have to be involved in latex code generation, as this
 175 is the responsibility of org-mode's latex export engine. But in this
 176 example, neither the printed representation nor the value of
 177 summary(lm(y ~ x)) is at all tabular, and it would therefore require
 178 some work to get the information in to an org table. However, the
 179 xtable package can be used to output a latex table. Using ':results
 180 latex' in org-babel ensures that this is stored as a latex block in
 181 the org buffer and thus can be included correctly in latex-based
 182 export targets.
 183
 184 #+begin_src R :results output latex
 185 library(xtable)
 186 x <- rnorm(100)
 187 y <- x + rnorm(100)
 188 xtable(summary(lm(y ~ x)))
 189 #+end_src
 190
 191 #+results:
 192 #+BEGIN_LaTeX
 193 % latex table generated in R 2.9.2 by xtable 1.5-5 package
 194 % Wed Dec  9 17:17:53 2009
 195 \begin{table}[ht]
 196 \begin{center}
 197 \begin{tabular}{rrrrr}
 198   \hline
 199  & Estimate & Std. Error & t value & Pr($>$$|$t$|$) \\
 200   \hline
 201 (Intercept) & -0.0743 & 0.0969 & -0.77 & 0.4454 \\
 202   x & 1.0707 & 0.0923 & 11.60 & 0.0000 \\
 203    \hline
 204 \end{tabular}
 205 \end{center}
 206 \end{table}
 207 #+END_LaTeX
 208 ** Org output from R
 209 David Hajage's [[http://cran.r-project.org/web/packages/ascii/index.html][ascii]] R package creates appropriate plain text
 210 representations of many R objects, and features an option to specify
 211 that the plain text representations should be in Org format. This can
 212 be particularly useful for retrieving non-tabular R data structures in
 213 Org.
 214
 215 In R:
 216 #+begin_example
 217 > library(ascii)
 218 > options(asciiType = "org")
 219 > library(Hmisc)
 220 > ascii(describe(esoph))
 221 #+CAPTION: esoph
 222 - 5 Variable
 223 - 88 Observations
 224
 225 *agegp*
 226 |  n | missing | unique |
 227 | 88 |       0 |      6 |
 228
 229 |           | 25-34 | 35-44 | 45-54 | 55-64 | 65-74 | 75+ |
 230 | Frequency |    15 |    15 |    16 |    16 |    15 |  11 |
 231 | %         |    17 |    17 |    18 |    18 |    17 |  12 |
 232
 233 *alcgp*
 234 |  n | missing | unique |
 235 | 88 |       0 |      4 |
 236
 237  0-39g/day (23, 26%), 40-79 (23, 26%), 80-119 (21, 24%), 120+ (21, 24%)
 238
 239 *tobgp*
 240 |  n | missing | unique |
 241 | 88 |       0 |      4 |
 242
 243  0-9g/day (24, 27%), 10-19 (24, 27%), 20-29 (20, 23%), 30+ (20, 23%)
 244
 245 *ncases*
 246 |  n | missing | unique |  Mean | .05 | .10 | .25 | .50 | .75 | .90 | .95 |
 247 | 88 |       0 |     10 | 2.273 | 0.0 | 0.0 | 0.0 | 1.0 | 4.0 | 5.3 | 6.0 |
 248
 249 |           |  0 |  1 |  2 |  3 | 4 | 5 | 6 | 8 | 9 | 17 |
 250 | Frequency | 29 | 16 | 11 |  9 | 8 | 6 | 5 | 1 | 2 |  1 |
 251 | %         | 33 | 18 | 12 | 10 | 9 | 7 | 6 | 1 | 2 |  1 |
 252
 253 *ncontrols*
 254 |  n | missing | unique |  Mean | .05 | .10 | .25 | .50 |  .75 |  .90 |  .95 |
 255 | 88 |       0 |     30 | 11.08 | 1.0 | 1.0 | 3.0 | 6.0 | 14.0 | 29.1 | 40.0 |
 256
 257  lowest:  1  2  3  4  5, highest: 40 46 48 49 60
 258 #+end_example
 259
 260
 261  From Org-babel:
 262 #+begin_src R :results output org
 263   library(ascii)
 264   options(asciiType="org")
 265   ascii(summary(table(1:4, 1:4)))
 266 #+end_src
 267
 268 #+results:
 269 Loading required package: proto
 270 - Number of cases in table: 4
 271 - Number of factors: 2
 272 - Test for independence of all factors:
 273   - Chisq = 12, df = 9, p-value = 0.2133
 274   - Chi-squared approximation may be incorrect
 275
 276 ** ess-switch-to-end-of-ESS
 277    When in an org mode R code edit buffer with an associated R
 278    session, ess-switch-to-end-of-ESS will bring the R session buffer
 279    into view and place point at the prompt. ESS binds this to C-c C-z
 280    and C-M-r by default.