28
votes
$\begingroup$

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 ?

$\endgroup$
17
votes
$\begingroup$

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.)

$\endgroup$
7
  • 1
    $\begingroup$ I couldn't agree more with these three points (though point 2 would not apply in my particular case, since I designed the method in question). The third point is a very important one, and more generally raises the issue of the level of information that one can expect of the user (or: for who do we release a package) : should we only code for specialists of the field, familiar with the method at hand, or try to make our package usable by interested scholars that haven't read all related articles ? $\endgroup$
    – Jean-Baptiste Camps
    May 14 '13 at 13:09
  • 2
    $\begingroup$ #2 always applies as far as "test your code"! Different people have different styles on the last point, and there's no right answer. You could take the line that it's not a programmer's job to explain what is well explained elsewhere, or futile to document a program except by explaining use. In the Stata community, where I am active, good documentation seems widely appreciated and its lack is a concern, but the R community must have its own mores. $\endgroup$
    – Nick Cox
    May 14 '13 at 13:17
  • $\begingroup$ about telling winners from losers and your very valid points: #1: fortunately, there are some points in R one can easily check, and which point towards better documentation than just the formal required help pages. Is a vignette provided (sos::findFn finds this criterion important enough to put this info into the result table!)? A demo? A web page with more information? Does citation give a proper paper or book #2 you may ship example data with your code, so even if there is no other implementation you can test your code against, now others can test their implementation against yours. $\endgroup$
    – cbeleites unhappy with SX
    May 14 '13 at 15:33
  • 1
    $\begingroup$ "R programmers often seem to require that R users know just as much they do about the technique being implemented and document minimally...." - It is important to distinguish the documentation of the code vs the statistical method. R documentation is absolutely not the place to learn stat methods. Even vignettes assume a certain level of sophistication. Too many complaints about minimal documentation in R really amount to complaining that the docs aren't spoon feeding them statistical knowledge. $\endgroup$
    – joran
    May 14 '13 at 20:58
  • 2
    $\begingroup$ The ellipsis ... was intended to signal a wry aside. It's for the R community to set its own standards, or at least to debate them. $\endgroup$
    – Nick Cox
    May 14 '13 at 21:57
14
votes
$\begingroup$

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.
$\endgroup$
3
  • 7
    $\begingroup$ I'd add that lack of experience is also a reason to write an R package. Writing a package for the first time is not only fun and a challenge, but it actually helps one formulate ideas about how to design a 'proper' package that will be useful to oneself and the community. In other words, even if one lacks experience, it's still a good idea to write a package in order to get experience in doing it. $\endgroup$
    – Graeme Walsh
    May 14 '13 at 12:01
  • 1
    $\begingroup$ Your view, Grame, is a quite motivating one for a not-so-experienced R programmer that would hesitate to go into designing a package. On the other hand, though it would very certainly be fulfilling for oneself, I note that both answer emphasize (and I can understand that as well) the programming and scientific need for a clean, efficient and above else error-free code. So, that opens a new question that could be "How to make sure an R package is free of errors ?", supposedly the job of the community, but the increasing number of new packages can be a limit to that. $\endgroup$
    – Jean-Baptiste Camps
    May 14 '13 at 13:03
  • $\begingroup$ This definitely comes back to your point that there is quite a difference between writing a package (say, to gain experience) and actually taking the next step and publishing the package. cbeleites tells us that he makes his packages "semi-public" and I think his approach contains elements of how to make sure that an R package is free of errors (or rather, that the possibility of errors are minimized). Essentially, some sort of peer-review or testing phase is one way to help ensure that R packages are of good quality. If too many packages spring up without review they may not be so useful. $\endgroup$
    – Graeme Walsh
    May 18 '13 at 15:46
12
votes
$\begingroup$

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

$\endgroup$
8
votes
$\begingroup$

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).

$\endgroup$
1
  • 3
    $\begingroup$ +1. Another good way to make packages semi-public is to put the package source up on GitHub - it makes the code easier to find and encourages others to contribute without the implicit polish of a package on CRAN. $\endgroup$
    – Matt Parker
    May 21 '13 at 16:51
7
votes
$\begingroup$

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.
$\endgroup$
5
votes
$\begingroup$

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.

$\endgroup$
0
votes
$\begingroup$

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.

$\endgroup$

Not the answer you're looking for? Browse other questions tagged or ask your own question.