Reproducible Electronic Documents
Matt Schwab and Jon Claerbout
We give you our system for filing scientific computational research: Reproducible electronic documents. These documents enable you - or anyone with access to your files to handily regenerate your results. Thus your research and your software can be shared and reused. Reproducible electronic documents rely on UNIX makefiles, a few file naming conventions, and a small set of make rules and definitions. Two pages of motivation and summary.
Universal rules for reproducible documents
- The White Paper (postscript) (pdf) explains reproducible electronic documents; it is the best introduction to this concept. It has been published with some editing in Computing in Science & Engineering, Vol. 2, Issue6, Nov.-Dec. 2000, p.61-67 (Making scientific computations reproducible, Schwab, M.; Karrenbach, N.; Claerbout, J.).
- The software package (tar.gz) that accompanies the CIP article contains a complete, reproducible document and a generic set of GNU make rules. Use this package if you plan to test the idea of reproducibility and if you consider adapting it for your purposes.
- Our GNU make (tar.gz) version is a patched copy of the official make-3.74. If you have a GNU make version higher than 3.74, you do not need our patched version.
SEP-specific rules for reproducible documents
If you are not affiliated with SEP you probably want to get the generic rules mentioned above.
Archived reproducible electronic documents
Following reproducible documents have been equipped with GNU make rules:
- About postscript or CD-ROM versions of Jon Claerbout's books on seismic imaging (TDF, BEI, PVI, IEI).
- About PDF or CD-ROM version of SEP sponsor report 89 (not available to the general public)
Schwab tested all of these documents and the reproducibility rules by removing and rebuilding all the documents' figures (276) on three different computers, IBM, HP, and SUN.
A former cake version
In 1995 we abandoned cake and converted to GNU make. Cake had served us well for many years. Since older SEP documents are based on cake, we offer here our former rules and the cake source code.
Related pointers and topics
- With the Xtpanel (by Steve Cole and Dave Nichols) scripting language we easily create graphic user interfaces for our electronic reproducible documents.
- SUN's Java web language could soon enable us to deliver secure software to anyone on the web.
- In SEP's first Java experience Ken Lenga and Bob Clapp created a Java viewer for seismic data, and a Java application that computes a finite-difference operator to the 2-D wave equation. (but they seem to be hiding their stuff during the alpha to beta transition of Java).
- At the PDF at SEP page Christine Ecker outlines her experiences converting SEP's 1995 fall report from LaTeX to PDF format.
- In the Reproducibile Documents, Java, PDF at SEP manuscript Claerbout delivered a short summary of our web activities to our laboratory's sponsors.
Reproducible research elsewhere
If you create reproducible, electronic research documents, please let us know and we will point to your web page.
- At the Wavelet research page, Jonathan Buckheit, Shaobing Chen, David Donoho, Iain Johnstone, and Jeffrey Scargle are delivering reproducible research on the web. They use Matlab. Their reproducible research is not integrated with its documentation like ours is.
- In France, at Ecole Polytechnique Federale de Lausanne at the Audiovisual Communications Laboratory, they also do reproducible research
Invited Paper SEG 1992
J. Claerbout, “Electronic documents give reproducible research a new meaning,” in Proc. 62nd Ann. Int. Meeting of the Soc. of Exploration Geophysics, 1992, pp. 601–604. [Online]. (postscript)(html)