Why and when create a R package?

Question

I understand this question is quite a broad one, but I wonder what should be the decisive points in deciding to create (or not) a new package for R. To be more specific, I would add that the question is not about the reasons to use R in itself, more about the decision to compile various scripts and to integrate them in a new package.

Amongst the points that could lead to these decisions, I have thought of (in a quite non-exhaustive fashion), of :

• the non-existence of other packages in the same sub-field ;
• the need for exchanging with other researchers and allowing reproducibility of experiments ;

And amongst the points that could lead to a contrary decision :

• part of the methods used already present in some other packages;
• number of new functions not sufficient to justify to create a new independent package.

I might have forgotten many points that could go in either list, and also, these criteria seem partly subjective. So, what would you say should justify, and at which point, to start bringing together various functions and data in a new documented and broadly available package ?

Answer 1

I don't program in R, but I program otherwise, and I see no R-specific issue here.

I imagine that most people first write something because they really want it for themselves. Conversely, any feeling that one should be publishing software because it is the thing to do should be resisted strongly. Smart people can be lousy programmers, and often are.

Going public seems a matter of being confident that you have something that is as good or better than what is already public and fills a gap. Knowing that other people want to do the same thing is surely a boost.

If you are in doubt, don't publish. In many communities, there is a quality control problem of mediocre or buggy software released by uncritical or inexperienced programmers, although how bad the problem is remains open to debate. Optimists feel that trivia can just be ignored and that users will expose bugs and limitations fast enough; pessimists feel that we are drowning in poor quality stuff and it's hard to tell the winners from the losers. (On the other hand, the experience gained from publication is part of what allows programmers to improve.)

There could be a book on this, but a few pointers spring to mind:

1. Good quality documentation distinguishes good software as well as good code, indeed sometimes more obviously. Never underestimate how much work will be needed to provide the documentation that the code deserves. R programmers often seem to require that R users know just as much they do about the technique being implemented and document minimally....

2. As far as possible, test your code so that you can reproduce published solutions with real data from elsewhere. (If you are coding up something totally new, that may be more difficult, but not impossible. Also, you may often find yourself wondering whether it's their bug or yours.)

3. Programmers often underestimate the ability of users to throw unsuitable data at a program. So, think about what could go wrong, e.g. with missing values, zeros if a program assumes positive, etc., etc. (The benign take here is that it's the job of the users to find the problems and improve the code through their feedback, but a program that breaks down easily won't enhance your reputation.)

Answer 2

This is an important and practical question. Let's start by distinguishing between writing a package and publishing it on CRAN.

Reasons not to write a package:

• Cost efficiency.
• Lack of experience.

Reasons to write an R package:

• Sharing with people and platforms.
• Forces a tidy code and work process.
• Ease of use (even for self) when functions start accumulating.

Reasons to submit a package (CRAN, Bioconductor,...):

• Contribution to the community.
• Ease of distribution.

Answer 3

Remember that there is option #3; you may ask the maintainer of a relevant package to include your code or data.

Answer 4

My personal triggers for packaging are:

• I find I'm again using some code that I once wrote for another data analysis project.
• I think I'll need the method I just wrote again.

• A colleague asks me for code. A substantial part of the code I write is at least as much on request of colleagues (who use R but do not program that much themselves) as for myself.

• I use the formal requirements of a package (documentation) to "force" me clean up and document my code.

I agree with @JohnRos that there is quite a difference between writing a package and publishing the package.

• I usually package early, but then make the package only "semipublic". That is, it may be available on an internal server (or on r-forge), so my colleagues can access the package. But I publish to CRAN only after the package has been used for months or even a few years by close colleagues. This doesn't bring up all bugs according to @Nick Cox's point #3, but a fair amount of them.
  The versions of the package (I put the date after the dash in the version number) make it easy to fix things ("to do this and that, make sure you intall at least last week's version")

• According to my working contract, my employer has the last word on the decision whether and how a package can be published to the outside world.

The thing where I do not yet have a good strategy for packaging is data.

---

Comments to your list of reasons:

• the non-existence of other packages in the same sub-field ;

Not finding a package that does what I need for me triggers writing the code, but it doesn't have to do with the decision whether to package or not.

• the need for exchanging with other researchers and allowing reproducibility of experiments ;

Definitively. Possibly already the need to share between several computers I use.

And amongst the points that could lead to a contrary decision :

• part of the methods used already present in some other packages;

you could import those methods into your package/code: this is a point against writing such code, but has only indirectly to do with packaging.

• number of new functions not sufficient to justify to create a new independent package.

For me, there is no minimum number of functions to start a package. In my experience packages tend to grow "automatically". On the contrary, after I've found myself a few times branching off a new package out of another (because e.g. some helper functions in the end turned out to be thematically different and useful in other situations, too), I'm now rather creating new packages immediately.

Also, if you didn't write documentation and tests, this can be a prohibitive amount of work when a "sufficient" number of functions for creating a package did accumulate.
(If you do write them immediately, then the additional effort of putting it into a package is negligible once you know the workflow).

Answer 5

I'd say create a package whenever you are doing a large enough set of similar tasks in R that you would benefit from a package in which you can put things in a namespace (to avoid conflicts with similarly named functions), where you can write documentation. I even have a package on github for bundling up a grab bag of functions that aren't related, but I use so often that I thought they deserved documentation, man files, etc.

Another use case could be when submitting a paper, if you have a number of functions you could easily create a package, including documentation for those functions, examples for each function, and a tutorial on how to use it. And you don't need to put it on CRAN, as said in above answers. This could be awesome for reproducibility.

Three tools I'd say are important:

• devtools pkg, to make it super easy to build packages (also see the wiki on the devtools github pages
• roxygen2 pkg, to make writing documentation for your package easy
• GitHub, You can use install_github (or similarly install_bitbucket, etc.) to install directly from GitHub, which is nice for sharing with others.

Answer 6

I agree with everything I read so far. All those reasons are good programming practice and do not apply to R in particular. However I find myself writing R packages most of the time, and for yet another reason. So I will add:

R-specific reason to write an R package:

• because you write in C

Any time you use foreign languages such as C, C++ or FORTRAN (mostly for high performance computing), writing a package is largely worth the trouble. If you have more than one or two functions, you rapidly end up with files all over the place and dependencies between the R and C code that is difficult to maintain and to port.

Answer 7

One reason not mentioned in the other excellent answers: You have a large or complex data analysis project. Packaging, first, the data as a package, and then extending with useful functions to transform, plot, or compute specific analyses. This way you get a documented version of the data complete with all the functions used to compute the reported analysis. Then the report(s) from the project can be written using knitr or other packages for reproducible research!

This could significantly save time if some reanalysis has to be done, or it could even be published (or semipublished) if the analysis are published.