From f2fb60ef3852c040554bc8cf04f7023baa503347 Mon Sep 17 00:00:00 2001 From: Jeremy Colman Date: Thu, 21 Sep 2023 13:42:32 +0100 Subject: [PATCH 1/5] Update r-markdown.Rmd Redraft aimed at clarifying when `override = FALSE` must be used. --- vignettes/r-markdown.Rmd | 48 ++++++++++++++++++++++------------------ 1 file changed, 27 insertions(+), 21 deletions(-) diff --git a/vignettes/r-markdown.Rmd b/vignettes/r-markdown.Rmd index dac62ede8..369eb920e 100644 --- a/vignettes/r-markdown.Rmd +++ b/vignettes/r-markdown.Rmd @@ -21,13 +21,17 @@ knitr::opts_chunk$set( ``` 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`. +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, 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: +Behind the scenes in each option, the engine compiles the model code in each chunk into an +in-memory model: a `stanmodel` if Rstan is being used, or a `CmdStanModel` in the CmdStanR case. The in-memory model 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"} @@ -38,20 +42,20 @@ the `output.var` chunk option. For example: rstan::sampling(model) ``` ```` - -CmdStanR provides a replacement engine, which can be registered as follows: +## 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) check_cmdstan_toolchain(fix = TRUE, quiet = TRUE) -register_knitr_engine() +register_knitr_engine(override = FALSE) ``` -By default, this overrides knitr's built-in `stan` engine so that all `stan` +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: +but instead a `CmdStanModel` object, so the example code above would look like this: ````{verbatim} ```{stan, output.var="model"} @@ -88,16 +92,7 @@ fit <- ex1$sample( print(fit) ``` - -## 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 +## 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 @@ -130,6 +125,17 @@ 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 From 4fd6607d8de4d0cc95e452b707848eb28121941b Mon Sep 17 00:00:00 2001 From: jgabry Date: Thu, 21 Sep 2023 12:36:56 -0600 Subject: [PATCH 2/5] override=FALSE -> override=TRUE --- vignettes/r-markdown.Rmd | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/vignettes/r-markdown.Rmd b/vignettes/r-markdown.Rmd index 369eb920e..3dd9c4e8f 100644 --- a/vignettes/r-markdown.Rmd +++ b/vignettes/r-markdown.Rmd @@ -42,14 +42,16 @@ This is the default option. In that case we can write, for example: rstan::sampling(model) ``` ```` -## Option 2: Using CmdStanR for all chunks + +## 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) check_cmdstan_toolchain(fix = TRUE, quiet = TRUE) -register_knitr_engine(override = FALSE) +register_knitr_engine(override = TRUE) ``` This overrides knitr's built-in `stan` engine so that all `stan` @@ -92,6 +94,8 @@ fit <- ex1$sample( 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 From 2563948621cc63887e5f17e62291b893e605451f Mon Sep 17 00:00:00 2001 From: jgabry Date: Mon, 25 Sep 2023 12:45:34 -0600 Subject: [PATCH 3/5] update to not use "in-memory" to avoid confusion --- vignettes/r-markdown.Rmd | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/vignettes/r-markdown.Rmd b/vignettes/r-markdown.Rmd index 3dd9c4e8f..4afc784ba 100644 --- a/vignettes/r-markdown.Rmd +++ b/vignettes/r-markdown.Rmd @@ -26,8 +26,11 @@ engines. Where users wish to write Stan programs as chunks directly in R Markdow 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 into an -in-memory model: a `stanmodel` if Rstan is being used, or a `CmdStanModel` in the CmdStanR case. The in-memory model is assigned to a variable with the name given by the `output.var` chunk option. +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 @@ -49,8 +52,6 @@ If CmdStanR is being used a replacement engine needs to be registered along the ```{r register-engine, message=FALSE} library(cmdstanr) -check_cmdstan_toolchain(fix = TRUE, quiet = TRUE) - register_knitr_engine(override = TRUE) ``` From 718a0c61f59d8add47bfb80601d1a0f1a35c3e16 Mon Sep 17 00:00:00 2001 From: jgabry Date: Mon, 25 Sep 2023 12:45:48 -0600 Subject: [PATCH 4/5] add a line of whitespace so bullet points render properly --- vignettes/r-markdown.Rmd | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/vignettes/r-markdown.Rmd b/vignettes/r-markdown.Rmd index 4afc784ba..ec03831e0 100644 --- a/vignettes/r-markdown.Rmd +++ b/vignettes/r-markdown.Rmd @@ -22,8 +22,9 @@ knitr::opts_chunk$set( 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 + +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 From 421d28fc53e0cd33170739d40ad0d8fd9d47ed16 Mon Sep 17 00:00:00 2001 From: jgabry Date: Mon, 25 Sep 2023 12:56:02 -0600 Subject: [PATCH 5/5] update the html to reflect the new edits --- docs/articles/r-markdown.html | 74 ++++++++++++++++++++++------------- 1 file changed, 46 insertions(+), 28 deletions(-) diff --git a/docs/articles/r-markdown.html b/docs/articles/r-markdown.html index eeb298b19..c403854e2 100644 --- a/docs/articles/r-markdown.html +++ b/docs/articles/r-markdown.html @@ -40,7 +40,7 @@ cmdstanr - 0.6.0 + 0.6.1 @@ -143,13 +143,27 @@

Mikhail

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:

+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. +
  2. all Stan chunks are to be processed using CmdStanR; and.
    +
    3. +
  3. some chunks are to be processed by RStan and some by CmdStanR.
    4. +
+

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:

```{stan, output.var="model"}
 // Stan model code
 ```
@@ -157,19 +171,21 @@ 
Mikhail
 ```{r}
 rstan::sampling(model)
 ```
-

CmdStanR provides a replacement engine, which can be registered as -follows:

+
+
+

Option 2: Using CmdStanR for all chunks +

+

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

-

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

+object, but instead a CmdStanModel object, so the example +code above would look like this:

```{stan, output.var="model"}
 // Stan model code
 ```
@@ -177,6 +193,7 @@ 
Mikhail
 ```{r}
 model$sample()
 ```
+

Example

@@ -212,7 +229,7 @@

Example#> #> All 4 chains finished successfully. #> Mean chain execution time: 0.0 seconds. -#> Total execution time: 0.7 seconds. +#> Total execution time: 0.6 seconds. print(fit) #> variable mean median sd mad q5 q95 rhat ess_bulk ess_tail @@ -221,15 +238,8 @@

Example#> 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 +

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 @@ -259,6 +269,14 @@

Using RStan and CmdStanR ```

+

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