stan_model {rstan} | R Documentation

## 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)

### 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 `"\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`

### 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 `stanmodel`s 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. http://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 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)
    fit <- sampling(mod, data = list(y_mean = 0))
    fit2 <- sampling(mod, data = list(y_mean = 5))

    ## End(Not run)

[Package rstan version 2.16.2 Index]