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