R Markdown supports a variety of languages through the use of knitr language engines. One such engine is the stan
engine, which allows users to write Stan programs directly in their R Markdown documents by setting the language of the chunk to stan
.
Behind the scenes, the engine relies on RStan to compile the model code into an in-memory stanmodel
, which is assigned to a variable with the name given by the output.var
chunk option. For example:
```{stan, output.var="model"}
// Stan model code
```
```{r}
rstan::sampling(model) ```
CmdStanR provides a replacement engine, which can be registered as follows:
library(cmdstanr)
check_cmdstan_toolchain(fix = TRUE, quiet = TRUE)
register_knitr_engine()
By default, this overrides knitr’s built-in stan
engine so that all stan
chunks are processed with CmdStanR, not RStan. Of course, this also means that the variable specified by output.var
will no longer be a stanmodel
object, but instead a CmdStanModel
object, so the code above would look like this:
```{stan, output.var="model"}
// Stan model code
```
```{r}
model$sample() ```
// This stan chunk results in a CmdStanModel object called "ex1"
parameters {
array[2] real y;
}
model {
y[1] ~ normal(0, 1);
y[2] ~ double_exponential(0, 2);
}
ex1$print()
#> // This stan chunk results in a CmdStanModel object called "ex1"
#> parameters {
#> array[2] real y;
#> }
#> model {
#> y[1] ~ normal(0, 1);
#> y[2] ~ double_exponential(0, 2);
#> }
fit <- ex1$sample(
refresh = 0,
seed = 42L
)
#> Running MCMC with 4 sequential chains...
#>
#> Chain 1 finished in 0.0 seconds.
#> Chain 2 finished in 0.0 seconds.
#> Chain 3 finished in 0.0 seconds.
#> Chain 4 finished in 0.0 seconds.
#>
#> All 4 chains finished successfully.
#> Mean chain execution time: 0.0 seconds.
#> Total execution time: 0.6 seconds.
print(fit)
#> variable mean median sd mad q5 q95 rhat ess_bulk ess_tail
#> lp__ -1.50 -1.17 1.24 0.96 -3.94 -0.18 1.00 1304 1536
#> y[1] -0.01 -0.01 0.99 0.99 -1.67 1.60 1.00 1993 2262
#> y[2] -0.07 -0.04 2.90 2.05 -4.79 4.54 1.00 2050 1420
Use cache=TRUE
chunk option to avoid re-compiling the Stan model code every time the R Markdown is knit/rendered.
You can find the Stan model file and the compiled executable in the document’s cache directory.
While the default behavior is to override the built-in stan
engine because the assumption is that the user is probably not using both RStan and CmdStanR in the same document or project, the option to use both exists. When registering CmdStanR’s knitr engine, set override = FALSE
to register the engine as a cmdstan
engine:
register_knitr_engine(override = FALSE)
This will cause stan
chunks to be processed by knitr’s built-in, RStan-based engine and only use CmdStanR’s knitr engine for cmdstan
chunks:
```{stan, output.var="model_obj1"}
// Results in a stanmodel object from RStan
```
```{r}
rstan::sampling(model_obj1)
```
```{cmdstan, output.var="model_obj2"}
// Results in a CmdStanModel object from CmdStanR
```
```{r}
model_obj2$sample() ```
When running chunks interactively in RStudio (e.g. when using R Notebooks), it has been observed that the built-in, RStan-based engine is used for stan
chunks even when CmdStanR’s engine has been registered in the session as the engine for stan
. As a workaround, when running chunks interactively, it is recommended to use the override = FALSE
option and change stan
chunks to be cmdstan
chunks.
Do not worry: if the template you use supports syntax highlighting for the Stan language, that syntax highlighting will be applied to cmdstan
chunks when the document is knit/rendered.