Most R users have downloaded and used packages from CRAN to extend R's capabilities. But relatively few have created packages themselves. The official reference documentation, Writing R Extensions, can be daunting, but creating a package is actually easier than you might think. Even if you don't plan to submit a package to CRAN, organizing your own work into packages confers a number of benefits:
- Packages offer a well-defined structure for organizing R source code, data, and documentation which makes for excellent best practice to compartmentalize and organize your work.
- The file-based structure of packages makes it easy to manage your work within source-code control systems, for security against losses and access to historical versions.
- The packaging system has tools for software validation which check that documentation exists and is technically in sync with the code, can spot common errors, and checks that examples actually run.
If you do plan to submit to CRAN, creating a package is a pre-requisite. But even if you're just sharing code with others, the package format is an ideal vehicle for distributing statistical methodology to others. For the recipient of your package, there are the following benefits:
- The validity of the package contents can be assured by running the automated tests.
- Packages can be dynamically loaded and unloaded at run-time and hence only occupy memory when actually used.
- Installations and updates are fully automated and can be executed from inside or outside R.
Freidrich Leisch, R-core member and manager of CRAN, has written an excellent tutorial (PDF) which takes you step-by-step through the process of creating your first package. It runs through a worked example of creating a package for linear regression (and incidentally also serves as a concise tutorial for writing method functions for a user-defined S3 class). It shows how to create the R source files, how to write help-files, and how to create and run tests on your package, and how to structure the package itself.
If you've been thinking about writing a package, or just need to organize your R code better, this is an excellent place to start.
[Update Sep 25 2013: The tutorial is now part of the contributed documentation for R, and the link below has been updated.]
R-project contributed documentation: Freidrich Leisch (2008): Creating R Packages: A Tutorial
For More R Tutorials, Check Out Revolution Analytics R Training.
Perhaps one of the greatest benefits of writing an R package is encapsulation. Without using R packages it's very difficult to create namespaces in R (without hackery). I'm still a bit unhappy with the .Rd format of documentation for R. I tend to use comments in my code as per the google doc standards, but find that writing Rd files for my own personal use is unnecessary.
'R CMD check' is slow and usually checks for things that one doesn't necessarily care about if a package is not being submitted to CRAN, ie. Rd formatting.
I've written a simple python script that uses the RUnit package and tests defined in a inst/tests/suites.R file. I can send it to you if you'd like
Posted by: ephpostfacto | August 28, 2009 at 06:24
Tutorial concept explained with useful ideas and interesting guidelines.
Posted by: Cosmetic Dentist Blackpool | September 08, 2009 at 05:18
Hi,
The link to the tutorial is now broken. As of 2013.09.25, it is http://cran.r-project.org/doc/contrib/Leisch-CreatingPackages.pdf
Posted by: Doug Morse | September 25, 2013 at 14:40
@Doug, thanks -- I have updated the post.
Posted by: David Smith | September 25, 2013 at 14:57
Hi David,
The link in the post still isn't updated/functioning. Doug's link works fine though :)
Cyrille
Posted by: Cyrille MdC | October 07, 2013 at 02:38
@Cyrille, the link should work now -- thanks.
Posted by: David Smith | October 08, 2013 at 11:26