Reproducible electronic documents

Matthias Schwab, Martin Karrenbach, and Jon Claerbout

matt@sep.Stanford.EDU, martin@sep.Stanford.EDU, jon@sep.Stanford.EDU

ABSTRACT

To organize computational scientific research and hence to conveniently transfer our technology, we impose a simple filing discipline on the authors in our laboratory. A document's makefile includes laboratory-wide standard rules that offer readers these four standard commands: make burn removes the document's result figures, make build recomputes them, make view displays the figures, and make clean removes any intermediate files. Although we developed these standards to aid readers we discovered that authors are often the principal beneficiaries.

In the mid 1980's, researchers at our laboratory noticed that a few months after completing a project, the researchers were usually unable to reproduce their own computational work without considerable agony. In 1991, the concept of electronic documents solved this problem by making scientific computations reproducible. Since then Jon Claerbout, Martin Karrenbach, Joel Schroeder, and I developed electronic reproducible documents to our laboratory's principal means of technology transfer of scientific computational research. A small set of standard commands makes a document's results and their reproduction readily accessible to any reader. To implement reproducible computational research the author must use makefiles, adhere to a community's naming conventions, and reuse (include) the community's common building and cleaning rules. Since electronic reproducible documents are an easily maintained, reusable software portfolio, not only the reader but also the author benefits from reproducible documents.