rstan_create_package() function helps get you started developing a
new R package that interfaces with Stan via the rstan package. First
the basic package structure is set up via
Then several adjustments are made so the package can include Stan programs
that can be built into binary versions (i.e., pre-compiled Stan C++ code).
The Details section below describes the process and the See Also section provides links to recommendations for developers and a step-by-step walk-through.
As of version
2.0.0 of rstantools the
rstan_package_skeleton() function is defunct and only
rstan_create_package() is supported.
rstan_create_package( path, fields = NULL, rstudio = TRUE, open = TRUE, stan_files = character(), roxygen = TRUE, travis = FALSE, license = TRUE, auto_config = TRUE )
The path to the new package to be created (terminating in the package name).
|fields, rstudio, open||
A character vector with paths to
Should roxygen2 be used for documentation? Defaults to
Logical or character; whether or not to paste the contents of
Whether to automatically configure Stan functionality
whenever the package gets installed (see Details). Defaults to
This function first creates a regular R package using
usethis::create_package(), then adds the infrastructure required to compile
stanmodel objects. In the package root directory, the user's
Stan source code is located in:
inst/ |_stan/ | |_include/ | |_include/
.stan files containing instructions to build a
object must be placed in
.stan files go in
stan/ subdirectory, to be invoked by Stan's
#include "include/mylib.stan" #include "data/preprocess.stan"
See rstanarm for many examples.
inst/include is for all user C++ files associated with the
Stan programs. In this folder, the only file to directly interact with the
Stan C++ library is
stan_meta_header.hpp; all other
directives must be channeled through here.
The final step of the package creation is to invoke
rstan_config(), which creates the following files for
interfacing with Stan objects from R:
src contains the
associated with all
ModelName.stan files in
src/Makevars[.win] which link to the
R/stanmodels.R loads the C++ modules containing the
stanmodel class definitions, and assigns an R instance of each
stanmodel object to a
stanmodels list (with names
corresponding to the names of the Stan files).
auto_config = TRUE, a
configure[.win] file is added to the
rstan_config() whenever the package is installed.
Consequently, the package must list rstantools in the
Imports field for this mechanism to work. Setting
auto_config = FALSE
removes the package's dependency on rstantools, but the package then
must be manually configured by running
stanmodel files in
inst/stan are added, removed, or modified.
In order to enable Stan functionality, rstantools copies some files to your package. Since these files are licensed as GPL= 3, the same license applies to your package should you choose todistribute it. Even if you don't use rstantools to createyour package, it is likely that you will be linking to Rcpp toexport the Stan C++ stanmodel objects to R. SinceRcpp is released under GPL >= 2, the same license would applyto your package upon distribution.
Authors willing to license their Stan programs of general interest
under the GPL are invited to contribute their
.stan files and
supporting R code to the rstanarm package.
stanmodel objects corresponding to the Stan programs included with your
package are stored in a list called
stanmodels. To run one of the Stan
programs from within an R function in your package just pass the
appropriate element of the
stanmodels list to one of the rstan
functions for model fitting (e.g.,
sampling()). For example, for a Stan
"foo.stan" you would use
The rstanarm package repository on GitHub.
Guidelines and recommendations for developers of R packages interfacing with Stan and a demonstration getting a simple package working can be found in the vignettes included with rstantools and at mc-stan.org/rstantools/articles.
The useR2016 presentation How to Use (R)Stan to Estimate Models in External R Packages.