This is an old revision of the document!

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) (tar.Z) 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) (tar.Z) 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.

  • The SEP make rules for online inspection.
  • The SEP-specific documentation (postscript).
  • The SEP-specific make rules (tar.gz) (tar.Z) for convenient downloading.
  • The cake2make (perl) helps translating old SEP cakefiles to makefiles.

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.

Since 1992 SEP produced reproducible documents using the make dialect cake:

  • SEP's List of CD-ROMs contains all the reproducible electronic documents SEP has put on CD-ROM. The CD-ROMs are sent to our laboratory's sponsors and some are available to the public.
  • A Promotional blurb about reproducible electronic documents was prepared by Claerbout, after publishing his first reproducible document in 1992.
  • At their 1992 SEG presentation , Claerbout and Karrenbach defined reproducible research for the 1992 Society of Exploration Geophysics meeting.
  • Their disappointment with CD-ROM technology led Claerbout, Schwab, and Karrenbach to look forward to the evolution of the web.

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.

  • The Idoc article (postscript) describes the cake implementation of the reproducibility rules.
  • SEP's former cake rules (tar.gz) (tar.Z) are now not used anymore.
  • The cake source code(tar.gz) (tar.Z) contains the files necessary to install cake on your system.
  • Mr Somogyi wrote cake before GNU make existed.

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

Envited 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]. Available:

/web/html/data/attic/sep/research/reproducible.1228947723.txt.gz · Last modified: 2015/05/26 22:40 (external edit) Creative Commons License Valid CSS Driven by DokuWiki do yourself a favour and use a real browser - get firefox!! Recent changes RSS feed Valid XHTML 1.0