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)
(html)
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.
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.
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
© 2005
, Stanford Exploration Project
Modified: 12/08/05, 08:21:39 PST
, by jon
Page Maintainer: webmaster `AT' sep.stanford.edu