48

I'm planning to start writing R packages.

I thought it would be good to study the source code of existing packages in order to learn the conventions of package construction.

My criteria for good packages to study:

  • Simple statistical/technical ideas: The point is to learn about the mechanics of package construction. Understanding the package should not require detailed highly domain specific knowledge about the actual topic of the package.
  • Simple and conventional coding style: I'm looking for something a bit more than Hello World but not a whole lot more. Idiosyncratic tricks and hacks would be distracting when first learning R packages.
  • Good coding style: The code is well written. It reveals both an understanding of good coding, in general, and an awareness of the conventions of coding in R.

Questions:

  • Which packages would be good to study?
  • Why would the suggested package source code be good to study relative either to the criteria mentioned above or any other criteria that might be relevant?

Update (13/12/2010) Following Dirk's comments I wanted to make it clear that no doubt many packages would be good to study first. I also agree that packages will provide models for different things (e.g., vignettes, S3 classes, S4 classes, unit testing, Roxygen, etc.). Nonetheless, it would be interesting to read concrete suggestions about good packages to start with and the reasons why they would be good packages to start with.

I've also updated the question above to refer to "packages" rather than "package".

Jeromy Anglim
  • 42,044
  • 23
  • 146
  • 250
  • 2
    Another way to look at this is to look for particular package *authors*; certain authors are very good at following best practices and writing clear code, in which case you can study all of their materials. – Shane Dec 15 '10 at 16:52
  • 1
    @Shane Good point. Any suggestions on which package authors might be good to study when first learning to write packages? – Jeromy Anglim Dec 16 '10 at 03:20

5 Answers5

15

I would suggest looking at the zoo package for the following reasons:

  1. It has several well-written vignettes;
  2. It uses a namespace using useDynLib, import, export, and S3method;
  3. It has several unit tests using RUnit;
  4. It provides good examples of how to create/document S3 methods;
  5. It has some calls to C code via the .Call interface;
  6. It contains a (plotting) demo;
  7. It aims to be consistent with the core R installation (e.g. functions behave similarly, it doesn't mask / override base functions, etc.)

It doesn't use roxygen, which is very handy, but 7 out of 8 ain't bad. ;-)

To respond to your criteria:

  1. The concept is simple: zoo is a matrix-like class ordered by something. No domain-specific knowledge necessary.
  2. zoo does seem to have a few idiosyncratic coding conventions, but nothing over-the-top that prevents understanding the code.
  3. zoo aims to be as consistent with R as possible.
Joshua Ulrich
  • 1,376
  • 10
  • 16
9

I do not consider myself an established R package developer but have recently undergone the process of writing and maintaining a package for my work environment.

I had previously been writing / maintaining / updating a set of scripts that I would pass from project to project via the source() function. The end result of this was that I'd end up with mostly redundant scripts hanging out in various places on our network drives. It was never clear where the most up-to-date set of scripts were located. I have since migrated to writing / maintaining a package utilizing roxygen. It has drastically simplified my life and made it easier to share my work with colleagues.

Based on your criteria above, I second the recommendation of reviewing the packages that Hadley has written. In particular, I think reading through the devtools wiki would be very helpful. Hadley's code is well documented and several of his packages utilize roxygen. I think writing and maintaining one document for both R functions and R documentation is much easier than having them split out in two locations (.R and .RD files).

Hadley's packages also serve some fairly basic concepts and are relatively easy to deparse (imho) if you are looking for pointers on the technical aspect ideas. I find myself digging through the plyr source code when I'm looking for a pointer on roxygen documentation or other fundamental tasks.

Chase
  • 3,055
  • 2
  • 19
  • 28
  • Thanks. The devtools wiki, in particular, has lots of great ideas. – Jeromy Anglim Dec 14 '10 at 02:29
  • @Jeromy - Having read your recent posts on reproducible research etc (uber uber helpful so thank you!) means that you'll take to roxygen very quickly. I should have also mentioned that Eclipse supports roxygen syntax and made it a pretty easy transition. The most difficult task I've been overcoming is writing vignettes that are useful and productive. I imagine you're starting from a much higher jumping off point than I am in that regard. – Chase Dec 14 '10 at 02:30
  • 2
    Just don't read the ggplot2 source. It will make your brain bleed – hadley Jan 26 '11 at 02:01
  • what an honest R developer! – Leo5188 Nov 11 '13 at 21:53
7

Why not take an empirically-driven random sampling approach? Just pick a few and see which work for you.

Kidding aside, just look at a few packages you yourself use and are familiar with. Downloading them is easy, or if you prefer you can also view them via a web interface at R-Forge, RForge, or Github.

You will most likely end up with different packages for different ideas. Some may help you with the way they integrate, say, a vignette. Some may help with compiled code. Or unit tests. Or Roxygen. There are about 2600 of them, so why obsess over a single best?

Dirk Eddelbuettel
  • 8,362
  • 2
  • 28
  • 43
  • Great points. I was planning to explore myself. And of course, exploration is half the fun. And I agree different packages teach different things. I agree that many packages would be good starting points. I'll update my question to reflect the idea that multiple packages would satisfy the criteria. But having some concrete suggestions might save myself and others new to R packages some time. I also think that established developers of R packages are in a better position to comment about the merits of a given package for the purposes of learning. – Jeromy Anglim Dec 13 '10 at 03:14
  • 2
    cuz you need to start somewhere :) – hans0l0 Apr 29 '11 at 09:22
2

Another piece of advise might be to look at packages yours will be depending on or interacting with, especially if these implement some items Joshua Ulrich mentioned or have been written by renowned authors. It might be helpful to learn how things are done in your field, to ensure some compatibility. Often people will have thought about certain issues and reading their solution migth be helpful.

Community
  • 1
Laurent
  • 401
  • 3
  • 5
1

i would recommend hadley's reshape package. you can find the source at https://github.com/hadley/reshape

Ramnath
  • 151
  • 4