From 163f49a7a2238d9578a2e41a31ad576c9a54f6cf Mon Sep 17 00:00:00 2001 From: rok-cesnovar Date: Sat, 9 Apr 2022 12:31:19 +0200 Subject: [PATCH 1/8] add vignette on deprecations --- _pkgdown.yml | 1 + docs/articles/deprecations.html | 288 ++++++++++++++++++ .../header-attrs-2.11/header-attrs.js | 12 + docs/articles/index.html | 8 +- vignettes/deprecations-files/logistic.stan | 17 ++ vignettes/deprecations.Rmd | 129 ++++++++ 6 files changed, 453 insertions(+), 2 deletions(-) create mode 100644 docs/articles/deprecations.html create mode 100644 docs/articles/deprecations_files/header-attrs-2.11/header-attrs.js create mode 100644 vignettes/deprecations-files/logistic.stan create mode 100644 vignettes/deprecations.Rmd diff --git a/_pkgdown.yml b/_pkgdown.yml index cd1445ccf..2f99caefa 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -71,6 +71,7 @@ articles: contents: - cmdstanr-internals - r-markdown + - deprecations - profiling - articles-online-only/opencl diff --git a/docs/articles/deprecations.html b/docs/articles/deprecations.html new file mode 100644 index 000000000..ed5a7831d --- /dev/null +++ b/docs/articles/deprecations.html @@ -0,0 +1,288 @@ + + + + + + + +Handling deprecated Stan features with the canonicalizer in CmdStanR • cmdstanr + + + + + + + + + + + + + + + + + +
+
+ + + + +
+
+
+

Handling deprecated Stan features with the +canonicalizer in CmdStanR

+

Rok Češnovar, Jonah +Gabry

+ + + Source: vignettes/deprecations.Rmd + + +
+ + + +
+

+Introduction

+

This vignette demonstrates how to handle cases where one or more +feature in your Stan model has been deprecated. For most deprecated +features, the Stan-to-C++ compiler can be used to automatically convert +to a non-deprecated feature that replaces the deprecated one. This +vignette show cases how that automatic conversion can be done using +CmdStanR.

+

The automatic conversion of deprecated features to non-deprecated +features is done by with a mode called canonicalizer, which +is part of the Stan-to-C++ compiler. We recommend using CmdStan 2.29.2 +or newer when using the canonicalizer and this vignette. The minimum +CmdStanR version to run the vignette is 0.5.0.

+
+library(cmdstanr)
+check_cmdstan_toolchain(fix = TRUE, quiet = TRUE)
+
+
+

+Deprecation warnings

+

Consider the following simple logistic regression with parameters +alpha and beta, covariates X, and +outcome y:

+
data {
+  int<lower=1> k;
+  int<lower=0> n;
+  matrix[n, k] X;
+  int y[n];
+}
+parameters {
+  vector[k] beta;
+  real alpha;
+}
+model {
+  # priors
+  target += std_normal_log(beta);
+  alpha ~ std_normal();
+  
+  y ~ bernoulli_logit(X * beta + alpha);
+}
+

When compiling the model we receive a few warnings:

+
+mod <- cmdstan_model(stan_file = "deprecations-files/logistic.stan")
+

The first warning is about using the deprecated array syntax:

+
int y[n];
+

which should be replaced with the new syntax that uses the +array keyword:

+
array[n] int y;
+

The second warning is about using the deprecated commenting symbol +#, which should be replaced by //.

+

The last warning is about the use of the deprecated _log +suffix for probability density and mass functions. The suffix should be +replaced with the _lpdf suffix in this case, though it +could also be the _lpmf suffix, in case of using the +deprecated _log suffix with probability mass functions.

+

We can go and fix these issues manually or use the canonicalizer as +outlined in the next section.

+
+
+

+Using the canonicalizer

+

The canonicalizer is available through the canonicalize +argument of the $format() method of the +CmdStanModel class. The arguments accepts TRUE +and FALSE values, in which case all or no features of the +canonicalizer are used, but it can also accept a list of character +vectors that determine which features of the canonicalizer to use. The +canonincalizer in CmdStan 2.29.2 support four features: +parentheses, braces, includes and +deprecations. parentheses, braces +clean up the use of parentheses and braces, while includes +will replace the #include statement with the code from the +included files. See the canonicalizer +section of the Stan User’s Guide for more.

+

In this vignette we will be using the deprecations +feature that replaces deprecated Stan model features with non-deprecated +ones if possible.

+

Example of use:

+
+mod$format(canonicalize = list("deprecations"))
+
data {
+  int<lower=1> k;
+  int<lower=0> n;
+  matrix[n, k] X;
+  array[n] int y;
+}
+parameters {
+  vector[k] beta;
+  real alpha;
+}
+model {
+  // priors
+  target += std_normal_lpdf(beta);
+  alpha ~ std_normal();
+  
+  y ~ bernoulli_logit(X * beta + alpha);
+}
+

By default, the format function will print the resulting model code. +We can see that all three issues were resolved. y is now +defined using the new array keyword, the comment uses // +and the std_normal_log() is replaced with +std_normal_lpdf().

+

You can also use the $format() method to write the +updated version of the model directly to the Stan model file. That can +be enabled by setting overwrite_file = TRUE. The previous +version of the file will automatically be backed up to a file with the +.stan.bak suffix. If that is not desired or you are using a +version system and backuping is redundant, you can disable it by setting +backup = FALSE:

+
+mod$format(
+    canonicalize = list("deprecations"),
+    overwrite_file = TRUE,
+    backup = FALSE
+)
+
+
+ + + +
+ + + +
+

Developed by Jonah Gabry, Rok Češnovar.

+
+ +
+

Site built with pkgdown 1.6.1.

+
+ +
+
+ + + + + + diff --git a/docs/articles/deprecations_files/header-attrs-2.11/header-attrs.js b/docs/articles/deprecations_files/header-attrs-2.11/header-attrs.js new file mode 100644 index 000000000..dd57d92e0 --- /dev/null +++ b/docs/articles/deprecations_files/header-attrs-2.11/header-attrs.js @@ -0,0 +1,12 @@ +// Pandoc 2.9 adds attributes on both header and div. We remove the former (to +// be compatible with the behavior of Pandoc < 2.8). +document.addEventListener('DOMContentLoaded', function(e) { + var hs = document.querySelectorAll("div.section[class*='level'] > :first-child"); + var i, h, a; + for (i = 0; i < hs.length; i++) { + h = hs[i]; + if (!/^h[1-6]$/i.test(h.tagName)) continue; // it should be a header h1-h6 + a = h.attributes; + while (a.length > 0) h.removeAttribute(a[0].name); + } +}); diff --git a/docs/articles/index.html b/docs/articles/index.html index 9693e214c..bb629d2e7 100644 --- a/docs/articles/index.html +++ b/docs/articles/index.html @@ -79,7 +79,7 @@ cmdstanr - 0.5.0 + 0.5.1 @@ -183,13 +183,17 @@

Getting started

More details

-

More information about compilation, passing in data, how CmdStan ouput is written to CSV and read back into R, profiling Stan programs, running Stan on GPUs, and using CmdStanR in R Markdown documents.

+

More information about compilation, passing in data, how CmdStan +ouput is written to CSV and read back into R, profiling Stan programs, +running Stan on GPUs, and using CmdStanR in R Markdown documents.

How does CmdStanR work?
R Markdown CmdStan Engine
+
Handling deprecated Stan features with the canonicalizer in CmdStanR
+
Profiling Stan programs with CmdStanR
Running Stan on the GPU with OpenCL
diff --git a/vignettes/deprecations-files/logistic.stan b/vignettes/deprecations-files/logistic.stan new file mode 100644 index 000000000..a3f114619 --- /dev/null +++ b/vignettes/deprecations-files/logistic.stan @@ -0,0 +1,17 @@ +data { + int k; + int n; + matrix[n, k] X; + int y[n]; +} +parameters { + vector[k] beta; + real alpha; +} +model { + # priors + target += std_normal_log(beta); + alpha ~ std_normal(); + + y ~ bernoulli_logit(X * beta + alpha); +} diff --git a/vignettes/deprecations.Rmd b/vignettes/deprecations.Rmd new file mode 100644 index 000000000..8529568c4 --- /dev/null +++ b/vignettes/deprecations.Rmd @@ -0,0 +1,129 @@ +--- +title: "Handling deprecated Stan features with the canonicalizer in CmdStanR" +author: "Rok Češnovar, Jonah Gabry" +output: + rmarkdown::html_vignette: + toc: true + toc_depth: 4 +params: + EVAL: !r identical(Sys.getenv("NOT_CRAN"), "true") +vignette: > + %\VignetteIndexEntry{Handling deprecated Stan features with the canonicalizer in CmdStanR} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + +```{r child="children/settings-knitr.Rmd"} +``` + +## Introduction + +This vignette demonstrates how to handle cases where one or more feature +in your Stan model has been deprecated. For most deprecated features, the +Stan-to-C++ compiler can be used to automatically convert to a non-deprecated +feature that replaces the deprecated one. This vignette show cases how that +automatic conversion can be done using CmdStanR. + +The automatic conversion of deprecated features to non-deprecated features +is done by with a mode called `canonicalizer`, which is part of the Stan-to-C++ +compiler. We recommend using CmdStan 2.29.2 or newer when using the canonicalizer +and this vignette. The minimum CmdStanR version to run the vignette is 0.5.0. + +```{r library, message=FALSE} +library(cmdstanr) +check_cmdstan_toolchain(fix = TRUE, quiet = TRUE) +``` + +## Deprecation warnings + +Consider the following simple logistic regression with parameters `alpha` and `beta`, +covariates `X`, and outcome `y`: + +```stan +data { + int k; + int n; + matrix[n, k] X; + int y[n]; +} +parameters { + vector[k] beta; + real alpha; +} +model { + # priors + target += std_normal_log(beta); + alpha ~ std_normal(); + + y ~ bernoulli_logit(X * beta + alpha); +} +``` + +When compiling the model we receive a few warnings: + +```{r compile, message=FALSE} +mod <- cmdstan_model(stan_file = "deprecations-files/logistic.stan") +``` + +The first warning is about using the deprecated array syntax: +```stan +int y[n]; +``` +which should be replaced with the new syntax that uses the `array` keyword: +```stan +array[n] int y; +``` + +The second warning is about using the deprecated commenting symbol `#`, +which should be replaced by `//`. + +The last warning is about the use of the deprecated `_log` suffix for +probability density and mass functions. The suffix should be replaced +with the `_lpdf` suffix in this case, though it could also be the +`_lpmf` suffix, in case of using the deprecated `_log` suffix with +probability mass functions. + +We can go and fix these issues manually or use the canonicalizer as outlined +in the next section. + +# Using the canonicalizer + +The canonicalizer is available through the `canonicalize` argument of the +`$format()` method of the `CmdStanModel` class. The arguments accepts +`TRUE` and `FALSE` values, in which case all or no features of the +canonicalizer are used, but it can also accept a list of character vectors that +determine which features of the canonicalizer to use. The canonincalizer in +CmdStan 2.29.2 support four features: `parentheses`, `braces`, `includes` +and `deprecations`. `parentheses`, `braces` clean up the use of parentheses and braces, +while `includes` will replace the `#include` statement with the code from +the included files. See the [canonicalizer section of the Stan User's Guide](https://mc-stan.org/docs/2_29/stan-users-guide/stanc-pretty-printing.html#canonicalizing) for +more. + +In this vignette we will be using the `deprecations` feature that replaces +deprecated Stan model features with non-deprecated ones if possible. + +Example of use: + +```{r canonicalize, message=FALSE} +mod$format(canonicalize = list("deprecations")) +``` + +By default, the format function will print the resulting model code. We +can see that all three issues were resolved. `y` is now defined using the +new array keyword, the comment uses `//` and the `std_normal_log()` is replaced +with `std_normal_lpdf()`. + +You can also use the `$format()` method to write the updated version of the +model directly to the Stan model file. That can be enabled by setting +`overwrite_file = TRUE`. The previous version of the file will automatically +be backed up to a file with the `.stan.bak` suffix. If that is not desired or +you are using a version system and backuping is redundant, +you can disable it by setting `backup = FALSE`: + +```{r overwrite_file, eval=FALSE} +mod$format( + canonicalize = list("deprecations"), + overwrite_file = TRUE, + backup = FALSE +) +``` \ No newline at end of file From b7c47224017519aef12ed3a0f5d2a30bf784d816 Mon Sep 17 00:00:00 2001 From: rok-cesnovar Date: Sat, 9 Apr 2022 15:09:53 +0200 Subject: [PATCH 2/8] add resource files --- vignettes/deprecations.Rmd | 2 ++ 1 file changed, 2 insertions(+) diff --git a/vignettes/deprecations.Rmd b/vignettes/deprecations.Rmd index 8529568c4..cdffe3796 100644 --- a/vignettes/deprecations.Rmd +++ b/vignettes/deprecations.Rmd @@ -5,6 +5,8 @@ output: rmarkdown::html_vignette: toc: true toc_depth: 4 +resource_files: + - deprecations-files/logistic.stan params: EVAL: !r identical(Sys.getenv("NOT_CRAN"), "true") vignette: > From ce224d435333c1748c78f9aaa3054c64c8cac311 Mon Sep 17 00:00:00 2001 From: rok-cesnovar Date: Sat, 9 Apr 2022 15:14:21 +0200 Subject: [PATCH 3/8] add install extras --- vignettes/.install_extras | 1 + 1 file changed, 1 insertion(+) create mode 100644 vignettes/.install_extras diff --git a/vignettes/.install_extras b/vignettes/.install_extras new file mode 100644 index 000000000..134e9d91a --- /dev/null +++ b/vignettes/.install_extras @@ -0,0 +1 @@ +deprecations-files/logistic.stan \ No newline at end of file From ba3ba38e6f32f49be386999d3b312ed745966bbf Mon Sep 17 00:00:00 2001 From: rok-cesnovar Date: Sat, 9 Apr 2022 17:06:27 +0200 Subject: [PATCH 4/8] move model to inst --- .../logistic.stan => inst/deprecated-logistic.stan | 2 +- vignettes/.install_extras | 1 - vignettes/deprecations.Rmd | 2 +- 3 files changed, 2 insertions(+), 3 deletions(-) rename vignettes/deprecations-files/logistic.stan => inst/deprecated-logistic.stan (98%) delete mode 100644 vignettes/.install_extras diff --git a/vignettes/deprecations-files/logistic.stan b/inst/deprecated-logistic.stan similarity index 98% rename from vignettes/deprecations-files/logistic.stan rename to inst/deprecated-logistic.stan index a3f114619..9ef23a075 100644 --- a/vignettes/deprecations-files/logistic.stan +++ b/inst/deprecated-logistic.stan @@ -12,6 +12,6 @@ model { # priors target += std_normal_log(beta); alpha ~ std_normal(); - + y ~ bernoulli_logit(X * beta + alpha); } diff --git a/vignettes/.install_extras b/vignettes/.install_extras deleted file mode 100644 index 134e9d91a..000000000 --- a/vignettes/.install_extras +++ /dev/null @@ -1 +0,0 @@ -deprecations-files/logistic.stan \ No newline at end of file diff --git a/vignettes/deprecations.Rmd b/vignettes/deprecations.Rmd index cdffe3796..13360051a 100644 --- a/vignettes/deprecations.Rmd +++ b/vignettes/deprecations.Rmd @@ -64,7 +64,7 @@ model { When compiling the model we receive a few warnings: ```{r compile, message=FALSE} -mod <- cmdstan_model(stan_file = "deprecations-files/logistic.stan") +mod <- cmdstan_model(stan_file = system.file("deprecated-logistic.stan", package = "cmdstanr")) ``` The first warning is about using the deprecated array syntax: From 06ecc7d8bdd17d071b72ace92d1dcce363be8577 Mon Sep 17 00:00:00 2001 From: jgabry Date: Wed, 13 Apr 2022 13:02:22 -0600 Subject: [PATCH 5/8] use write_stan_file and a few minor edits --- inst/deprecated-logistic.stan | 17 ------- vignettes/deprecations.Rmd | 84 +++++++++++++++++------------------ 2 files changed, 42 insertions(+), 59 deletions(-) delete mode 100644 inst/deprecated-logistic.stan diff --git a/inst/deprecated-logistic.stan b/inst/deprecated-logistic.stan deleted file mode 100644 index 9ef23a075..000000000 --- a/inst/deprecated-logistic.stan +++ /dev/null @@ -1,17 +0,0 @@ -data { - int k; - int n; - matrix[n, k] X; - int y[n]; -} -parameters { - vector[k] beta; - real alpha; -} -model { - # priors - target += std_normal_log(beta); - alpha ~ std_normal(); - - y ~ bernoulli_logit(X * beta + alpha); -} diff --git a/vignettes/deprecations.Rmd b/vignettes/deprecations.Rmd index 13360051a..3fc8fe8e6 100644 --- a/vignettes/deprecations.Rmd +++ b/vignettes/deprecations.Rmd @@ -1,12 +1,10 @@ --- title: "Handling deprecated Stan features with the canonicalizer in CmdStanR" -author: "Rok Češnovar, Jonah Gabry" +author: "Rok Češnovar and Jonah Gabry" output: rmarkdown::html_vignette: toc: true toc_depth: 4 -resource_files: - - deprecations-files/logistic.stan params: EVAL: !r identical(Sys.getenv("NOT_CRAN"), "true") vignette: > @@ -20,16 +18,17 @@ vignette: > ## Introduction -This vignette demonstrates how to handle cases where one or more feature -in your Stan model has been deprecated. For most deprecated features, the -Stan-to-C++ compiler can be used to automatically convert to a non-deprecated -feature that replaces the deprecated one. This vignette show cases how that -automatic conversion can be done using CmdStanR. +This vignette demonstrates how to handle cases where your Stan program contains +deprecated features resulting in deprecation warnings. In most cases, the +Stan-to-C++ compiler can be used to automatically update your code to a +non-deprecated feature that replaces the deprecated one. This vignette showcases +how that automatic conversion can be done using CmdStanR. -The automatic conversion of deprecated features to non-deprecated features -is done by with a mode called `canonicalizer`, which is part of the Stan-to-C++ -compiler. We recommend using CmdStan 2.29.2 or newer when using the canonicalizer -and this vignette. The minimum CmdStanR version to run the vignette is 0.5.0. +The automatic conversion of deprecated features to non-deprecated features is +done using the so-called "canonicalizer", which is part of the Stan-to-C++ +compiler. We recommend using CmdStan 2.29.2 or later when using the +canonicalizer and this vignette. The minimum CmdStanR version to run the +code in the vignette is 0.5.0. ```{r library, message=FALSE} library(cmdstanr) @@ -38,10 +37,11 @@ check_cmdstan_toolchain(fix = TRUE, quiet = TRUE) ## Deprecation warnings -Consider the following simple logistic regression with parameters `alpha` and `beta`, -covariates `X`, and outcome `y`: +The following logistic regression model uses several deprecated language +features, resulting in several warnings during compilation. -```stan +```{r logistic} +stan_file <- write_stan_file(" data { int k; int n; @@ -59,53 +59,52 @@ model { y ~ bernoulli_logit(X * beta + alpha); } +") +mod <- cmdstan_model(stan_file) ``` -When compiling the model we receive a few warnings: -```{r compile, message=FALSE} -mod <- cmdstan_model(stan_file = system.file("deprecated-logistic.stan", package = "cmdstanr")) -``` +The first warning is about using the deprecated array syntax -The first warning is about using the deprecated array syntax: -```stan +``` int y[n]; ``` -which should be replaced with the new syntax that uses the `array` keyword: -```stan + +which should be replaced with the new syntax using the `array` keyword: + +``` array[n] int y; ``` The second warning is about using the deprecated commenting symbol `#`, which should be replaced by `//`. -The last warning is about the use of the deprecated `_log` suffix for -probability density and mass functions. The suffix should be replaced -with the `_lpdf` suffix in this case, though it could also be the -`_lpmf` suffix, in case of using the deprecated `_log` suffix with -probability mass functions. +The last warning is about the use of the deprecated `_log` suffix for +probability density and mass functions. In this case the `_log` suffix should be +replaced with `_lpdf`. For probability mass functions the suffix `_lpmf` is +used. We can go and fix these issues manually or use the canonicalizer as outlined in the next section. -# Using the canonicalizer +## Using the canonicalizer The canonicalizer is available through the `canonicalize` argument of the `$format()` method of the `CmdStanModel` class. The arguments accepts -`TRUE` and `FALSE` values, in which case all or no features of the -canonicalizer are used, but it can also accept a list of character vectors that -determine which features of the canonicalizer to use. The canonincalizer in -CmdStan 2.29.2 support four features: `parentheses`, `braces`, `includes` -and `deprecations`. `parentheses`, `braces` clean up the use of parentheses and braces, -while `includes` will replace the `#include` statement with the code from -the included files. See the [canonicalizer section of the Stan User's Guide](https://mc-stan.org/docs/2_29/stan-users-guide/stanc-pretty-printing.html#canonicalizing) for -more. +`TRUE` and `FALSE` values, in which case all or none of the features of the +canonicalizer are used. It can also accept a list of character vectors that +determine which features of the canonicalizer to use. + +The canonincalizer in CmdStan 2.29.2 supports four features: `parentheses`, +`braces`, `includes` and `deprecations`. The `parentheses` and `braces` features +clean up the use of parentheses and braces, while `includes` will replace +`#include` statements with the code from the included files. See the +[canonicalizer section of the Stan User's Guide](https://mc-stan.org/docs/2_29/stan-users-guide/stanc-pretty-printing.html#canonicalizing) +for more details. In this vignette we will be using the `deprecations` feature that replaces deprecated Stan model features with non-deprecated ones if possible. -Example of use: - ```{r canonicalize, message=FALSE} mod$format(canonicalize = list("deprecations")) ``` @@ -119,13 +118,14 @@ You can also use the `$format()` method to write the updated version of the model directly to the Stan model file. That can be enabled by setting `overwrite_file = TRUE`. The previous version of the file will automatically be backed up to a file with the `.stan.bak` suffix. If that is not desired or -you are using a version system and backuping is redundant, +you are using a version system and making a backup is redundant, you can disable it by setting `backup = FALSE`: -```{r overwrite_file, eval=FALSE} +```{r overwrite_file} mod$format( canonicalize = list("deprecations"), overwrite_file = TRUE, backup = FALSE ) -``` \ No newline at end of file +mod$print() +``` From 636cfba918ed0bf9ae9dd265dc9ab6e93a95d548 Mon Sep 17 00:00:00 2001 From: jgabry Date: Wed, 13 Apr 2022 13:18:37 -0600 Subject: [PATCH 6/8] overwrite private$stan_code_ if overwrite_file=TRUE --- R/model.R | 1 + 1 file changed, 1 insertion(+) diff --git a/R/model.R b/R/model.R index c405b76d5..366980a52 100644 --- a/R/model.R +++ b/R/model.R @@ -912,6 +912,7 @@ format <- function(overwrite_file = FALSE, } } out_file <- self$stan_file() + private$stan_code_ <- run_log$stdout } cat(run_log$stdout, file = out_file, sep = "\n") From 1719851e1f8743a53b5ab5b3e656bc1aab9fbf33 Mon Sep 17 00:00:00 2001 From: jgabry Date: Wed, 13 Apr 2022 13:31:09 -0600 Subject: [PATCH 7/8] fix printing after overwriting file --- R/model.R | 4 +++- man/cmdstan_model.Rd | 2 +- vignettes/deprecations.Rmd | 2 +- 3 files changed, 5 insertions(+), 3 deletions(-) diff --git a/R/model.R b/R/model.R index 366980a52..610ba93c6 100644 --- a/R/model.R +++ b/R/model.R @@ -912,9 +912,11 @@ format <- function(overwrite_file = FALSE, } } out_file <- self$stan_file() - private$stan_code_ <- run_log$stdout } cat(run_log$stdout, file = out_file, sep = "\n") + if (isTRUE(overwrite_file)) { + private$stan_code_ <- readLines(self$stan_file()) + } invisible(TRUE) } diff --git a/man/cmdstan_model.Rd b/man/cmdstan_model.Rd index 975d9ea29..1f48d1c86 100644 --- a/man/cmdstan_model.Rd +++ b/man/cmdstan_model.Rd @@ -31,7 +31,7 @@ more. See \code{\link[=model-method-compile]{$compile()}} for details.} A \code{\link{CmdStanModel}} object. } \description{ -\if{html}{\figure{logo.png}{options: width="25"}} +\if{html}{\figure{logo.png}{options: width="25px"}} Create a new \code{\link{CmdStanModel}} object from a file containing a Stan program or from an existing Stan executable. The \code{\link{CmdStanModel}} object stores the path to a Stan program and compiled executable (once created), and provides diff --git a/vignettes/deprecations.Rmd b/vignettes/deprecations.Rmd index 3fc8fe8e6..69d43a58b 100644 --- a/vignettes/deprecations.Rmd +++ b/vignettes/deprecations.Rmd @@ -119,7 +119,7 @@ model directly to the Stan model file. That can be enabled by setting `overwrite_file = TRUE`. The previous version of the file will automatically be backed up to a file with the `.stan.bak` suffix. If that is not desired or you are using a version system and making a backup is redundant, -you can disable it by setting `backup = FALSE`: +you can disable it by setting `backup = FALSE`. ```{r overwrite_file} mod$format( From cc86f4eb5e87dbc52afe3be1ebedab6daa0b8e02 Mon Sep 17 00:00:00 2001 From: jgabry Date: Wed, 13 Apr 2022 13:36:43 -0600 Subject: [PATCH 8/8] regenerate html --- docs/articles/deprecations.html | 160 ++++++++---------- .../header-attrs-2.9/header-attrs.js | 12 ++ docs/articles/index.html | 4 +- 3 files changed, 87 insertions(+), 89 deletions(-) create mode 100644 docs/articles/deprecations_files/header-attrs-2.9/header-attrs.js diff --git a/docs/articles/deprecations.html b/docs/articles/deprecations.html index ed5a7831d..e889922a4 100644 --- a/docs/articles/deprecations.html +++ b/docs/articles/deprecations.html @@ -125,13 +125,11 @@ -
+
-

Handling deprecated Stan features with the -canonicalizer in CmdStanR

-

Rok Češnovar, Jonah -Gabry

+

Handling deprecated Stan features with the canonicalizer in CmdStanR

+

Rok Češnovar and Jonah Gabry

Source: vignettes/deprecations.Rmd @@ -144,17 +142,8 @@

Rok Češnovar, Jonah

Introduction

-

This vignette demonstrates how to handle cases where one or more -feature in your Stan model has been deprecated. For most deprecated -features, the Stan-to-C++ compiler can be used to automatically convert -to a non-deprecated feature that replaces the deprecated one. This -vignette show cases how that automatic conversion can be done using -CmdStanR.

-

The automatic conversion of deprecated features to non-deprecated -features is done by with a mode called canonicalizer, which -is part of the Stan-to-C++ compiler. We recommend using CmdStan 2.29.2 -or newer when using the canonicalizer and this vignette. The minimum -CmdStanR version to run the vignette is 0.5.0.

+

This vignette demonstrates how to handle cases where your Stan program contains deprecated features resulting in deprecation warnings. In most cases, the Stan-to-C++ compiler can be used to automatically update your code to a non-deprecated feature that replaces the deprecated one. This vignette showcases how that automatic conversion can be done using CmdStanR.

+

The automatic conversion of deprecated features to non-deprecated features is done using the so-called “canonicalizer”, which is part of the Stan-to-C++ compiler. We recommend using CmdStan 2.29.2 or later when using the canonicalizer and this vignette. The minimum CmdStanR version to run the code in the vignette is 0.5.0.

 library(cmdstanr)
 check_cmdstan_toolchain(fix = TRUE, quiet = TRUE)
@@ -162,64 +151,55 @@

Deprecation warnings

-

Consider the following simple logistic regression with parameters -alpha and beta, covariates X, and -outcome y:

-
data {
-  int<lower=1> k;
-  int<lower=0> n;
-  matrix[n, k] X;
-  int y[n];
-}
-parameters {
-  vector[k] beta;
-  real alpha;
-}
-model {
-  # priors
-  target += std_normal_log(beta);
-  alpha ~ std_normal();
-  
-  y ~ bernoulli_logit(X * beta + alpha);
-}
-

When compiling the model we receive a few warnings:

-
-mod <- cmdstan_model(stan_file = "deprecations-files/logistic.stan")
-

The first warning is about using the deprecated array syntax:

-
int y[n];
-

which should be replaced with the new syntax that uses the -array keyword:

-
array[n] int y;
-

The second warning is about using the deprecated commenting symbol -#, which should be replaced by //.

-

The last warning is about the use of the deprecated _log -suffix for probability density and mass functions. The suffix should be -replaced with the _lpdf suffix in this case, though it -could also be the _lpmf suffix, in case of using the -deprecated _log suffix with probability mass functions.

-

We can go and fix these issues manually or use the canonicalizer as -outlined in the next section.

+

The following logistic regression model uses several deprecated language features, resulting in several warnings during compilation.

+
+stan_file <- write_stan_file("
+data {
+  int<lower=1> k;
+  int<lower=0> n;
+  matrix[n, k] X;
+  int y[n];
+}
+parameters {
+  vector[k] beta;
+  real alpha;
+}
+model {
+  # priors
+  target += std_normal_log(beta);
+  alpha ~ std_normal();
+  
+  y ~ bernoulli_logit(X * beta + alpha);
+}
+")
+mod <- cmdstan_model(stan_file)
+
Warning in '/var/folders/s0/zfzm55px2nd2v__zlw5xfj2h0000gn/T/RtmplsuXnS/model-840d5c7122c.stan', line 6, column 2: Declaration
+    of arrays by placing brackets after a variable name is deprecated and
+    will be removed in Stan 2.32.0. Instead use the array keyword before the
+    type. This can be changed automatically using the auto-format flag to
+    stanc
+Warning in '/var/folders/s0/zfzm55px2nd2v__zlw5xfj2h0000gn/T/RtmplsuXnS/model-840d5c7122c.stan', line 13, column 2: Comments
+    beginning with # are deprecated and this syntax will be removed in Stan
+    2.32.0. Use // to begin line comments; this can be done automatically
+    using the auto-format flag to stanc
+Warning in '/var/folders/s0/zfzm55px2nd2v__zlw5xfj2h0000gn/T/RtmplsuXnS/model-840d5c7122c.stan', line 14, column 12: std_normal_log
+    is deprecated and will be removed in Stan 2.32.0. Use std_normal_lpdf
+    instead. This can be automatically changed using the canonicalize flag
+    for stanc
+

The first warning is about using the deprecated array syntax

+
int y[n];
+

which should be replaced with the new syntax using the array keyword:

+
array[n] int y;
+

The second warning is about using the deprecated commenting symbol #, which should be replaced by //.

+

The last warning is about the use of the deprecated _log suffix for probability density and mass functions. In this case the _log suffix should be replaced with _lpdf. For probability mass functions the suffix _lpmf is used.

+

We can go and fix these issues manually or use the canonicalizer as outlined in the next section.

-
-

-Using the canonicalizer

-

The canonicalizer is available through the canonicalize -argument of the $format() method of the -CmdStanModel class. The arguments accepts TRUE -and FALSE values, in which case all or no features of the -canonicalizer are used, but it can also accept a list of character -vectors that determine which features of the canonicalizer to use. The -canonincalizer in CmdStan 2.29.2 support four features: -parentheses, braces, includes and -deprecations. parentheses, braces -clean up the use of parentheses and braces, while includes -will replace the #include statement with the code from the -included files. See the canonicalizer -section of the Stan User’s Guide for more.

-

In this vignette we will be using the deprecations -feature that replaces deprecated Stan model features with non-deprecated -ones if possible.

-

Example of use:

+
+

+Using the canonicalizer

+

The canonicalizer is available through the canonicalize argument of the $format() method of the CmdStanModel class. The arguments accepts TRUE and FALSE values, in which case all or none of the features of the canonicalizer are used. It can also accept a list of character vectors that determine which features of the canonicalizer to use.

+

The canonincalizer in CmdStan 2.29.2 supports four features: parentheses, braces, includes and deprecations. The parentheses and braces features clean up the use of parentheses and braces, while includes will replace #include statements with the code from the included files. See the canonicalizer section of the Stan User’s Guide for more details.

+

In this vignette we will be using the deprecations feature that replaces deprecated Stan model features with non-deprecated ones if possible.

 mod$format(canonicalize = list("deprecations"))
data {
@@ -239,24 +219,32 @@ 

   
   y ~ bernoulli_logit(X * beta + alpha);
 }
-

By default, the format function will print the resulting model code. -We can see that all three issues were resolved. y is now -defined using the new array keyword, the comment uses // -and the std_normal_log() is replaced with -std_normal_lpdf().

-

You can also use the $format() method to write the -updated version of the model directly to the Stan model file. That can -be enabled by setting overwrite_file = TRUE. The previous -version of the file will automatically be backed up to a file with the -.stan.bak suffix. If that is not desired or you are using a -version system and backuping is redundant, you can disable it by setting -backup = FALSE:

+

By default, the format function will print the resulting model code. We can see that all three issues were resolved. y is now defined using the new array keyword, the comment uses // and the std_normal_log() is replaced with std_normal_lpdf().

+

You can also use the $format() method to write the updated version of the model directly to the Stan model file. That can be enabled by setting overwrite_file = TRUE. The previous version of the file will automatically be backed up to a file with the .stan.bak suffix. If that is not desired or you are using a version system and making a backup is redundant, you can disable it by setting backup = FALSE.

 mod$format(
     canonicalize = list("deprecations"),
     overwrite_file = TRUE,
     backup = FALSE
-)
+) +mod$print()
+
data {
+  int<lower=1> k;
+  int<lower=0> n;
+  matrix[n, k] X;
+  array[n] int y;
+}
+parameters {
+  vector[k] beta;
+  real alpha;
+}
+model {
+  // priors
+  target += std_normal_lpdf(beta);
+  alpha ~ std_normal();
+  
+  y ~ bernoulli_logit(X * beta + alpha);
+}

diff --git a/docs/articles/deprecations_files/header-attrs-2.9/header-attrs.js b/docs/articles/deprecations_files/header-attrs-2.9/header-attrs.js new file mode 100644 index 000000000..dd57d92e0 --- /dev/null +++ b/docs/articles/deprecations_files/header-attrs-2.9/header-attrs.js @@ -0,0 +1,12 @@ +// Pandoc 2.9 adds attributes on both header and div. We remove the former (to +// be compatible with the behavior of Pandoc < 2.8). +document.addEventListener('DOMContentLoaded', function(e) { + var hs = document.querySelectorAll("div.section[class*='level'] > :first-child"); + var i, h, a; + for (i = 0; i < hs.length; i++) { + h = hs[i]; + if (!/^h[1-6]$/i.test(h.tagName)) continue; // it should be a header h1-h6 + a = h.attributes; + while (a.length > 0) h.removeAttribute(a[0].name); + } +}); diff --git a/docs/articles/index.html b/docs/articles/index.html index bb629d2e7..4daf22f4d 100644 --- a/docs/articles/index.html +++ b/docs/articles/index.html @@ -183,9 +183,7 @@

Getting started

More details

-

More information about compilation, passing in data, how CmdStan -ouput is written to CSV and read back into R, profiling Stan programs, -running Stan on GPUs, and using CmdStanR in R Markdown documents.

+

More information about compilation, passing in data, how CmdStan ouput is written to CSV and read back into R, profiling Stan programs, running Stan on GPUs, and using CmdStanR in R Markdown documents.

How does CmdStanR work?