16 CONTRIBUTED RESEARCH ARTICLES Implementing the Compendium Concept with

This article suggests an implementation of the compendium concept by combining Sweave and the LATEX literate programming environment DOCSTRIP.


Introduction
introduced compendiums as a mechanism to combine text, data, and auxiliary software into a distributable and executable unit, in order to achieve reproducible research1 : ". . .research papers with accompanying software tools that allow the reader to directly reproduce the result and employ the methods that are presented . . ." Gentleman and Lang (2007, (abstract)) Gentleman (2005) provides an example of how the compendium concept can be implemented.The core of the implementation is a Sweave2 source file.This source file is then packaged together with data and auxiliary software as an R package.
In this article I suggest an alternative implementation of the compendium concept combining Sweave with DOCSTRIP.The latter is the L A T E X literate programming environment used in package documentation and as an installation tool. 3DOCSTRIP has previously been mentioned in the context of reproducible research, but then mainly as a hard to use alternative to Sweave. 4 Here, instead, DOCSTRIP and Sweave are combined.
Apart from the possibility to enjoy the functionality of Sweave and packages such as xtable etc the main additional advantages are that • in many applications almost all code and data can be kept in a single source file, • multiple documents (i.e., PDF files) can share the same Sweave code chunks.This means not only that administration of an empirical project is facilitated but also that it becomes easier to achieve reproducible research.Since DOCSTRIP is a part of every L A T E X installation a Sweave user need not install any additional software.Finally, Sweave and DOCSTRIP can be combined to produce more complex projects such as R packages.
One example of the suggested implemention will be given.It contains R code common to more than one document; an article containing the advertisement of the research (using the terminology of Buckheit and  Donoho (1995)), and one technical documentation of the same research.In the following I assume that the details of Sweave are known to the readers of the R Journal.The rest of the article will (i) give a brief introduction to DOCSTRIP, (ii) present and comment the example and (iii) close with some final remarks.

DOCSTRIP
Suppose we have a source file the entire or partial content of which should be tangled into one or more result files.In order to determine which part of the source file that should be tangled into a certain result file (i) the content of the source file is tagged with none, one or more tags (tag-lists) and (ii) the various tag-lists are associated with the result files in a DOCSTRIP "installation" file.
There are several ways to tag parts of the source file: • A single line: Start the line with '%<tag-list>'.
• Several lines, for instance one or more code or text chunks in Sweave terminology: On a single line before the first line of the chunk enter the start tag '%<*tag-list>' and on a single line after the last line of the chunk the end tag '%</tag-list>'.• All lines: Lines that should be in all result files are left untagged.'tag-list' is a list of tags combined with the Boolean operators '|' (logical or), '&' (logical and) and '!' (logical negation).A frequent type of list would be, say, 'tag1|tag2|tag3' which will tangle the tagged material whenever 'tag1', 'tag2' or 'tag3' is called for into the result files these tags are associated with.The initial '%' of the tags must be in the file's first column or else the tag will not be recognised as a DOCSTRIP tag.Also, tags must be matched so a start tag with 'tag-list' must be closed by an end tag with 'tag-list'.This resembles the syntax of L A T E X environments rather than the Sweave syntax, where the end of a code or text chunk is indicated by the beginning of the next text or code chunk.Note also that tags cannot be nested. 5he following source file ('docex.txt')exemplifies all three types of tags: Line 1 loads DOCSTRIP.Lines 2 − 5 contain options that basically tell DOCSTRIP not to issue any messages, to write over any existing result files and not to mess up the result files with pre-and post-ambles. 6The action takes place on lines 6 − 9 within the command '\generate{}', where lines 7 − 8 associate the tags 'file1' and 'file2' in the source file 'docex.txt'with the result files 'file1.txt' and 'file2.txt'. 7 We name this file 'docex.ins',where '.ins' is the conventional extension for DOCSTRIP installation files.DOCSTRIP is then invoked with latex docex.insA log-file called 'docex.log' is created from which we here show the most important parts (lines 56 − 67): Generating file(s) ./file1.txt ./file2.txt \openout0 = `./file1.txt'.We see that two result files are created from the 15 lines of code in the source file.First 'file1.txt'; 1 This line begins both files.Note that some lines are blank in both the original source file and the result files.Disregarding these the two result files together have 8 lines of code.The untagged material in lines 7 − 9 in the source files is tangled into both result files, the blank lines 7 and 8 in the source file result in the blank lines 5 and 7 in 'file1.txt'and the blank lines 2 and 4 in 'file2.txt'.

Example
In the following a simple example will be given of how DOCSTRIP can be combined with Sweave to implement the compendium concept.The starting point is a "research problem" which involves loading some data into R, preprocessing the data, conducting an estimation and presenting the result.The purpose is to construct a single compendium source file which contains the code used to create (i) an "article" PDFfile which will provide a brief account of the test and (ii) a "technical documentation" PDF-file which gives a more detailed description of loading and preprocessing data and the estimation.The source file also contains the code of a BibT E X databse file and the DOCSTRIP installation file.Although this source file is neither a L A T E X file or a Sweave file I will use the extension '.rnw' since it first run through Sweave.Here we simplify the example by using data from an R package, but if the data set is not too large it could be a part of the source file.
We can think of the "article" as the "advertisement" intended for journal publication and the "technical documentation" as a more complete account of the actual research intended to be available on (say) a web place.However, tables, graphs and individual statistics should originate from the same R code so whenever Sweave is executed these are updated in both documents.There may also be common text chunks and when they are changed in the source file, both documents are updated via the result files.
The example code in the file 'example_source.rnw' is as follows: The compendium source file contains the following DOCSTRIP tags (for their association to files, see below): • 'article' associated with 'example_article.tex',which contains the code to the "advertisement" article, • 'techdoc' associated with 'example_techdoc.tex',which contains the code to the technical documentation, • 'bib' associated with 'example.bib'which contains the code to the BibT E X data base file, • 'dump' associated with no file.Note that the tags 'article' and 'techdoc' overlap with eachother but not with 'bib' and 'dump', which in turn are mutually exclusive.There is no untagged material.
Lines 2 − 15 contain general information about the distributed project, which could be more or less elaborate.Here it just states that the project is distributed as a single source file and how the compendium source file should be processed to get the relevant output This note replicates the Kleiber and Zeileis [2008, p. 56ff] estimation of a price per citation elasticity of library subscriptions for economics journals equal to −0.53.The data set includes the number of library subscriptions (Si), the number of citations (Ci) and the subscription price for libraries (Pi).We want to estimate the model where Pi/Ci is the price per citation.The result with OLS standard errors is in Table 1 'example_article.pdf'and 'example_techdoc.pdf'.When the instructions are followed, Sweave is run first on 'example_source.rnw'creating the file 'example_source.tex', in which the Sweave code chunks are replaced by the corresponding R output code wrapped with L A T E X typesetting commands.One of the R functions used in this Sweave session is writeLines() (see the lines 80 − 96) so that the DOCSTRIP installation file 'example.ins' is created before DOCSTRIP is run.
This file 'example_source.tex' is the DOCSTRIP source file from which the DOCSTRIP utility, together with the installation file 'example.ins',creates the result files 'example_article.tex','example_techdoc.tex'and 'example.bib'.The two first result files share some but not all code from the DOCSTRIP source file.The result files are then run with the L A T E X family of software (here pdflatex and BibT E X) to create two PDF-files 'example_article.pdf' and 'example_techdoc.pdf'.These are shown in Figures 1-2.
Note that the entire bibliography (BibT E X) file is included on lines 73 − 77 and extracted with DOCSTRIP.Note also on line 73 that unless the @ indicating a new bibliographical entry is not in column 1 it is mixed up by Sweave as a new text chunk and will be removed, with errors as the result when BibT E X is run. 8he bibliography database file is common to both 'example_article.tex'and 'example_techdoc.tex'.Here the documents have the same single reference.But in real implementations bibliographies would probably not overlap completely.This way handling references is then preferable since all bibliographical references occur only once in the source file. 9n LaTeX cross references are handled by writing information to the auxiliary file, which is read by later L A T E X runs.This handles references to an object located both before and after the reference in the L A T E X file.In Sweave '' can be used to refer to R objects created before but not after the reference is made.This is not exemplified here.But since Sweave and L A T E X are run sequentially an object can be created by R, written to a file (see the code chunk on lines 65 − 67) and then be used in the L A T E X run with the command '\input{}' (see code line 29).

Final comments
By making use of combinations of DOCSTRIP and (say) 'writeLines()' and by changing the order in which Sweave and DOCSTRIP are executed the applications can be made more complex.Such examples may be found Lundholm (2010a,b).10Also, the use of DOCSTRIP can facilitate the creation of R packages as exemplified by the R data package sifds available on CRAN (Lundholm, 2010c).Another type of example would be teaching material, where this article may itself serve as an example.Apart from the DOCSTRIP

M. Lundholm September 15, 2010
This note replicates the Kleiber and Zeileis [2008, p. 56ff] estimation of a price per citation elasticity of library subscriptions for economics journals equal to −0.53.The data, available in R package AER on CRAN, is loaded: > data("Journals", package = "AER") The data set includes the number of library subscriptions (Si), the number of citations (Ci) and the subscription price for libraries (Pi).We want to estimate the model log(Si) = α0 + α1 log (Pi/Ci) + i, where Pi/Ci is the price per citation.We the define the price per citation, include the variable in the data frame Journals > Journals$citeprice <-Journals$price/Journals$citations and estimate the model: > result <-lm(log(subs) ~log(citeprice), data = Journals) The result with OLS standard errors is in Table 1

2368
This is the text that should be included in file1 4 5 This is the text to be included in both files 7 Also text for both files.and'file2.txt';1This line begins both files.

235
This is the text to be included in both files4 This is the text that should be included in file2 6 Also text for both files.

The
For instance, line 1 is a single line tagged 'file1' or 'file2', line 2 starts and line 6 ends a tag 'file1' and line 13 starts and line 15 ends a tag 'file1' or 'file2'.Lines 7 − 9 are untagged.The next step is to construct a DOCSTRIP installation file which associates each tag with one or more result files: .

Table 1 :
. Estimation resultsReferencesC.Kleiber and A. Zeileis.Applied Econometrics with R. Springer, 2008.file and a Bash script file all code used to produce this article is contained in a single source file.The Bash script, together with DOCSTRIP, creates all example files including the final PDF-files; that is, all example code is executed every time this article is updated.So, if the examples are changed an update of the article via the Bash script also updates the final PDF-files in Figures1-2. 11lophoneThis article was written on a i486-pc-linux-gnu platform using R version 2.11.1 (2010-05-31), L A T E X2 ε (2005/12/01) and DOCSTRIP 2.5d (2005/07/29).