An Sweave Demo
Literate Programming in R
Reproducible Research

University of Minnesota, Twin Cities     School of Statistics     Charlie's Home Page

This web page provides an illustration or three of Sweave, which is literate programming for R or (a newer buzzword) a package for reproducible research.

Sweave is an R function now available by default. Its author is Friedrich Leisch and its web site is just a directory, not a web page wherein one can find the manual, the FAQ, and three papers about it.

Contents

• Literate Programming
• Reproducible Research
• My Examples
• An Issue with Sweave.sty

Literate Programming

The term literate programming was coined by Donald Knuth, one of the true geniuses of computing, the author/inventor of TeX, among other things.

The basic idea is that

• Programs are useless without descriptions.
• Descriptions should be literate, not comments in code or typical reference manuals.
• The code in the descriptions should work. Thus it is necessary to extract the real working code from the literary description.

Some web sites describing this are

• Knuth's page on the subject.
• The FAQ.

Reproducible Research

The term reproducible research is newer, and I don't know who coined it. The basic idea is simple. It's the scientific ideal.

• Research should be reproducible. Anything in a scientific paper should be reproducible by the reader.
• Whatever may have been the case in low tech days, this ideal has long gone. Much scientific research in recent years is too complicated and the published details to scanty for anyone to reproduce it.
• The lack of detail is not entirely the author's fault. Journals have severe page pressure and no room for full explanations.
• For many years, the only hope of reproducibility is old-fashioned person-to-person contact. Write the authors, ask for data, code, whatever. Some authors help, some don't. If the authors are not cooperative, tough.
• Even cooperative authors may be unable to help. If too much time has gone by and their archiving was not systematic enough and if their software was unportable, there may be no way to recreate the analysis.
• Fortunately, the internet comes to the rescue. No page pressure there!
• Nowadays, many scientific papers also point to supplementary materials on the internet, either at the journal's or the author's web site. It doesn't matter so long as the material is permanently available. Data, computer programs, whatever should be there.

But even more, the entire analysis should be reproducible. In real science, this is hard. Redoing all the chemistry, or all the field work, or whatever is asking a lot.

But in mathematical and computing sciences, like statistics, reproducibility is perfectly possible. It only takes will and knowledge to do it.

Some web sites describing this are

• A paper by Robert Gentleman and Duncan Temple Lang which is a Bioconductor Project working paper.
• a paper by Jonathan Buckheit and David Donoho (PDF).
• a new web site www.reproducibleresearch.org
• and two more links pointed out to me by Jon Wellner
  • a web site by Roger Koenker
  • a web site by Matt Schwab and Jon Claerbout
  more links at Jon's reproducible research page.

My Examples

Intro

This one is just a demo. The LaTeX (PDF) shows what one can do. The source file (foo.Rnw) shows how to do it.

This example is a little unusual because it includes a lot of Sweave included literally in the LaTeX portion of the document (so you can see what it looks like), but that's not what you usually want to do.

The following examples are more typical. They don't explain Sweave, they just do a job.

An R Package Vignette

A package vignette is an Sweave file that illustrates the use of the package. Because it is Sweave, it is non-bogus. The code actually works. We know it works because it worked to produce the LaTeX output!

For the official poop on vignettes see the relevant section in the Writing R Extensions book.

The day I heard Robert Gentleman talk about this, I went home and wrote the following vignette for an (already written) package. The LaTeX (PDF) shows what one can do. The source file (demo.Rnw) shows how to do it.

One new bit about vignettes. They have a line like

from this example, which is just a LaTeX comment but is used to tell the package that this is a vignette. So the regular documentation mentions the vignette (click on overview to see it).

Supplementary Materials for a Paper

A paper on the theory in Yun Ju Sung's thesis, Monte Carlo Likelihood Inference for Missing Data Models (preprint) contained computing examples. Every number in the paper and every plot was taken (by cut-and-paste, I must admit) from a supplementary materials document done in Sweave.

The LaTeX (PDF) shows what one can do. The source file (examples.Rnw) shows how to do it.

An Issue with Sweave.sty

In recent versions of R the way to run Sweave from the command line

    R CMD Sweave foo.Rnw
    latex foo
    latex foo

(or pdflatex instead of latex) no longer works unless you have the line

    export SWEAVE_STYLEPATH_DEFAULT="TRUE"

in your .bashrc file. Then it does work.

Also the following works without this environment variable set. Inside R do

    Sweave("foo.Rnw")
    library(tools)
    texi2dvi("foo.tex")

with the latter replaced by

    texi2dvi("foo.tex", pdf = TRUE)

if you want PDF rather than DVI output. By the way, the texi2dvi command automagically runs latex or pdflatex multiple times until all the cross references are right.