Guidelines for Developers of R Packages Interfacing with Stan

Stan Development Team

2016-12-19

Note to developers

One of the coolest things about working on a project like Stan has been seeing some of our users begin to develop tools for making Stan more accessible to audiences that may otherwise not benefit from what Stan offers. In particular, recently we have started seeing a growing number of R packages that provide high-level interfaces to Stan, using the rstan package for estimating models without requiring that the user be familiar with the Stan modeling language itself.

This is a great development and we would like to support such efforts going forward, but to-date we have made little effort to coordinate the development of these packages. To avoid a Wild West, so to speak, of Stan-based R packages, we think it is important that developers make every effort to adhere to certain guidelines in order to ensure these packages are of the highest possible quality and provide the best possible experience for users. To that end, in this post we present a set of recommendations for the development of R packages that interface with Stan. These recommendations are based on software design principles we value as well as many things we are learning as we continue developing our rstanarm package and review packages being developed by others.

Of course anyone is free to develop a package based on Stan, even if they ignore these recommendations. However, both because we feel strongly about these recommendations and because we are seeing an increase in the number of requests for help (and our time is unfortunately limited), we will loosely enforce these guidelines by

  1. prioritizing giving feedback to developers who follow them over those who choose not to, and
  2. refraining from promoting packages that ignore them.

That said, we are open to some limited exceptions (e.g., the brms package is a sanctioned exception to one of guidelines about Stan code). If you think your package should be an exception definitely let us know.

Guidelines for R packages providing interfaces to Stan

General package structure and development

Stan code

R code and documentation

Concluding remarks

These guidelines are not set in stone. We expect them to evolve and we very much appreciate feedback on how they can be improved. And, of course, we look forward to seeing the packages you develop using Stan!

– The Stan Development Team