Writing knitr in restructured text

by Paul Agapow
in science

tagged knitr, r, reproducibility, restructured-text

Swapping out Markdown for a different markup.

knitr is a useful R package/tool for documenting analysis. Basically, it allows the embedding of R code "chunks" within a simple text document. This document can then be "knitted", which means that the R code is interpreted and reinserted in the document along with the results of that code. Thus analyses can accompany their results, be they numeric or graphical.

An arguably problematic point with knitr is the primary document markup language: Markdown. Markdown is easy to write, but a little under-powered compared to its competitor, restructured Text (rst), which is very popular amongst Python users. Fortunately, knitr also understands rst. Unfortunately, it's not completely clear how you use it. This then is my set of notes about writing knitr documents in rst.

Technical environment

R 2.15.3 on R Studio 0.97, running under Ubuntu 12.10, using knitr version 1.1.

File extensions

The commonly suggested extension for a knitr restructured text file is .Rst. The standard restructured text extension is, of course, .rst. Apart from causing some confusion (i.e. a .Rst file is converted to a .rst file), this may cause legitimate problems in filesystems that are case insensitive (e.g. MacOS). It's far better to use .Rrst. This is logical and while not a three letter extension, it shouldn't cause any problem in this day and age. It's also recognised automatically by knitr.

There is an alternative naming scheme where _knit_ is embedded in the file name and stripped in conversion. That is my_exp_knit_.rst becomes my_exp.rst.

IDEs and production

Unfortunately, R Studio doesn't handle rst-formatted knitr docs, so several of the steps that it handles gracefully for Markdown-flavoured knitr have to be done manually:

  • Create the rst-knitr doc as a text file. Name it appropriately.
  • Edit your document as rst.
  • Prepare for conversion by loading the knitr libraries (library (knitr)) and changing to the directory of your source (e.g. setwd("~/Documents/Projects/R/Writing")).
  • Convert your document with knit ("mydo.Rrst") (or knit2html etc.)
  • Examine the output

The actual R code is embedded in rst with an explicit directive. Start the code chunk with .. {r [label] [, option_list]} and end it with .. .. (note the space between). For example:

.. {r example_code}

x <- 1+1
rnorm(5)

.. ..

which will output something like:

.. sourcecode:: r

x <- 1 + 1
rnorm(5)

::

## [1] -1.0678 -0.2180 -1.0260 -0.7289 -0.6250

Inline R code can be written with the :r: role. For example:

This is text with the value :r:`pi` embedded within it.

becomes:

This is text with the value 3.1416 embedded within it.

Shortcomings and other notes

  • There doesn't seem to be any issue with indenting or using blank lines inside a chunk. The delimiters are the important part.
  • Conversely, trying to literally quote a chunk (i.e. using :: and indenting to display a chunk and not actually interpret it) or inline code is problematic - knitr will process it regardless of the indenting. Presumably this is because the knitting works on a brute force pattern match rather than the directive and role interpretation it looks like.
  • There is another way of marking out code chunks, which is to preface each line with a double dot ... However, I have never been able to get this to work as it is always marked as a parser error.
  • knit2pdf doesn't seems to work with rst documents, because of some malformed intermediate texi file being generated. However rst2pdf could be used instead.