rstan: stan_model – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

stan_model

Construct a Stan model

Description

Construct an instance of S4 class stanmodel from a model specified in Stan's modeling language. A stanmodel object can then be used to draw samples from the model. The Stan program (the model expressed in the Stan modeling language) is first translated to C++ code and then the C++ code for the model plus other auxiliary code is compiled into a dynamic shared object (DSO) and then loaded. The loaded DSO for the model can be executed to draw samples, allowing inference to be performed for the model and data.

Usage

stan_model(file, model_name = "anon_model", 
             model_code = "", stanc_ret = NULL, 
             boost_lib = NULL, eigen_lib = NULL, 
             save_dso = TRUE, verbose = FALSE, 
             auto_write = rstan_options("auto_write"), 
             obfuscate_model_name = TRUE, 
             allow_undefined = FALSE, includes = NULL,
             isystem = c(if (!missing(file)) dirname(file), getwd()))

Arguments

`file`	A character string or a connection that R supports specifying the Stan model specification in Stan's modeling language.
`model_name`	A character string naming the model; defaults to `"anon_model"`. However, the model name will be derived from `file` or `model_code` (if `model_code` is the name of a character string object) if `model_name` is not specified.
`model_code`	Either a character string containing the model specification or the name of a character string object in the workspace. This is an alternative to specifying the model via the `file` or `stanc_ret` arguments.
`stanc_ret`	A named list returned from a previous call to the `stanc` function. The list can be used to specify the model instead of using the `file` or `model_code` arguments.
`boost_lib`	The path to a version of the Boost C++ library to use instead of the one in the BH package.
`eigen_lib`	The path to a version of the Eigen C++ library to use instead of the one in the RcppEigen package.
`save_dso`	Logical, defaulting to `TRUE`, indicating whether the dynamic shared object (DSO) compiled from the C++ code for the model will be saved or not. If `TRUE`, we can draw samples from the same model in another R session using the saved DSO (i.e., without compiling the C++ code again).
`verbose`	Logical, defaulting to `FALSE`, indicating whether to report additional intermediate output to the console, which might be helpful for debugging.
`auto_write`	Logical, defaulting to the value of `rstan_options("auto_write")`, indicating whether to write the object to the hard disk using `saveRDS`. Although this argument is `FALSE` by default, we recommend calling `rstan_options("auto_write" = TRUE)` in order to avoid unnecessary recompilations. If `file` is supplied and its `dirname` is writable, then the object will be written to that same directory, substituting a `.rds` extension for the `.stan` extension. Otherwise, the object will be written to the `tempdir`.
`obfuscate_model_name`	A logical scalar that is `TRUE` by default and passed to `stanc`.
`allow_undefined`	A logical scalar that is `FALSE` by default and passed to `stanc`.
`includes`	If not `NULL` (the default), then a character vector of length one (possibly containing one or more `"\n"`) of the form `'#include "/full/path/to/my_header.hpp"'`, which will be inserted into the C++ code in the model's namespace and can be used to provide definitions of functions that are declared but not defined in `file` or `model_code` when `allow_undefined = TRUE`
`isystem`	A character vector naming a path to look for file paths in `file` that are to be included within the Stan program named by `file`. See the Details section below.

Details

If a previously compiled stanmodel exists on the hard drive, its validity is checked and then returned without recompiling. The most common form of invalidity seems to be Stan code that ends with a } rather than a blank line, which causes the hash checker to think that the current model is different than the one saved on the hard drive. To avoid reading previously compiled stanmodels from the hard drive, supply the stanc_ret argument rather than the file or model_code arguments.

There are three ways to specify the model's code for stan_model:

parameter model_code: a character string containing the Stan model specification,
parameter file: a file name (or a connection) from which to read the Stan model specification, or
parameter stanc_ret: a list returned by stanc to be reused.

Value

An instance of S4 class stanmodel that can be passed to the sampling, optimizing, and vb functions.

References

The Stan Development Team Stan Modeling Language User's Guide and Reference Manual. http://mc-stan.org/.

Examples

## Not run: 
stancode <- 'data {real y_mean;} parameters {real y;} model {y ~ normal(y_mean,1);}'
mod <- stan_model(model_code = stancode, verbose = TRUE)
fit <- sampling(mod, data = list(y_mean = 0))
fit2 <- sampling(mod, data = list(y_mean = 5))

## End(Not run)

rstan

R Interface to Stan

v2.21.2

GPL (>= 3)

Authors

Jiqiang Guo [aut], Jonah Gabry [aut], Ben Goodrich [cre, aut], Sebastian Weber [aut], Daniel Lee [ctb], Krzysztof Sakrejda [ctb], Modrak Martin [ctb], Trustees of Columbia University [cph], Oleg Sklyar [cph] (R/cxxfunplus.R), The R Core Team [cph] (R/pairs.R, R/dynGet.R), Jens Oehlschlaegel-Akiyoshi [cph] (R/pairs.R), John Maddock [cph] (gamma.hpp), Paul Bristow [cph] (gamma.hpp), Nikhar Agrawal [cph] (gamma.hpp), Christopher Kormanyos [cph] (gamma.hpp), Bronder Steve [ctb]

Initial release

2020-07-27