Skip to content
Browse files

added some comments about org-mode comments

  • Loading branch information...
1 parent d4f86bb commit 5d35a0c9b61bc5bce8d6fec35b1d76cb105436d5 Erik Iverson committed Feb 24, 2011
Showing with 159 additions and 127 deletions.
  1. +159 −127 org-mode-R-tutorial.org
View
286 org-mode-R-tutorial.org
@@ -11,10 +11,11 @@
This is an introduction to writing and evaluating R
([[http://www.R-project.org]]) source code within Emacs org-mode
-([[http://orgmode.org]]) buffers. Briefly, org-mode files use headlines to
-organize information. Each top-level headline in this document starts
-with a single '*', like the "Introduction" headline below. While this
-is /not/ an introduction to using org-mode, you will need to know one
+([[http://orgmode.org]]) buffers. Why you might want to do this is covered
+in the text. Briefly, org-mode files use headlines to organize
+information. Each top-level headline in this document starts with a
+single '*', like the "Introduction" headline below. While this is
+/not/ an introduction to using org-mode, you will need to know one
command to proceed: use the TAB key on a headline to open it. TAB will
cycle through the visibility states of the information under the
headline, and eventually TAB will collapse the headline back to how
@@ -42,15 +43,19 @@ the possibilities, you can continue on.
* Introduction
Emacs org-mode 7.01 has an exciting new feature that lets you evaluate
-source code blocks within an org-mode document. This lets you do
+source code blocks within an org-mode document. Source code blocks are
+simply parts of a document that contain source code, as opposed to
+free text such as this paragraph. Using R within org-mode lets you do
things like:
-- insert the results of R code into an Emacs buffer
-- insert graphics and tabular material into a buffer
+- insert the results of R code into your document with the press of a
+ keystroke
+- similarly insert graphics and tabular material generated by R into a
+ document
- insert /graphical depictions/ of LaTeX output into an Emacs buffer
- pass the results of R code to other programming languages such as
- Python in the same document
-- export code and results (similar to Sweave) simultaneously to LaTeX
+ Python in the same document, or vice-versa
+- /export/ code and results (similar to Sweave) simultaneously to LaTeX
and HTML reports /without having to write any markup/
These techniques open up several interesting possibilities for
@@ -80,11 +85,24 @@ this reason, I suggest you download the [[https://github.com/erikriverson/org-mo
document is based on, then visit the file in Emacs, and follow along
there. If you're an Emacs or org-mode user, you should do this now!
Note that the link is to a file in a [[https://github.com/erikriverson/org-mode-R-tutorial][Github]] repository, if you'd like
-to clone it on your system for easy updating in the future, you should
-do that now.
+to clone the whole repository on your system for easy updating in the
+future, you should do that now.
-For those following along in an exported version, such as HTML,
-in the actual org-mode file, source code blocks look like this:
+For those following along in an exported version such as HTML, it is
+important to know that in the actual org-mode file, source code blocks
+look like this:
+
+# Important note for those who are following along in the org-mode
+# file: Since source code blocks look differently in the org-mode
+# buffer and the exported copy (e.g., the #+begin_src lines are not
+# exported), I wanted to show one example for those readers following
+# along in an exported copy of how the blocks actually look in Emacs,
+# thus the example below. To achieve this effect, I have to create an
+# example block. In this tutorial, this is the only example of, well,
+# an example.
+
+# By the way, lines starting with a '#' character, such as this one,
+# represent comments in org-mode, and will never be exported.
#+begin_example
#+begin_src R
@@ -98,8 +116,12 @@ in the actual org-mode file, source code blocks look like this:
#+end_src
#+end_example
-However, when they are /exported/ into documents like this they will
-look like:
+However, when source code blocks are /exported/ into documents like
+this they will look like:
+
+# Once again, the language above is simply for those reading the
+# exported version. For the rest of the tutorial, I assume you're
+# reading in org-mode, so I won't have to interject these comments.
#+begin_src R :exports code
# some R code
@@ -119,13 +141,14 @@ exported version is still worth reading if you simply want to learn
about some of the capabilities and philosophy of org-mode.
This tutorial was written in GNU Emacs 23.2 on Ubuntu 10.04, org-mode
-version 7.01trans, pulled directly from the org-mode git repository.
+version 7.4, pulled directly from the org-mode git repository.
** System Prerequisites for this tutorial
First, we need to make sure our environment is setup correctly for the
examples to run. This requires a bit more work under Windows than
-others, see below.
+Linux, see below. I have not tried this on Mac, so if the instructions
+vary, please let me know.
Here is a list of software we need to run the examples:
1) org-mode 7.01 or greater, see [[http://orgmode.org]]
@@ -147,20 +170,21 @@ For LaTeX support,
6) Some extra LaTeX packages (comes with texlive-full Ubuntu package):
- I found that on my Ubuntu 10.04 installation, I had to install the
+ I found that on my Ubuntu installation, I had to install the
texlive-latex-extra and texlive-fonts-recommended packages to get
the LaTeX documents that org-mode produces to compile. You can get
both of these (plus dvipng) through the Ubuntu package
- texlive-full, so simply installing the `texlive-full` package will
- be the easiest option if you happen to be on Ubuntu.
+ texlive-full, so /simply installing the `texlive-full` package will
+ be the easiest option if you happen to be on Ubuntu/.
For Windows users who have installed MikTeX, I had to use the
MikTeX package manager to install the following packages for LaTeX
support to work: soul, marvosysm, wasysym, wasy, zhmetrics. Install
these and you should be good to go.
-For inline image support,
-7) libpng, GNU/Linux users should already have this. I found under
+For inline image support (i.e., displaying graphics /in/ your Emacs
+buffer),
+7) libpng, Linux users should already have this. I found under
Windows that I had to download
http://downloads.sourceforge.net/gnuwin32/libpng-1.2.37-setup.exe
and after running the installation program, *manually* copy the
@@ -172,18 +196,20 @@ For inline image support,
* Setting up org-mode for source code evaluation
Setting up org-mode to run source code is very simple. So simple in
-fact, that we can do it from right inside this document, using the
-very mechanism its describing (how very GEB!). Since you are reading
-the R tutorial, I will assume you want to specifically run R source
-code blocks within org-mode. Since we use LaTeX later on in the
-tutorial, we'll also take the opportunity to set up org-mode to
-evaluate LaTeX blocks.
+fact, that we can do it from right inside this document using source
+code blocks, the very thing this tutorial is about (how very
+GEB!). Since you are reading the R tutorial, I will assume you want to
+specifically run R source code blocks within org-mode. Since we use
+LaTeX later on in the tutorial, we'll also take the opportunity to set
+up org-mode to evaluate LaTeX blocks.
The absolute, bare minimum setup you need to perform is to run the
following Emacs lisp code. For a preview of what we're going to learn
with in this tutorial, simply hit C-c C-c anywhere in the following
-code block to evaluate it! You will be asked in the minibuffer to
-confirm that you want to evaluate the source code contained in the
+code block to evaluate it! (I am now assuming you're reading this in
+Emacs. If not, you can still follow along to see all the interesting
+things you can do with org-mode!) You will be asked in the minibuffer
+to confirm that you want to evaluate the source code contained in the
block. Confirm this, and you'll be set up for the rest of the
tutorial. You can also add the lines between the #+begin_src
and #+end_src lines to your Emacs initialization file, so that they
@@ -219,14 +245,13 @@ evaluate it. If you're asked to confirm evaluation, go for it!
(org-version)
#+end_src
-This time, because of the different code block argument,
-which will be explained later, we see one great feature of org-mode
-source code blocks. We can automatically insert the results of the
-code blocks in the actual buffer.
-
-Note to Windows users. As mentioned above in the requirements section,
-make sure the directory containing the R executable is added to your
-PATH variable for you to run these examples.
+This time, because of the different code block argument, which will be
+explained later, we see one great feature of org-mode source code
+blocks. We can automatically insert the results of the code blocks in
+the actual buffer. In exported versions, you will also see the results
+automatically inserted. If you're reading this in HTML, whatever
+version you see listed is the version I exported with. I did not have
+to copy and paste the version number, it was /automatically inserted/.
** Prompting for confirmation before evaluating code
Although not necessary, there is one more variable I set in my Emacs
@@ -254,11 +279,12 @@ modifying the variable we defined above to include more languages.
* Org-mode source code blocks (Finally, we can start!)
** Exporting pretty-printed source code blocks
-Before I show you how to evaluate code in org-mode, let's start off
-with looking at a what a typical org-mode code block looks like. We
-just saw a couple examples above of Emacs lisp source code blocks. In
-what follows, we will be working with very simple R functions to show
-off the capabilities of org-mode.
+If you went through the introduction, you got a flavor for how to
+evaluate code in org-mode. Let's start off with looking at a what a
+typical org-mode code block looks like. We just saw a couple examples
+above of Emacs lisp source code blocks. In what follows, we will be
+working with very simple R functions to show off the capabilities of
+org-mode.
The following is a simple R code block in org-mode. You can edit the
code in its own buffer by typing C-c ' (that's a single quote), or
@@ -271,7 +297,8 @@ So here is an example of a source code block. The defining feature is
the #+begin_src and #+end_src lines, with the language definition,
"R", on the first line. All our R code comes between the #+begin_src
and #+end_src blocks. There will be many of these blocks throughout
-this document.
+this document. Remember HTML readers, you cannot see the source code
+blocks
Try opening this code block by putting point anywhere inside of it,
and hitting C-c ' (that's a single quote). This will open a new
@@ -342,11 +369,11 @@ Next, let's actually submit some R code.
*** Obtaining the return value of an R code block
We will now see how to submit a code block. Just as in the
-Introduction with Emacs lisp code, simply hit C-c C-c anywhere in the
-code block to submit it to R. If you didn't set the confirmation
-variable to nil as I described above, you'll have to confirm that you
-want to evaluate the following R code. So go ahead, evaluate the
-following R code block with C-c C-c and see what happens.
+introduction when we evaluated elisp code, simply hit C-c C-c anywhere
+in the code block to submit it to R. If you didn't set the
+confirmation variable to nil as I described above, you'll have to
+confirm that you want to evaluate the following R code. So go ahead,
+evaluate the following R code block with C-c C-c and see what happens.
#+begin_src R
square <- function(x) {
@@ -392,10 +419,10 @@ below.
Now we see the typical R notation for printing a vector. Note in the
-following example that setting `:results output` captures *all*
-function output, not just the return value. We capture things printed
-to the screen with the `cat` function for example, or the printing of
-the variable `x`.
+following example that setting `:results output` captures *all* the R
+output that the code block generates, not just the return value. We
+capture things printed to the screen with the `cat` function for
+example, or the printing of the variable `x`.
#+begin_src R :results output
x <- 1:10
@@ -409,8 +436,9 @@ the variable `x`.
#+end_src
Try changing the :results argument to `value` (which is the same as
-omitting it completely), and re-run the above code block. You should
-see the same org-table output as we saw above.
+omitting the argument completely, since 'value' is the default ), and
+re-run the above code block. You should see the same org-table output
+as we saw above.
*** More information on org-mode source block headers
See [[http://orgmode.org/manual/Header-arguments.html#Header-arguments]]
@@ -422,6 +450,9 @@ per file, or system-wide.
Much like the Sweave \Sexpr command, we can evaluate small blocks of
inline code using the
+# OK, I wasn't entirely truthful in my initial comment at the
+# beginning of the tutorial, here is another example of an example
+
#+begin_example
SRC_R[optional header arguments]{R source code}
#+end_example
@@ -441,9 +472,10 @@ One of the biggest limitations to using code blocks like above is that
a new R session is started up `behind the scenes` when we evaluate
each code block. Not only is this s-l-o-w, but if we define a function
or data.frame in one code block, and want to use it another code block
-later on, we are out of luck. This limitation can be overcome by using
-R session-based evaluation, which sends the R code to a running ESS
-process when the code block is evaluated.
+later on, we are out of luck unless we resort to writing the objects
+to disk. This limitation can be overcome by using R session-based
+evaluation, which sends the R code to a running ESS process when the
+code block is evaluated.
** R session-based evaluation
@@ -514,23 +546,17 @@ initialization file. Either way, evaluate it with C-c C-c.
The following R code generates some graphical output. There are
several things to notice.
-1) :results output is specified. This is because the figure is
- generated using the ggplot2 package in R, which is based on
- something called `grid` graphics. Grid graphics need to be
- explicitly printed when called within a function for their output
- to be displayed. See, for example, [[http://cran.r-project.org/doc/FAQ/R-FAQ.html#Why-do-lattice_002ftrellis-graphics-not-work_003f][R FAQ 7.22]]. When :results value
- (the default) is active, Org-mode is generating an R function
- wrapper. The upshot is: when generating grid-based graphical output
- within org-mode, you need to either use :results output, wrap the
- graphical function in a print call, or use the :session
- argument. See this mailing list [[http://www.mail-archive.com/emacs-orgmode@gnu.org/msg25944.html][post]] for more explanation if you'd
- like.
+1) =:results output graphics= is specified. The 'graphics' value is
+ one we have not seen yet, and lets org-mode know that our code
+ block will be producing a figure of some sort. We need to specify
+ the 'output' value to the :results argument since we are generating
+ a figure with ggplot2, which is a grid-based graphical system.
2) We use a new source code block argument, :file. This argument will
- capture graphical output from the source block and generate a file
- with the given name. Then, the results section becomes an org-mode
- link to the newly created file. In the example below, the file
- generated is called diamonds.png.
+ capture output (a graphic in this case) from the source block and
+ generate a file with the given name. Then, the results section
+ becomes an org-mode link to the newly created file. In the example
+ below, the file generated is called diamonds.png.
Finally, If you have defined the Emacs lisp code for inline-image
support above, an overlay of the file will be inserted inline in
@@ -553,14 +579,10 @@ several things to notice.
#+end_src
-#+results:
-[[file:diamonds.png]]
-
This opens up many opportunities for doing interesting things with R
-within your org-mode documents!
-
-If you're reading an exported version, you might want to see what this
-looks like in the actual org-mode buffer!
+within your org-mode documents. If you're reading an exported version,
+you might want to see what this looks like in the actual org-mode
+buffer.
* Inserting LaTeX output
@@ -602,66 +624,77 @@ generating graphical output from R using a :file argument, so there is
nothing new there.
However, note we have a new argument, :noweb. What does that mean? In
-short, it let's us use syntax like <<CodeBlock()>> to insert the
-results of running a code block named CodeBlock into another source
-code block. So, in our example, we're running the R-latex code block
-defined above, and inserting the results, which need to be valid LaTeX
-code, into our latex code block. For this example, we of course didn't
-need to write an R function to generate such simple LaTeX output, but
-it can be much more complicated, as our next example shows. In short,
-our R code block is helping to write the LaTeX code block for us.
+short, it let's us use syntax like
+
+#+begin_example
+<<CodeBlock()>>
+#+end_example
+
+to insert the results of running a code block named CodeBlock into
+another source code block. So, in our example, we're running the
+R-latex code block defined above, and inserting the results, which
+need to be valid LaTeX code, into our latex code block. For this
+example, we of course didn't need to write an R function to generate
+such simple LaTeX output, but it can be much more complicated, as our
+next example shows. In short, our R code block is helping to write the
+LaTeX code block for us.
Noweb was not invented for org-mode, it's been around for a while, and
is used in Sweave, for example. See [[http://en.wikipedia.org/wiki/Noweb][its Wikipedia page]]. The :noweb
-argument is set to 'no' be default, because the <<X>> syntax is
-actually valid in some languages that org-mode supports.
+argument is set to 'no' be default, because the noweb syntax is
+actually valid in some languages that org-mode supports, and would
+therefore interfere with legitimate use of those languages.
Run the following code block. The "R-latex" R code block will be run,
generating the string \\LaTeX, which is then substituted into this
LaTeX code block, and then turned into the LaTeX logo by the latex
program. Don't worry about the complicated header arguments, those
will be explained in more detail in the next section.
-#+begin_src latex :noweb yes :file (if (eq backend 'html) "latex-logo-html.png" "latex-logo.png") :buffer (if (eq backend 'html) "no" t) :scale 2
+For this code block, since the header line contains so many arguments,
+you can break it up using the #+headers: syntax, as shown below.
+
+#+headers: :file (if (eq backend 'html) "latex-logo-html.png" "latex-logo.png")
+#+headers: :buffer (if (eq backend 'html) "no" t) :scale 2
+#+begin_src latex :noweb yes
<<R-latex()>>~is a high-quality typesetting system; it includes
features designed for the production of technical and scientific
documentation. <<R-latex()>>~is the de facto standard for the
communication and publication of scientific
documents. <<R-latex()>>~is available as free software.
#+end_src
-#+results:
-[[file:latex-logo.png]]
-
-
** A more complicated example, exporting LaTeX in buffer, to HTML, and to PDF
Now let's try something a little more complex, using an R function
that generates a full LaTeX table. This particular example depends on
having the R package Hmisc installed. If you don't have it installed,
-start up R and then do: > install.packages("Hmisc")
+start up R and then do:
+
+#+begin_src R :exports code :eval never
+install.packages("Hmisc")
+#+end_src
What follows is an R source block that generates some LaTeX code
representing a table. We want to be able to insert a =png= image of
the table in the buffer when run with C-c C-c, using the colors of our
current Emacs buffer.
A few sections from now, I'll touch on the exporting features of
-org-mode. Org can generate HTML and PDF versions of documents like
-this one.
+org-mode. Org-mode comes with an exporter that can generate HTML and
+PDF versions of documents like this one.
Back to our example, for HTML export, we also want to generate a
=png=. However, we want the background to be transparent, not whatever
-color our Emacs buffer happened to be.
-
-For LaTeX output, we don't need a =png= file at all, we would of
-course prefer to simply insert the auto-generated LaTeX code in the
-exported LaTeX document, and then compile to PDF.
+color our Emacs buffer happened to be. For LaTeX output, we don't need
+a =png= file at all, we would of course prefer to simply insert the
+auto-generated LaTeX code in the exported LaTeX document, and then
+compile to PDF.
The following should accomplish all three goals.
-We tell the R code block to output latex code using the syntax
-/:results output latex/. Also, only export the code. If we export
+We tell the R code block to return its standard output using the
+syntax /:results output/. Also, only export the code. If we export
both, then the LaTeX results would get exported twice when we export
to PDF, once from each code block. It would actually be exported
twice when we export to HTML, but in that case, since the results are
@@ -712,14 +745,13 @@ Here is an example of how you can configure these background colors.
where="!htbp")
#+end_src
-#+begin_src latex :noweb yes :file (if (and (boundp 'backend) (eq backend 'latex)) nil (if (and (boundp 'backend) (eq backend 'html)) "hmisc-html.png" "hmisc.png")) :buffer (if (and (boundp 'backend) (eq backend 'html)) "no" t)
+
+#+headers: :file (if (and (boundp 'backend) (eq backend 'latex)) nil (if (and (boundp 'backend) (eq backend 'html)) "hmisc-html.png" "hmisc.png"))
+#+headers: :buffer (if (and (boundp 'backend) (eq backend 'html)) "no" t)
+#+begin_src latex :noweb yes
<<Hmisc-latex()>>
#+end_src
-#+results:
-[[file:hmisc.png]]
-
-
And here is how that actually looks in the Emacs buffer.
* Putting it all together, a notebook interface to R
@@ -736,15 +768,16 @@ task you can think of. Since org-mode is a general-purpose authoring
tool, with very strong exporting capabilities, almost anything is
possible.
-For instance, I use org-mode to generate HTML for an R blog that I
-run. Several posters to the org-mode mailing list have mentioned
-writing their entire graduate theses in org-mode.
+For instance, I use org-mode to generate HTML for a web site that I
+run. (You may in fact be reading this article on that web
+site). Several posters to the org-mode mailing list have mentioned
+writing their entire graduate theses in org-mode.
I look at this workflow as an alternative to the excellent [[http://www.stat.uni-muenchen.de/~leisch/Sweave/][Sweave]]
package that cuts out the need for learning LaTeX to produce
high-quality documents. Org-mode is doing all the exporting for you,
-including LaTeX if you'd like. Getting LaTeX and HTML output
-essentially "for free" should not be underestimated!
+including automatically generating the LaTeX markup. Getting LaTeX and
+HTML output essentially "for free" should not be underestimated!
On some level, all these activities assume that you are a comfortable
org-mode user, and that you will be writing code, conducting analyses,
@@ -888,20 +921,19 @@ formats, improving documentation, and the innumerable features that
org-mode provides, and will continue to provide in the future.
As with all new processes, it can be a challenge to start working with
-source code this way. As a current org-mode user, I think the
-benefits are clear.
-
-As for what to do next, try looking at the [[http://orgmode.org/worg/org-contrib/babel/uses.php][results]] of those who use
-org-mode's source code support to accomplish interesting things. You
-can look at current documentation for R support [[http://orgmode.org/worg/org-contrib/babel/languages/ob-doc-R.php][here]].
+source code this way. As a current org-mode user, I think the benefits
+are clear.As for what to do next, try looking at the [[http://orgmode.org/worg/org-contrib/babel/uses.php][results]] of those
+who use org-mode's source code support to accomplish interesting
+things. You can look at current documentation for R support [[http://orgmode.org/worg/org-contrib/babel/languages/ob-doc-R.php][here]].
For an exercise in using org-mode with source code, you can write your
-Emacs initialization file in org-mode! These [[http://orgmode.org/worg/org-contrib/babel/intro.php#sec-8_2_1][instructions]] are slightly
-out of date, but they give you a general idea of how to proceed.
-Essentially, your master Emacs init file will simply tangle an
-org-mode file full Emacs lisp code blocks, and then load the resulting
-file. My Emacs init file is around 1000 lines long, so organizing it
-in a hierarchy with embedded tags and links is very useful to me.
+Emacs initialization file in org-mode (as I do). These [[http://orgmode.org/worg/org-contrib/babel/intro.php#sec-8_2_1][instructions]]
+are slightly out of date, but they give you a general idea of how to
+proceed. Essentially, your master Emacs init file will simply tangle
+an org-mode file full Emacs lisp code blocks, and then load the
+resulting file. My Emacs init file is around 1500 lines long, so
+organizing it in a hierarchy with embedded tags and links is very
+useful to me.
In short, there are many possibilities using these techniques! In many
ways, I have only scratched the surface of the capabilities of

0 comments on commit 5d35a0c

Please sign in to comment.
Something went wrong with that request. Please try again.