Effort required by the author: an example

The reader interface demands minimal effort from the author. At our laboratory,an author merely supplies the application-specific rules, while the community's ReDoc rules contain all definitions that are not application-specific. The author's definitions have to conform to the community's naming conventions, so that the author's application-specific rules can be invoked by the universal ReDoc rules.

The author of a reproducible document lists each result file as either easily, conditionally, or non-reproducible. For every easily or conditionally reproducible result, the author supplies a rule that generates the result file. Furthermore, the author specifies a cleaning rule that removes the intermediate files. The ReDoc rules offer the author a comprehensive default cleaning rule, jclean.

Since the author's rules deal with the document's application, the effort required of an author is best illustrated by an example. The electronic version of this article is accompanied by a subdirectory called Frog. Frog contains a complete albeit small reproducible electronic document about a finite-difference approximation of the 2-D surface waves caused by a frog hopping around a rectangular pond. Figure 2 shows the Frog example as a reader would find it on our CD-ROMs.

 

xtpanelHor
Figure 2 Online version of a reproducible electronic document. The reader interface for reproducible research is only one component of SEP's current computational research environment: A research document at SEP (visible in the background to the left) is written in L^ATEX. Using SEP's own L^ATEX macros, a push-button in each figure caption invokes a graphic user interface. The graphic user interface enables a reader to interactively execute the burn, build, clean, and view commands for each individual figure. (The panel is shown in the foreground. The result of make view is shown towards the right.) SEP's GNU make rules allow an author to extend the interactivity of a result figure easily to additional, application-specific actions. Unfortunately, these features are beyond the scope of this article. We distribute our software and the theses of our research group on World Wide Web.

The actual electronic document comprises a directory with a few files. The short traditional scientific article that describes the implementation of the finite-difference approximation of the wave equation is available in three formats: L^ATEX, PostScript, and HTML. Some RATFOR files implement the 2-D wave propagation code. The Fig directory contains the result files: a figure (postscript and gif version) of the pond after some wild hops by the frog and the output (two float numbers) of a dot-product test of the linear finite-difference operator and its adjoint. To organize the document's files, the author of the Frog example wrote the following makefile:

 

SEPINC = ../rules
include ${SEPINC}/Doc.defs.top

RESULTSER = frog dot

col = 0.,0.,0.-1.,1.,1.
${RESDIR}/frog.ps ${RESDIR}/frog.gif: frog.x
	frog.x                   > junk.pgm
	pgmtoppm ${col} junk.pgm > junk.ppm
	ppmtogif        junk.ppm > ${RESDIR}/frog.gif
	pnmtops         junk.pgm > ${RESDIR}/frog.ps

objs = 	copy.o adjnull.o rand01.o wavecat.o  	pressure.o velocity.o viscosity.o wavesteps.o
frog.x: ${objs}

dot.build ${RESDIR}/dot.txt : dot.x
	dot.x dummy > ${RESDIR}/dot.txt
dot.view: ${RESDIR}/dot.txt
	cat ${RESDIR}/dot.txt
dot.burn: 
	rm ${RESDIR}/dot.txt

dot.x : ${objs}

clean: jclean

include ${SEPINC}/Doc.rules.red
include ${SEPINC}/Doc.rules.idoc
include ${SEPINC}/Prg.rules.std

The variable RESULTSER contains the list of the document's easily reproducible results, frog and dot.

The next rule contains the commands to build the postscript and gif version of the frog result. Such a rule is application-specific and cannot be supplied by included default rules. The target names comprise the directory RESDIR, in which the result files reside, and file suffixes (.ps, .gif), which indicate the files' formats. The rule depends on an executable frog.x, which it executes during the computations of the result.

Default rules for compilation and linking of executables such as frog.x are supplied by a shared include file, Prg.rules.std. The dependency of the executable on its subroutine object files, as in the case of frog.x, needs to be defined by the author of the makefile, since it depends on the application-specific file names.

In the case of the dot result file, the rules supplied by the author reflect the commands of the reader interface: dot.build creates the result file, dot.view displays it, and dot.burn removes it.

Finally, the target clean invokes the included default target jclean. The targets remove intermediate files based on our laboratory's naming conventions.