Inline Figures in Org-Mode Paper Drafts

Writing a paper often comes along with a problem known as information fragmentation: figures, tables and the respective data sources related to the paper certainly are somewhere on your hard disk – but where? How did I name the file with the data-points again? And, the heck, which commands did I use to create that fancy plot? But chill, there is a way to avoid the joyless seeking and re-finding. At least if you draft your papers in org-mode, as I described in a recent post.

The key tool here is the wonderful org-mode extension Org-R by Dan Davison. It allows to include code fragments that create figures or tables directly into your document. That way, everything will be in one place.  Searching, au revoir.

Introduction to Org-R

Luckily, Dan wrote a comprehensive tutorial on how to use org-R. If your planning to give it a try, I suggest to look over his words first. However, he forgot to mention two things you’ll need to enable the org-R goodness. Insert

(add-to-list ‘load-path “~/site-lisp/org-mode/contrib/lisp”)
(require ‘org-R)

into your .emacs and edit the directory to point into your org-mode directory. Also, you need to have a R instance running (invoke M-x R) in the directory of your document. Try some of the examples given in his tutorial in a new .org document now.

What happens behind the scenes here is that org-R translates the inline commands into a R command sequence. For example, infile:x.csv is converted into x = read.table(...) . The +RR prefix introduces direct R commands, which are executed before the +R commands (except infile:). The result is then inserted as a table or as a link to a graphic. Note that many actions rely on conventions:  outfile:x.png will create a png image. Reading from a datafile will only work if the file suffix is .csv. And its contents will always be stored in a variable x. If you are not sure what is happening behind the scenes, the command showcode:t shows you the created R-code and is hence a great tool for debugging.

Using figures

A typical fragment for creating a figure that is also exported into LaTeX/PDF/HTML properly is

#+CAPTION: Distribution of foot sizes among coputer scientists
#+LABEL: fig:SizeDistribution
#+ATTR_LaTeX: scale=0.5
[[file:images/distanceDist.png]]
#+R: infile:”tmp.csv” #+R: action:density columns:1 args:(:lwd 4)
#+R: outfile:”images/distanceDist.png”
#+R: inline:t

The first three lines give the image a caption and a reference, and define the size of the image in the paper. Invoking C-c (or org-apply) in the second part will (re-)create the image. The command #+R: inline:t is required for the resulting link to the image having the same format as the LaTeX exporter recognizes for figures.

Keeping your document clean

The main intend of org-R obviously was to enable org-mode users to perform quick calculations and create simple graphs from data that originates from org-tables. Undeniable, org-r is very good at that. However, our objective shall rather be to centralize and de-fragment drafting of papers containing complex figures. When it comes to more elaborate graphs and datasets, the usefulness of  the predefined actions vanishes and longer, more complex R code is required. You might rather want to work in ESS/R-mode, where you have all the coloring and intendation niceness, and you do not have to precede every line with an +RR:.

The alternative is to source the functions from a separate .R file, for example you could use

#+CAPTION: Distribution of finger lengths among computer scientists
#+ATTR_LaTeX: scale=0.5
#+LABEL: fig:LengthDistribution
[[file:images/distanceDist.png]]
#+R: infile:”tmp.csv”
#+RR: source(”rcode.R”)
#+RR: myDensity(x)
#+R: outfile:”images/distanceDist.png”
#+R: inline:t

with the following code (imagine a longer fragment) in rcode.R

myDensity <- function(x) {  
plot(density(x[,1]), col=”chartreuse4″, lwd=5, xlim=c(0,2000))
}

That way, you avoid immense R code pollution in your draft, yet you have all the information (data-files, linked code and parameters) in one place. Happy drafting!

Comments are closed.