I would argue that the most important tool for reproducible research is not Sweave or knitr but GNU make (or rake).

Consider, for example, all of the files associated with a manuscript. In the simplest case, I would have an R script for each figure plus a LaTeX file for the main text. And then a BibTeX file for the references.

Compiling the final PDF is a bit of work:

  • Run each R script through R to produce the relevant figure
  • Run latex and then bibtex and then latex a couple of more times.

And the R scripts need to be run before latex is, and only if they’ve changed.

A simple example

GNU make makes this easy. In your directory for the manuscript, you create a text file called Makefile that looks something like the following (here using pdflatex).

mypaper.pdf: mypaper.bib mypaper.tex Figs/fig1.pdf Figs/fig2.pdf
	pdflatex mypaper
	bibtex mypaper
	pdflatex mypaper
	pdflatex mypaper

Figs/fig1.pdf: R/fig1.R
	cd R;R CMD BATCH fig1.R fig1.Rout

Figs/fig2.pdf: R/fig2.R
	cd R;R CMD BATCH fig2.R fig2.Rout

Each batch of lines indicates a file to be created (the target), the files it depends on (the dependencies), and then a set of commands needed to construct the target from the dependent files. Note that the lines with the commands must start with a tab character.

One oddity: if you need to change directories to run a command, do the cd on the same line as the related command. The following *would not work*:

### this doesn't work ###
Figs/fig1.pdf: R/fig1.R
	cd R
	R CMD BATCH fig1.R fig1.Rout

Another great feature: in the example above, you’d only build fig1.pdf when fig1.R changed. And note that the dependencies propagate. If you change fig1.R, then fig1.pdf will change, and so mypaper.pdf will be re-built.

Using GNU make

You probably already have GNU make installed on your computer. Type make --version in a terminal/shell to see.

To use make:

  • Go into the the directory for your project.
  • Create the Makefile file.
  • Every time you want to build the project, type make.
  • In the example above, if you want to build fig1.pdf without building mypaper.pdf, just type make fig1.pdf.

More complicated examples

There are complicated Makefiles all over the place. Poke around github and study them.

Here are some of my own examples:

And here are some examples from Mike Bostock:

Resources


The source for this minimal tutorial is on github.

Also see my git/github guide, knitr in a knutshell tutorial, and simple site tutorial.