Using ski ratings, I would classify knitr as a Blue Square. It's great for beginners and experts alike, balancing excitement and accessibility. Looking back, I was one of the early adopters back in college breezing through regression report assignments while my classmates were still copy-and-pasting to Word. There's no denying that knitr has been an amazing development for reproducibility.

However, sometimes you want a little more. I'd like to introduce you to the Black Diamond of reproducible computing: org-mode. It's a lot more powerful and fun, but definitely has the potential to lead to painful wipe-outs if you're not ready.

At its core, org-mode is just an outlining tool. However, it's just an outlining tool in the same sense that emacs is just a text editor: it's really an environment for reproducible research.



As mentioned, the most basic use of org-mode is to create outlines like the following.

* Section 1
  Text goes here.
* Section 2
  Some more text
** Subsection 1
   Details, details, details
** Subsection 2
   1) We can add lists too
   2) ...
   3) Some more

This is where I started and if it's all you need, you can totally just use it as an outliner. The best strategy learning org-mode (and emacs in general) is to establish a beachhead of functionality you use and gradually expand into using other, more complicated, features.


* TODO Problem 1
* CHECK Problem 2
* DONE Problem 3

You can mark headlines with TODO tags. I find this is helpful for tracking progress; starting off with all TODOs as you complete sections you mark them with a DONE1 tag. You can also specify intermediate tags; I have a CHECK tag which I use to indicate that I should double-check my work before marking it DONE.


* Magic Square
  | 2 | 7 | 6 |
  | 9 | 5 | 1 |
  | 4 | 3 | 8 |

You have easy creation of tables: no longer do you have to mess with LaTeX's tabular/table/tabu environments. Rather you have quick and clean syntax for most of your table needs. You can even export tables from R with the "ascii" library.

Links and Figures

link description


#+NAME: fig:figname
#+CAPTION: This is a caption

As we can see in figure fig:figname

You can also include figures and links. It's straightforward to include captions and references. If you want even more control you can specify certain attributes such as the export width and alignment.

Source Code Blocks

#+BEGIN_SRC R :exports results :results graphics :file figs/regression_line.png
N <- 100
x <- 1:100
y <- x + rnorm(N)

plot(y ~ x)
abline(lm(y ~ x))

So far we haven't been discussing the real feature that tools like knitr and org-mode provide: integration of code and text. Org-mode does this too, and it does it for a variety of languages.

To add code you just create a new source block 2 with the appropriate language identifier: R for R, julia for julia, etc. You write your code within the block3 and when you export your document it executes the code and adds the results into the document..


(a + b)^{2} = a^{2} + 2ab + b^{2}

For common symbols such as Greek letters you can just specify them in-line by using their LaTeX expression with no math-delimiters required. For more complicated structures you can include blocks of LaTeX source code. These work exactly like regular source code blocks.

Multiple Export Formats

You can export org-documents into a variety of formats: HTML and LaTeX (beamer and vanilla) are the two I use most. The nice thing is that almost everything works automatically without changing syntax. If I want to change from HTML to LaTeX it's as simple as pressing a different key in the export menu. The only thing I've run into problems with is exporting complicated LaTeX which doesn't have expressions in MathJax, the LaTeX renderer for HTML

You can also only export only the source code. This supports the Knuth literate-programming style with copious amounts of documentation from which you can extract the code and compile.

Also, because this is emacs, if you need a different format you can write your own export back-end. There are currently a couple packages such as "ox-impress-js" and "ox-reveal" for exporting to browser-based presentation tools. If I get the time I'm interested in exporting to tikzposter.

Polyglot Code Blocks

#+NAME: read_parameters
#+BEGIN_SRC ruby :exports none
nObs = 100
mean = 0
sd = 1

[nObs, mean, sd]

#+NAME: run_simulation
#+BEGIN_SRC python :var params=read_parameters :exports none
  import numpy.random

  nObs, mean, sd = params

  vals = numpy.random.normal(mean, sd, nObs)

  return vals

#+NAME: plot_results
#+BEGIN_SRC R :var x=run_simulation :exports results :results graphics :file test.png
x <- as.numeric(x)

Where org-mode shines in comparison with knitr is the ability to write documents using several languages in concert. For instance, in the snippet above we're passing values from ruby to python to R seamlessly. Thus, you can combine some data munging python code with some Julia optimization code and finish it off with a ggplot from R.

As far as I can tell this isn't possible4 in knitr. It also doesn't seem like Jupyter notebooks have this capability although there's another project Beaker which does.


I currently use org-mode for everything. I write problem sets, papers, presentations, meeting notes, and this very blog post in org-mode. I have my schedule and todo list in org-mode. I even have my emacs configuration file in org-mode. The benefits of having a single tool5 is that you become very efficient.

The one downside is that it takes a while to get the hang of things. This past year I've put in a bunch of time and so have honed my emacs-fu. For newcomers, it might take a while.



In my setup it then turns green which is more emotionally satisfying than I'd care to admit.


Easy shortcut: <s


*C-'* opens the block in a new buffer with the language's major-mode


Without writing out temporary results to file


This goes a bit against my stance on programming languages where I'm very much a proponent of using the "best tool for the job"