Reproducible electronic documents
Matt Schwab and Jon Claerbout
SEP's Reproducible Electronic Documents transfer
technology developed by its researchers to
fellow scientists in a highly reusable fashion.
A Reproducible Electronic Document contains
a collection of files and a command generator make (UNIX).
For any document the command "make burn" removes the document's
results and the command "make build" regenerates them
from the files contained in the document.
Universal rules for reproducible documents
- The White Paper (postscript)
explains reproducible electronic documents
and is submitted to Computer in Physics (CIP).
This article is the best introduction to reproducible documents.
- 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
- The SEP documentation (postscript)
discusses the laboratory-specific details of
SEP's reproducible documents.
This article probably interests only readers that are affiliated
- The SEP specific make rules (tar.gz) are an
adaption of the generic reproducibility rules to our laboratory.
If you are not affiliated with SEP you probably want to get the
generic rules mentioned above.
Archive of Reproducible Electronic Documents
Following reproducible documents have been equipped with GNU make
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.
- 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)
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.
- The Idoc article (postscript):
the cake implementation of the reproducibility rules. cake
was replaced by GNU make and is not recommended anymore.
- 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.
Related pointers and topics
In the future we want to deliver
reproducible research on the World Wide Web:
- Jon Claerbout considers a meeting about ways
to use the World Wide Web to distribute
scientific and engineering technology
- 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. PDF (by Adobe) is a
potential replacement for postscript.
- 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
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.