R Markdown CmdStan Engine • cmdstanr
Description: cmdstanr

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()
    ```

## Example

    // 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.7 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

## Caching chunks

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.

## Using RStan and CmdStanR engines side-by-side

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()
    ```

## Running interactively

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.