---
title: "R Markdown CmdStan Engine"
author: "Mikhail Popov"
output:
  rmarkdown::html_vignette:
    toc: true
params:
  EVAL: !r identical(Sys.getenv("NOT_CRAN"), "true")
vignette: >
  %\VignetteIndexEntry{R Markdown CmdStan Engine}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r settings-knitr, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = if (isTRUE(exists("params"))) params$EVAL else FALSE
)
```

R Markdown supports a variety of languages through the use of knitr language
engines. Where users wish to write Stan programs as chunks directly in R Markdown documents there are three options: 

1. the user wishes all the Stan chunks in the R Markdown document to be processed using RStan;    
2. all Stan chunks are to be processed using CmdStanR; and.   
3. some chunks are to be processed by RStan and some by CmdStanR. 

Behind the scenes in each option, the engine compiles the model code in each
chunk and creates an object that provides methods to run the model: a
`stanmodel` if Rstan is being used, or a `CmdStanModel` in the CmdStanR case.
This model object is assigned to a variable with the name given by the
`output.var` chunk option.

## Option 1: Using RStan for all chunks

This is the default option. In that case we can write, for example:

````{verbatim}
```{stan, output.var="model"}
// Stan model code
```

```{r}
rstan::sampling(model)
```
````

## Option 2: Using CmdStanR for all chunks

If CmdStanR is being used a replacement engine needs to be registered along the following lines:

```{r register-engine, message=FALSE}
library(cmdstanr)
register_knitr_engine(override = TRUE)
```

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 example code above would look like this:

````{verbatim}
```{stan, output.var="model"}
// Stan model code
```

```{r}
model$sample()
```
````

## Example

```{stan ex1, output.var="ex1"}
// 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);
}
```

```{r print-ex1}
ex1$print()
```

```{r fit-ex1}
fit <- ex1$sample(
  refresh = 0,
  seed = 42L
)

print(fit)
```


## Option 3: Using both RStan and CmdStanR in the same R Markdown document

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:

```{r register-engine-no-override}
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:

````{verbatim}
```{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()
```
````


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


## Running interactively

When running chunks interactively in RStudio (e.g. when using
[R Notebooks](https://bookdown.org/yihui/rmarkdown/notebook.html)), 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.