Construct a Stan model

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.

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 = isTRUE(getOption("stanc.allow_undefined", FALSE)),
    allow_optimizations = isTRUE(getOption("stanc.allow_optimizations", FALSE)),
    standalone_functions = isTRUE(getOption("stanc.standalone_functions", FALSE)),
    use_opencl = isTRUE(getOption("stanc.use_opencl", FALSE)),
    warn_pedantic = isTRUE(getOption("stanc.warn_pedantic", FALSE)),
    warn_uninitialized = isTRUE(getOption("stanc.warn_uninitialized", 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.

allow_optimizations

A logical scalar that is FALSE by default and passed to stanc.

standalone_functions

A logical scalar that is FALSE by default and passed to stanc.

use_opencl

A logical scalar that is FALSE by default and passed to stanc.

warn_pedantic

A logical scalar that is FALSE by default and passed to stanc.

warn_uninitialized

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:

  1. parameter model_code: a character string containing the Stan model specification,

  2. parameter file: a file name (or a connection) from which to read the Stan model specification, or

  3. 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. https://mc-stan.org/.

See also

stanmodel for details on the class.

sampling, optimizing, and vb, which take a stanmodel object as input, for estimating the model parameters.

More details on Stan, including the full user's guide and reference manual, can be found at https://mc-stan.org/.

Examples

if (FALSE) {
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))
}