Org-mode as an alternative to knitr

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

link description

[file:path/to/file]

#+NAME: fig:figname
#+CAPTION: This is a caption
[file:path.png]

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.

#+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))
#+END_SRC

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 ² with the appropriate language identifier: R for R, julia for julia, etc. You write your code within the block³ and when you export your document it executes the code and adds the results into the document..

#+BEGIN_LaTeX
\begin{equation}
(a + b)^{2} = a^{2} + 2ab + b^{2}
\end{equation}
#+END_LaTeX

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.

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.

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

[nObs, mean, sd]
#+END_SRC

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

  nObs, mean, sd = params

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

  return vals
#+END_SRC

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

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 possible⁴ in knitr. It also doesn't seem like Jupyter notebooks have this capability although there's another project Beaker which does.