Create an R package from a single R file with roxyPackage

Documenting code can be a bit of a pain. Yet, the older (and wiser?) I get, the more I realise how important it is. When I was younger I said ‘documentation is for people without talent’. Well, I am clearly loosing my talent, as I sometimes struggle to understand what I programmed years ago. Thus, anything that soothes the pain of writing and maintaining documentation must be good and should help me to better understand my ‘old me’ in the future.

Ideally I want my R code and documentation in as few files as possible. A good start to achieve this is using roxygen2, an R package which has been around for some time. It allows me to tie R code together with the documentation in the same file and helps considerably in maintaining R packages.

The roxyPackage by Meik Michalke goes a step further, building on roxygen2. Meik presented his package at the Cologne R user group meeting a few weeks ago and I was intrigued by it. As I said in my notes to the meeting, with roxyPackage I can create a package from a single file of R code and documentation.

Here is an example of one R file to build a package using roxyPackage. For my toy example I wrote a doughnut plot function in R, something which is clearly missing ;) I took the basic pie chart function and amended it to plot another white disc in the middle. On top of the function code I wrote the help file documentation using the roxygen2 syntax.

In my next step I use roxyPackage to turn this file into its own standalone Doughnut package. Following the roxyPackage vignette I have to pass a data frame with the details of a typical DESCRIPTION file to roxyPackage for it to turn the R file into a package.

The arguments pck.source.dir, R.libs, repo.root specify the folders in which I store my R file, my R libraries and output package respectively.

Job done. After executing the above commands I end up with my package build and installed on my system. Additionally, roxyPackage created binary packages for Windows and Mac in my very own repository (my own little CRAN). In the future I only have to update the version number in the above data frame, rather than DESCRIPTION file, package.Rd help file and NEW/ChangeLog. Fantastic!

Closing remarks

This post is dedicated to my colleagues, who I have pestered with end user computing (EUC) standards over the last months. I believe with roxygen2 and roxyPackage it won’t be too burdensome anymore to comply with those standards.

Indeed, I think roxygen2 and roxyPackage can help novice R users and those who start programming to think a little bit like professional IT guys (I know, I haven’t even mentioned testing or version control yet). Often users just want to get their job done and this is were the above approach can help them to document their work without too much pain.

Session Info

R version 2.15.2 (2012-10-26)
Platform: x86_64-apple-darwin9.8.0/x86_64 (64-bit)

locale:
[1] en_GB.UTF-8/en_GB.UTF-8/en_GB.UTF-8/C/en_GB.UTF-8/en_GB.UTF-8

attached base packages:
[1] tools     stats     graphics  grDevices utils     datasets  methods   base     

other attached packages:
[1] roxyPackage_0.03-1 XiMpLe_0.03-16     roxygen2_2.2.2     digest_0.6.1      

loaded via a namespace (and not attached):
[1] brew_1.0-6    stringr_0.6.2