makeR: An R Package for Managing Document Building and Versioning

If you are reading this vis-à-vis R-Bloggers, then you know how good R, LaTeX, and Sweave are for generating reports and/or conducting reproducible research. It has been particularly valuable for me in Institutional Research where there are many reports that I need to prepare on a regular basis (some monthly, some quarterly, some annually). However, one issue I have had is how to do I track these different reports. I have tried manual processes such as copying and pasting R scripts to more automated approaches such as GNU Make. Though the latter is a robust system, I have had two issues with it recently, namely it is more complex and it requires access to the shell. My goal is to manage the documents entirely in R because our office is moving to using RStudio Server which means we don’t have access to the shell. The makeR package is my attempt to solve this problem.

I should start by stating what the makeR package IS NOT. It is not a system for package development, use devtools for that. It is also not really meant to handle very complex research projects, use ProjectTemplate for that. Instead, makeR attempts to solve the problem of generating a series of documents that are the same with the exception of easily extractable variables. The package provides methods for handling LaTeX, Sweave, cacheSweave, and knitr documents. The package vignette describes how to create custom builders including one for R script files that generate PNG files. I have reduced the build process to four R statements:

1. Create or load a project. The package uses an XML file to store project information.
2. Add a new version.
3. Build the version.
4. Release the version

By default, a project will have three directories: source, build, and release. Upon each build, source files are copied from the source directory to a subdirectory named build. A builder function will then execute the appropriate code. Execution occurs (by default) in a separate R environment, saves output to a log file, and will also save the R environment to the build directory to assist with debugging. Releasing will copy the built file(s) to the release directory renaming the files to include the version information (i.e. version name/number and minor version number).

Version 1.0 has been released to CRAN. The package vignette contains more detail. There are also three demos

1. rbloggers demonstrates a simple Sweave (Rnw) document that summarizes posts within a particular month to the R-Bloggers site.
2. stocks shows how to use an R script file that generates PNG files as output.
3. makeR-knitr shows how to use the knitr package for document building.

makeR is hosted on Github and there is a project page with more documentation at jbryer.github.com/makeR.