f04b8c650f1bc552e9ab1a4ce7a94943578ac001
[worg.git] / 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.