stopifnot(require(knitr)) opts_chunk$set( comment=NA, eval = if (isTRUE(exists("params"))) params$EVAL else FALSE ) td <- tempdir() PATH <- file.path(td, "rstanlm") if(dir.exists(PATH)) { unlink(PATH, recursive = TRUE, force = TRUE) }
In this vignette we will walk through the steps necessary for creating an R package that depends on Stan by creating a package with one function that fits a simple linear regression. Before continuing, we recommend that you first read the other vignette Guidelines for Developers of R Packages Interfacing with Stan.
The rstantools package offers two methods for adding Stan functionality to R packages:
rstan_create_package()
: set up a new R package with Stan programsuse_rstan()
: add Stan functionality to an existing R packageHere we will use rstan_create_package()
to initialize a bare-bones package
directory. The name of our demo package will be rstanlm; it will fit a
simple linear regression model using Stan.
library("rstantools") rstan_create_package(path = 'rstanlm')
library("rstantools") rstan_create_package(path = PATH, rstudio=FALSE, open=FALSE)
If we had existing .stan
files to include with the package we could use the
optional stan_files
argument to rstan_create_package()
to include them.
Another option, which we'll use below, is to add the Stan files once the
basic structure of the package is in place.
We can now set the new working directory to the new package directory and view
the contents. (Note: if using RStudio then by default the newly created project
for the package will be opened in a new session and you will not need the call
to setwd()
.)
setwd("rstanlm") list.files(all.files = TRUE)
list.files(PATH, all.files = TRUE)
file.show("DESCRIPTION")
DES <- readLines(file.path(PATH, "DESCRIPTION")) cat(DES, sep = "\n")
Some of the sections in the DESCRIPTION
file need to be edited by hand (e.g.,
Title
, Author
, Maintainer
, and Description
, but these also can be set
with the fields
argument to rstan_create_package()
). However,
rstan_create_package()
has added the necessary packages and versions to
Depends
, Imports
, and LinkingTo
to enable Stan functionality.
Before deleting the Read-and-delete-me
file in the new package directory make
sure to read it because it contains some important instructions about
customizing your package:
file.show("Read-and-delete-me")
cat(readLines(file.path(PATH, "Read-and-delete-me")), sep = "\n")
You can move this file out of the directory, delete it, or list it in the
.Rbuildignore
file if you want to keep it in the directory.
file.remove('Read-and-delete-me')
file.remove(file.path(PATH, 'Read-and-delete-me'))
Our package will call rstan's sampling()
method to use MCMC to fit a simple
linear regression model for an outcome variable y
with a single predictor x
.
After writing the necessary Stan program, the file should be saved with a
.stan
extension in the inst/stan
subdirectory. We'll save the
following program to inst/stan/lm.stan
:
```{stan, output.var = "foo", eval = FALSE}
// Save this file as inst/stan/lm.stan
data {
int
y ~ normal(intercept + beta * x, sigma); }
```r stan_prog <- " data { int<lower=1> N; vector[N] x; vector[N] y; } parameters { real intercept; real beta; real<lower=0> sigma; } model { // ... priors, etc. y ~ normal(intercept + beta * x, sigma); } " writeLines(stan_prog, con = file.path(PATH, "inst", "stan", "lm.stan")) rstan_config(PATH)
The inst/stan
subdirectory can contain additional Stan programs if
required by your package. During installation, all Stan programs will be
compiled and saved in the list stanmodels
that can then be used by R function
in the package. The rule is that the Stan program compiled from the model code
in inst/stan/foo.stan
is stored as list element stanmodels$foo
. Thus, the
filename of the Stan program in the inst/stan
directory should not contain
spaces or dashes and nor should it start with a number or utilize non-ASCII
characters.
We next create the file R/lm_stan.R
where we define the function lm_stan()
in which our compiled Stan model is being used. Setting the
rstan_create_package()
argument roxygen = TRUE
(the default value) enables
roxygen2 documentation for
the package functions. The following comment block placed in lm_stan.R
ensures that the function has a help file and that it is added to the package
NAMESPACE
:
# Save this file as `R/lm_stan.R` #' Bayesian linear regression with Stan #' #' @export #' @param x Numeric vector of input values. #' @param y Numeric vector of output values. #' @param ... Arguments passed to `rstan::sampling` (e.g. iter, chains). #' @return An object of class `stanfit` returned by `rstan::sampling` #' lm_stan <- function(x, y, ...) { standata <- list(x = x, y = y, N = length(y)) out <- rstan::sampling(stanmodels$lm, data = standata, ...) return(out) }
Rcode <- " #' Bayesian linear regression with Stan #' #' @export #' @param x Numeric vector of input values. #' @param y Numeric vector of output values. #' @param ... Arguments passed to `rstan::sampling`. #' @return An object of class `stanfit` returned by `rstan::sampling` lm_stan <- function(x, y, ...) { out <- rstan::sampling(stanmodels$lm, data=list(x=x, y=y, N=length(y)), ...) return(out) } " writeLines(Rcode, con = file.path(PATH, "R", "lm_stan.R"))
When roxygen2 documentation is enabled, a top-level package file
R/rstanlm-package.R
is created by rstan_create_package()
to import necessary
functions for other packages and to set up the package for compiling Stan C++
code:
file.show(file.path("R", "rstanlm-package.R"))
cat(readLines(file.path(PATH, "R", "rstanlm-package.R")), sep = "\n")
The #' @description
section can be manually edited to provided specific
information about the package.
With roxygen documentation enabled, we need to generate the documentation
for lm_stan
and update the NAMESPACE
so the function is exported, i.e.,
available to users when the package is installed. This can be done with the
function roxygen2::roxygenize()
, which needs to be called twice initially.
try(roxygen2::roxygenize(load_code = rstantools_load_code), silent = TRUE) roxygen2::roxygenize()
try(roxygen2::roxygenize(PATH, load_code = rstantools_load_code), silent = TRUE) roxygen2::roxygenize(PATH)
Finally, the package is ready to be installed:
# using ../rstanlm because already inside the rstanlm directory install.packages("../rstanlm", repos = NULL, type = "source")
install.packages(PATH, repos = NULL, type = "source")
It is also possible to use devtools::install(quick=FALSE)
to install the
package. The argument quick=FALSE
is necessary if you want to recompile the
Stan models. Going forward, if you only make a change to the R code or the
documentation, you can set quick=TRUE
to speed up the process, or use
devtools::load_all()
.
After installation, the package can be loaded and used like any other R package:
library("rstanlm")
fit <- lm_stan(y = rnorm(10), x = rnorm(10), # arguments passed to sampling iter = 2000, refresh = 500) print(fit)
unlink(PATH, recursive = TRUE, force = TRUE)
Details can be found in the documentation for rstan_create_package()
so we
only mention some of these briefly here:
Running rstan_create_package()
with auto_config = TRUE
(the default value)
automatically synchronizes the Stan C++ files with the .stan
model files
located in inst/stan
, although this creates a dependency of your package on
rstantools itself (i.e., rstantools must be installed for your package
to work). Setting auto_config = FALSE
removes this dependency, at the cost of
having to manually synchronize Stan C++ files by running rstan_config()
every
time a package .stan
file is added, removed, or even just modified.
The function use_rstan()
can be used to add Stan functionality to an
existing package, instead of building the package from scratch.
R/<package-name>-package.R
file.
Check the roxygen documentation for more details.One may add additional Stan models to an existing package.
The following steps are required if one is using devtools
:
inst/stan/new.stan
pkgbuild::compile_dll()
to preform a fake R CMD install.roxygen2::roxygenize()
to update the documentation.devtools::install()
to install the package locally.Guidelines for Developers of R Packages Interfacing with Stan
Ask a question at the Stan Forums
R packages by Hadley Wickham and Jenny Bryan provides a solid foundation in R package development as well as the release process.
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.