Skip to content
Find file
5d35a0c
943 lines (759 sloc) 40.4 KB

Org-mode and R: An Introduction

Introduction

Emacs org-mode 7.01 has an exciting new feature that lets you evaluate 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 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, 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 automatically generating comprehensive documentation and advanced reports. You can also extract the source code portions of an org-mode document for further processing, through a process called tangling. This tutorial will get you started using these org-mode features together with the R programming language.

If you are unfamiliar with org-mode itself, you can learn a lot more from the project’s website. There are many good tutorials available on org-mode already. The compact guide is a great place to start. This current document focuses on source code support. Note that while the features being demonstrated in this document were being developed, the project was known as org-babel. Thus, many of the variables and function names reference ‘org-babel’ in their names. Org-babel is now distributed with org-mode, so many of the previous configuration hurdles are now gone. Keep this in mind as you read old mailing list posts and documentation. The authors of org-babel are Eric Schulte and Dan Davison. They have worked very hard creating this amazing system!

Although you may be viewing this tutorial in an exported format like HTML or PDF, I wrote this tutorial in org-mode. You will benefit most from it by following along in org-mode. Only then can you interactively evaluate the examples to see org-mode in action. For this reason, I suggest you download the actual org mode file that this 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 Github repository, if you’d like 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, it is important to know that in the actual org-mode file, source code blocks look like this:

# some R code 
square <- function(x) 
{
  x * x
}
  
square(1:10)

However, when source code blocks are exported into documents like this they will look like:

# some R code 
square <- function(x) 
{
  x * x
}
  
square(1:10)

It’s something to be aware of when following along from an exported version such as HTML, since I will be referencing source code block arguments that you will not be able to see. That is another very good reason to follow along with the raw org mode file. However, an 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.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 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
  2. a working R installation, see http://www.R-project.org
  3. The R examples use the ggplot2 and Hmisc packages from CRAN. Simply install from the R command line by issuing the command,
install.packages(c("ggplot2", "Hmisc"))

The directory containing the R binary must be in your PATH environment variable. For Windows users, you will probably have to add this yourself.

For LaTeX support,

  1. a working LaTeX installation, see http://latex-project.org. Windows users can use MikTeX.
  2. dvipng program (comes with MikTeX or texlive-full Ubuntu package)
  3. Some extra LaTeX packages (comes with texlive-full Ubuntu package):

    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.

    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 (i.e., displaying graphics in your Emacs buffer),

  1. 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 libpng12.dll and zlib1.dll files into my emacs-23.x\bin directory, and then restart emacs for inline image support to work. One easy way to test if png support is working is to simply open a png file within Emacs from dired.

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 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! (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 are always run when starting Emacs.

So go ahead, hit C-c C-c with point in the following code block. The tutorial will explain the syntax of the block, so don’t worry about that now!

(org-babel-do-load-languages
 'org-babel-load-languages
 '((R . t)
   (latex . t)))

If you received any type of error message, please make sure that you have the proper version of org-mode installed by typing M-x org-version <Enter>. You should have at least 7.01. If you still are running org-mode version 6.xx or before, please visit the project web site for instructions on downloading the latest version.

If you didn’t get any errors, org-mode is now setup to run the R examples that follow. You should have seen the result of the code block (a list) printed in the minibuffer.

Instead of typing M-x org-version, which is simply calling an emacs-lisp function, you could do this through an org-mode source code block. Move point to the code block below, and hit C-c C-c again to evaluate it. If you’re asked to confirm evaluation, go for it!

(org-version)

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 initialization file relating to evaluating source code in org-mode. By default, org-mode will ask you to confirm each and every time you evaluate a source code block. If you ran the above source code block with C-c C-c, you will have noticed that behavior. I turn this feature off with the following line. If you choose, simply hit C-c C-c to evaluate it for this session, or put it in your Emacs initialization file. Then, you won’t be asked before org-mode evaluates source code blocks. You may view this as a security risk. Always look over the code you’re going to evaluate before submitting it to the system.

(setq org-confirm-babel-evaluate nil)

Other supported languages

Besides R, which we just set up with the above source code block, see here for a list of languages that org-mode currently supports. You can then add more languages to your personal setup if you desire, by 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

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 just by editing the code within the org-mode buffer. The nice thing about opening the code in its own buffer with C-c ‘, is that the buffer is then in ESS mode. All the ESS key bindings, interaction with the inferior R process, and syntax highlighting work as expected.

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. 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 buffer, with the contents of the source code block. You can then edit this buffer just like any other R file, as it is in R-mode from ESS. When finished editing, hit C-c ’ again, and you’ll see any changes you made reflected in this org-mode buffer. You can control how this new ESS-mode buffer is displayed by setting the org-src-window-setup variable in Emacs.

square <- function(x) 
{
  x * x
}
  
square(1:10)

So now we have this code block defined. Why would we want to do something like that with org-mode? First and foremost so that when we export an org-mode document to a more human-readable format, org-mode recognizes those lines as R syntax, and highlights them appropriately in the HTML or LaTeX output. The lines will be syntax highlighted just like they would be in an R code buffer in Emacs. In fact, if you’re reading an exported version of this document, you’re actually seeing what the code block looks like upon export!

Try this for yourself. With point anywhere in this subtree, for example, put it here [ ], hit C-c C-e 1 b (that’s the number ‘one’). This subtree should be exported to an HTML file and displayed in your web browser. Notice how the source code is syntax highlighted.

Note: for syntax highlighting in exported HTML to work, htmlize.el must be in your load-path. The easiest way to make that happen if you haven’t already is to run the following Emacs lisp code, after changing the “/path/to” portion to reflect your local setup. I have the following in my Emacs init file, but you can once again just type C-c C-c to submit the code and evaluate the lisp.

(add-to-list 'load-path "/path/to/org-mode/contrib/lisp")

Evaluating the code block using org-mode

As I mentioned, defining the above code block would be useful if we wanted to export the org-mode document and have the R code in the resulting, say, HTML file, syntax highlighted. The feature that org-mode now adds in version 7.01 is letting us actually submit the code block to R to compute results for either display or further computation.

It is worth pointing out here that org-mode works with many languages, and they can all be intertwined in a single org-mode document. So you might get results from submitting an R function, and then pass those results to a Python or shell script through an org-table. Org-mode then becomes a meta-programming tool. We only concentrate on R code here, however.

We did see above in the setup section that we have Emacs lisp code in this same org-mode file. To be clear, you can mix many languages in the same file, which can be very useful when writing documentation, for instance.

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 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.

square <- function(x) {
  x * x
}

square(1:10)

If you’ve submitted the code block using C-c C-c, and everything went well, you should have noticed that your buffer was modified. Org-mode has inserted a results section underneath the code block, and above this text. These results are from running the R code block, and recording the last value. This is just like how R returns the last value of a function as its return value. Notice how the results have been inserted as an org-table. This can be very useful. However, what if we wanted to see the standard R output? You will see how to do that in the next section.

You can also try changing the source code block, and re-running it. For example, try changing the call to the square function to 1:12, then hit C-c C-c again. The results have updated to the new value!

Obtaining all code block output

We just saw how the last value after evaluating our code is put into an org-mode table by default. That is potentially very useful, but what if we just want to see the R output as it would appear printed in the R console? Well, just as R functions have arguments, org-mode source blocks have arguments. One of the arguments controls how the output is displayed, the :results argument. It is set to ‘value’ by default, but we can change it to ‘output’ to see the usual R output. Notice the syntax for setting source code block arguments below.

square <- function(x) {
  x * x
}

square(1:10)

Now we see the typical R notation for printing a vector. Note in the 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`.

x <- 1:10
x
square <- function(x) {
  cat("This is the square function.\n")
  x * x
}

square(1:10)

Try changing the :results argument to `value` (which is the same as 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 for more information on source code block header arguments, including the various ways they can be set in an org-mode document: per block, per file, or system-wide.

Inline code evaluation

Much like the Sweave \Sexpr command, we can evaluate small blocks of inline code using the

SRC_R[optional header arguments]{R source code} 

syntax. So, in org-mode I will type

SRC_R[:exports results]{round(pi, 2)}

and you will see src_R[:exports results]{round(pi, 2)} in the exported output. You’ll see examples of how to use the :exports code block header in a few sections.

Passing data between code blocks

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 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

Often in R, we will define functions or objects in one code block and want to use these objects in subsequent code blocks. However, each time we submit a code block using C-c C-c, org-mode is firing up an R session, submitting the code, obtaining the return values, and closing down R. So, by default, our R objects aren’t persistent! That’s an important point. Fortunately, there is an easy way to tell org-mode to submit our code blocks to a running R process in Emacs, just like we do with R files in ESS.

You simply use the :session argument to the org-mode source block.

square <- function(x) {
  x * x
}
x <- 1:10 

So, the above code block defines our function (square) and object (x). Now we want to apply call our square function with the x object. Without :session, we could not do this.

square(x)

Running the above code block will result in an error, since a new R session was started, and our objects were not available. Now try the same code block, but with the :session argument, as below.

square(x)

The results we expect are now inserted, since we submitted this code block to the same R session where the square function was defined.

Code blocks using different languages

Even though this tutorial covers the R language, one of org-mode’s main strengths is its ability to act as a meta programming language, using results from a program written in one language as input to a program in another language.

See http://orgmode.org/worg/org-contrib/babel/intro.php#meta-programming-language for an example of this. To keep things as focused on R as possible, I chose not to include an example like the one found in the link in this tutorial.

Inserting R graphical output

Here is a really cool feature of evaluating source code in org-mode. We can insert images generated by R code blocks inline in our Emacs buffer! To enable this functionality, we need to evaluate a bit of Emacs lisp code. If this feature is something you want every time you use org-mode, consider placing the code in your Emacs initialization file. Either way, evaluate it with C-c C-c.

(add-hook 'org-babel-after-execute-hook 'org-display-inline-images)   
(add-hook 'org-mode-hook 'org-display-inline-images)   

The following R code generates some graphical output. There are several things to notice.

  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 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 the actual org-mode document! Run the following source code block to see how it works.

library(ggplot2)
data(diamonds)
dsmall <-diamonds[sample(nrow(diamonds), 100), ] 
p <- qplot(carat, price, data = dsmall)

plot.rrg <- function(...) roundrectGrob(gp = gpar(fill = "skyblue1", col = NA),
                                        r = unit(0.06, "npc"))

panel.rrg <- function(...) roundrectGrob(gp = gpar(fill = "grey80", col = NA),
                                        r = unit(0.06, "npc"))

p + opts(plot.background = plot.rrg) + opts(panel.background = panel.rrg)

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.

Inserting LaTeX output

We have just seen how to include graphical output in our org-mode buffer. We can also do something similar with LaTeX output generated by R. Of course, this requires at least a working LaTeX installation. You will also need to install the dvipng program (dvipng package in Ubuntu, for instance). See the System Requirements section for other prerequisites.

A simple example

Let’s work on a very simple example, displaying a LaTeX description in our org-mode buffer, using the official LaTeX logo. We will use R to generate the code that will display the official logo. There’s obviously no reason to do this except for demonstration purposes.

First we must define an R source block that generates some LaTeX code that displays the logo. That’s fairly straightforward. Notice we have given the source code block a name, so that we can call it later. We use the #+srcname syntax to do this. Note that you don’t have to run the following code block, it will be run automatically by the next one.

lf <- function() {
    "\\LaTeX"
}

lf()

Next, we define a new source block using the “latex” language, instead of “R”, as we have been using. If we use a :file argument with a LaTeX source code block, org-mode will generate a file of the resulting dvi file that LaTeX produces, and display it. This is just like 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.

Noweb was not invented for org-mode, it’s been around for a while, and is used in Sweave, for example. See its Wikipedia page. The :noweb 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.

For this code block, since the header line contains so many arguments, you can break it up using the #+headers: syntax, as shown below.

<<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.

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")

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-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.

The following should accomplish all three goals.

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 wrapped in #+BEGIN\_LATEX/#+END\_LATEX lines, and are therefore not included in the HTML export.

In the LaTeX code block, a file will be generated for in-buffer evaluation and HTML export, but we don’t want it produced for LaTeX export, otherwise the image and the actual table will be included in the PDF.

The final buffer argument controls the color selection through the org-format-latex-options variable. Essentially, if buffer is set to ‘yes’, your Emacs buffer colors will be used as arguments to the dvipng program used to produce the image, assuming you don’t change that values of the elements to something other than ‘default’ in org-format-latex-options. If buffer is ‘no’, then the html* elements of that variable will be used.

Here is an example of how you can configure these background colors.

(setq org-format-latex-options
      '(:foreground default :background "rgb 1 1 1" 
                    :scale 1.5
                    :html-foreground "Black" :html-background "Transparent"
                    :html-scale 1.0 
                    :matchers ("begin" "$1" "$" "$$" "\\(" "\\[")))
set.seed(21879) 
library(Hmisc)
  
df <- data.frame(age = rnorm(100, 50, 10),
                 gender = sample(c("Male", "Female"), 100, replace = TRUE),
                 study.drug = sample(c("Active", "Placebo"), 100, replace = TRUE))

label(df$study.drug) <- "Treatment" 
label(df$age) <- "Age at randomization" 
label(df$gender) <- "Gender" 
  
latex(summary(study.drug ~ age + gender, data = df,
              method = "reverse", overall = TRUE, test = TRUE), 
      long = TRUE,  file = "", round = 2, exclude1 = FALSE, npct = "both",
      where="!htbp")
<<Hmisc-latex()>>

And here is how that actually looks in the Emacs buffer.

Putting it all together, a notebook interface to R

Combining the techniques shown above: submitting code blocks, capturing output for further manipulation, and inserting graphical and tabular material, we essentially have a basic notebook-style interface for R.

This is potentially useful for countless tasks such as: a laboratory notebook, time series analysis of diet/exercise habits, tracking your favorite baseball team over the course of a season, or any reporting 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 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 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 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, and possibly exporting results through the familiar Emacs and org-mode user interface. Through the exporting functionality, org-mode offers many useful and easy-to-use options to share results of your efforts with others, but what about the code itself?

Most people you have to share code with aren’t going to want an org-mode file full of source code!

Tangling code

With many projects, you will have to share code with other programmers, who are most likely not going to be programming in org-mode. Therefore, sharing an org-mode file full of code is not an option.

Or, consider development of an R package. The package building process obviously operates on .R files, each full of R functions. However, that’s not what we have in a document like this one.

It is in situations like these where tangling can be used.

The process of tangling an org-mode document essentially extracts the code contained in org-mode source code blocks, and places it in a file of the appropriate type. How do we do this? We use the :tangle source code block header argument to direct org-mode what to do. Then, we call the tangle function on the file to extract the source code!

Read on to learn how to perform each of these steps.

Instructing org-mode how to tangle with header arguments

Let’s take a look at a few examples. Each example contains an R comment, so that you can see in the resulting .R file where it came from.

This first example will not extract any code from the source block. It is the default behavior.

# tangle was not specified
x <- 1:10
print(x) 

This will place the code in source code block in org-mode-R-tutorial.R, since we don’t specify a filename for the .R file.

# tangle was specified, but no file given
x <- 1:10
print(x)

This will place the tangled code in Rcode.R, since we specify that name.

# tangle was specified, and a file name given (Rcode.R)
x <- 1:10
print(x)

Note that we will have multiple source code blocks in an org-mode file, and they might have different types. For example, we might have R and Python code in the same document, but different source blocks.

This is no problem, as the tangling mechanism will generate appropriate files of each type, containing only the code of that type.

Finally, you can specify the :tangle argument as a buffer-wide setting, so that you don’t have to specify it for every source code block.

This opens up exciting possibilities like having a single org-mode file that includes:

  • all code for an R package
  • all documentation for the package
  • unit tests for the package
  • material to generate slides for presentations, through org-beamer
  • notes taken during package development
  • links to emails with bug reports, feature requests, etc.
  • a Makefile to build the package and documentation

Tangling the document

Now that we have seen how to instruct org-mode how to produce source code files from our org-mode document, how do we actually tangle the document?

We simply have to call the org-babel-tangle function, bound by default to C-c C-v C-t.

Org-mode confirms in the minibuffer how many code blocks have been tangled, and inspecting the file system should show that your source code files have been created. There exists a hook function that will run any post-processing programs you have defined, for example, a compiler, `R CMD build`, or running `make` with a Makefile, possibly itself generated from the org-mode document!

Exporting documents containing code and results

Org-mode provides a rich set of functions and customizations for exporting documents into more human-readable forms, and for users who are not Emacs or org-mode users. The most common methods are generating PDF documents through LaTeX, and HTML output. Source code will be syntax highlighted in HTML. There are various options for doing this in PDF, including using the listings package.

With org-mode source blocks, you can choose to export the source code, the results of evaluating the source code, neither, or both. The :exports header argument controls this. See the documentation for further examples.

As an example, type C-c C-e b to see an HTML version of this document.

Some fairly sophisticated processes, including complete report generation using R graphics and tables, can be achieved through this facility.

Using org-mode in this manner is essentially an alternative to Sweave, with the advantages of:

  • do not need to learn LaTeX or other markup language
  • any future org-mode export engines will be available to you
  • writing code in org-mode gives you access to a hyper-commenting system, with features such as TODO items, in-document linking, tags, and code folding.

Whether or not you use all the features that org-mode provides, you can use the system for literate programming and reproducible research, on projects large and small.

Where to go from here?

We have seen how to submit R code for evaluation in org-mode. There are many good reasons to do this, including tying results to source code, code folding, exporting of code and results into many common 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 results of those who use org-mode’s source code support to accomplish interesting things. You can look at current documentation for R support here.

For an exercise in using org-mode with source code, you can write your Emacs initialization file in org-mode (as I do). These 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 org-mode in this tutorial. As always, the official manual will be the source of the most up-to-date information and features of this great tool. Happy org-ing!

Jump to Line
Something went wrong with that request. Please try again.