From fc33e8dfdc083c2a69306ea117efdf0e93bbd402 Mon Sep 17 00:00:00 2001 From: Brian Ward Date: Thu, 18 Nov 2021 10:57:28 -0500 Subject: [PATCH 1/3] Update deprecation sections to reflect new policy --- src/functions-reference/_bookdown.yml | 1 + .../deprecated_functions.Rmd | 61 +++++++++++++--- .../real-valued_basic_functions.Rmd | 10 +-- src/functions-reference/removed_functions.Rmd | 4 ++ src/reference-manual/deprecations.Rmd | 72 ++++++++++++++----- src/reference-manual/index.Rmd | 4 +- src/reference-manual/types.Rmd | 11 ++- src/stan-users-guide/using-stanc.Rmd | 16 ++--- 8 files changed, 129 insertions(+), 50 deletions(-) create mode 100644 src/functions-reference/removed_functions.Rmd diff --git a/src/functions-reference/_bookdown.yml b/src/functions-reference/_bookdown.yml index efa11c0b4..045c454af 100644 --- a/src/functions-reference/_bookdown.yml +++ b/src/functions-reference/_bookdown.yml @@ -15,6 +15,7 @@ rmd_files: [ "compound_arithmetic_and_assignment.Rmd", "higher-order_functions.Rmd", "deprecated_functions.Rmd", + "removed_functions.Rmd", "conventions_for_probability_functions.Rmd", "discrete_distributions.Rmd", "binary_distributions.Rmd", diff --git a/src/functions-reference/deprecated_functions.Rmd b/src/functions-reference/deprecated_functions.Rmd index 248ef599b..b59022bbc 100644 --- a/src/functions-reference/deprecated_functions.Rmd +++ b/src/functions-reference/deprecated_functions.Rmd @@ -1,13 +1,54 @@ # Deprecated Functions This appendix lists currently deprecated functionality along with how to -replace it. These deprecated features are likely to be removed in the future. +replace it. -```{r results='asis', echo=FALSE} -if (knitr::is_html_output()) { - cat(' * integrate_ode_rk45, integrate_ode_adams, integrate_ode_bdf ODE Integrators\n') -} -``` +Starting in Stan 2.29, deprecated functions with drop in replacements (such as +the renaming of `get_lp` or `multiply_log`) will be removed 3 versions later +e.g., functions deprecated in Stan 2.20 will be removed in Stan 2.23 and placed +in [Removed Functions]. The Stan compiler can +[automatically update](https://mc-stan.org/docs/stan-users-guide/stanc-pretty-printing.html) +these on the behalf of the user. + + + +## `multiply_log` and `binomial_coefficient_log` functions + +*Deprecated*: Currently two non-conforming functions ending in suffix + `_log`. + +*Replacement*: Replace `multiply_log(...)` with `lmultiply(...)`. + Replace `binomial_coefficient_log(...)` with `lchoose(...)`. + +*Scheduled Removal*: Stan 2.32 + + +## `get_lp()` function + +*Deprecated*: The built-in no-argument function `get_lp()` is deprecated. + +*Replacement*: Use the no-argument function `target()` instead. + +*Scheduled Removal*: Stan 2.32 + +## `abs(real x)` function + +*Deprecated*: Use of the `abs` function with real-valued arguments + is deprecated; use functions `fabs` instead. + + +## Integer division with `operator/` + +*Deprecated*: Using `/` with two integer arguments is interpreted as integer +floor division, such that + +$$ 1 / 2 = 0 $$ + +This is deprecated due to its confusion with real-valued division, where + +$$ 1.0 / 2.0 = 0.5 $$ + +*Replacement*: Use the integer division operator `operator%/%` instead. ## integrate_ode_rk45, integrate_ode_adams, integrate_ode_bdf ODE integrators {#functions-old-ode-solver} @@ -24,7 +65,7 @@ if (knitr::is_html_output()) { A system of ODEs is specified as an ordinary function in Stan within the functions block. The ODE system function must have this function signature: - + ```stan array[] real ode(real time, array[] real state, array[] real theta, array[] real x_r, array[] int x_i); @@ -117,7 +158,7 @@ are as follows. * *`ode`*: function literal referring to a function specifying the system of differential equations with signature: - + ``` (real, array[] real, array[] real, data array[] real, data array[] int):array[] real ``` @@ -140,7 +181,7 @@ derivatives with respect to time of the state, For more fine-grained control of the ODE solvers, these parameters can also be provided: - + * `data` *`rel_tol`*: relative tolerance for the ODE solver, type `real`, data only, @@ -159,7 +200,7 @@ with values consisting of solutions at the specified times. The sizes must match, and in particular, the following groups are of the same size: - + * state variables passed into the system function, derivatives returned by the system function, initial state passed into the solver, and rows of the return value of the solver, diff --git a/src/functions-reference/real-valued_basic_functions.Rmd b/src/functions-reference/real-valued_basic_functions.Rmd index c22728df4..a420a9d6d 100644 --- a/src/functions-reference/real-valued_basic_functions.Rmd +++ b/src/functions-reference/real-valued_basic_functions.Rmd @@ -386,8 +386,8 @@ display the log probability accumulator at various stages of execution to see where it becomes ill defined. [^fn_lp]: This function used to be called `get_lp()`, but that name -has been deprecated; using it will print a warning. The function -`get_lp()` will be removed in a future release. +has been deprecated; using it will print a warning. The function +`get_lp()` will be removed in Stan 2.32.0. \index{{\tt \bfseries target }!{\tt (): real}|hyperpage} @@ -402,7 +402,7 @@ Return the current value of the log probability accumulator. `real` **`get_lp`**`()`
\newline Return the current value of the log probability accumulator; **deprecated;** - use `target()` instead. -`r since("2.5")` +`r since("2.5, scheduled for removal in 2.32.0")` Both `target` and the deprecated `get_lp` act like other functions ending in `_lp`, meaning that they may only may only be used in the @@ -1275,7 +1275,7 @@ function is written as $\binom{x}{y}$ and pronounced "x choose y." This function generalizes to real numbers using the gamma function. For $0 \leq y \leq x$, \[ \mathrm{binomial\_coefficient\_log}(x,y) = \log\Gamma(x+1) - \log\Gamma(y+1) - \log\Gamma(x-y+1). \] -`r since("2.0, deprecated since 2.10")` +`r since("2.0, deprecated since 2.10, scheduled for removal in 2.32")` \index{{\tt \bfseries binomial\_coefficient\_log }!{\tt (T1 x, T2 y): R}|hyperpage} @@ -1502,7 +1502,7 @@ _**Warning:**_ This function is deprecated and should be replaced with \[ \mathrm{multiply\_log}(x,y) = \begin{cases} 0 & \text{if } x = y = 0 \\ x \log y & \text{if } x, y \neq 0 \\ \text{NaN} & \text{otherwise} \end{cases} \] -`r since("2.0, deprecated in 2.10")` +`r since("2.0, deprecated in 2.10, scheduled for removal in 2.32")` \index{{\tt \bfseries multiply\_log }!{\tt (T1 x, T2 y): R}|hyperpage} diff --git a/src/functions-reference/removed_functions.Rmd b/src/functions-reference/removed_functions.Rmd new file mode 100644 index 000000000..6ae248562 --- /dev/null +++ b/src/functions-reference/removed_functions.Rmd @@ -0,0 +1,4 @@ +# Removed Functions + +Functions which once existed in the Stan language and have since been replaced +or removed will be listed here. diff --git a/src/reference-manual/deprecations.Rmd b/src/reference-manual/deprecations.Rmd index 1681270e8..8950fe325 100644 --- a/src/reference-manual/deprecations.Rmd +++ b/src/reference-manual/deprecations.Rmd @@ -1,8 +1,16 @@ -# Deprecated Features {#deprecated-features.appendix} +# Deprecated Features This appendix lists currently deprecated functionality along with how -to replace it. These deprecated features are likely to be removed in -the next major release. +to replace it. + +Starting with Stan 2.29, minor (syntax-level) deprecations can be removed 3 +versions after release; e.g., syntax deprecated in Stan 2.20 will be removed in +Stan 2.23 and placed in [Removed Features]. The Stan compiler can +[automatically update](https://mc-stan.org/docs/stan-users-guide/stanc-pretty-printing.html) +many of these on the behalf of the user. + +Any feature which changes semantic meaning (such as the upgraded ODE solver +interface) will not be removed until a major version change (e.g. Stan 3.0). ## Assignment with `<-` @@ -21,6 +29,7 @@ a <- b; a = b; ``` +*Scheduled Removal*: Stan 2.32 ## `increment_log_prob` statement @@ -42,15 +51,18 @@ underlying log density is incremented with each element. target += u; ``` +*Scheduled Removal*: Stan 2.32 ## `get_lp()` function -*Deprecated*: The no-argument function `get_lp()` is deprecated. +*Deprecated*: The built-in no-argument function `get_lp()` is deprecated. *Replacement*: Use the no-argument function `target()` instead. +*Scheduled Removal*: Stan 2.32 + ## `_log` density and mass functions @@ -83,10 +95,10 @@ with the log probability mass function foo_lpmf(y | ...). ``` +*Scheduled Removal*: Stan 2.32 ## `cdf_log` and `ccdf_log` cumulative distribution functions - *Deprecated*: The log cumulative distribution and complementary cumulative distribution functions for a distribution `foo` are currently written as `foo_cdf_log` and `foo_ccdf_log`. @@ -95,15 +107,6 @@ currently written as `foo_cdf_log` and `foo_ccdf_log`. Replace `foo_ccdf_log(y, ...)` with `foo_lccdf(y | ...)`. -## `multiply_log` and `binomial_coefficient_log` functions - -*Deprecated*: Currently two non-conforming functions ending in suffix - `_log`. - -*Replacement*: Replace `multiply_log(...)` with `lmultiply(...)`. - Replace `binomial_coefficient_log(...)` with `lchoose(...)`. - - ## User-defined function with `_log` suffix *Deprecated*: A user-defined function ending in `_log` can @@ -123,6 +126,11 @@ target += foo_log(y, ...); functions or `_lpmf` for mass functions in the user-defined function. +*Scheduled Removal*: Stan 2.32 + +Note: Following Stan 2.32, users can stil define a function ending in `_log`, +it will just no longer have a special meaning or support the `~` syntax. + ## `lkj_cov` distribution *Deprecated*:The distribution `lkj_cov` is deprecated. @@ -155,6 +163,8 @@ block or as a transformed parameter. An even more efficient transform would use Cholesky factors rather than full correlation matrix types. +*Scheduled Removal*: Stan 3.0 or later. + ## `if_else` function *Deprecated*:The function `if_else` is deprecated. This function @@ -176,14 +186,10 @@ with x = a ? b : c; ``` -## `abs(real x)` function - -*Deprecated*: Use of the `abs` function with real-valued arguments - is deprecated; use functions `fabs` instead. +*Scheduled Removal*: Stan 2.32 ## Character `#` as comment prefix - *Deprecated*: The use of `#` for line-based comments is deprecated. From the first occurrence of `#` onward, the rest of the line is ignored. This happens after includes are resolved @@ -192,6 +198,7 @@ x = a ? b : c; *Replacement*: Use a pair of forward slashes, `//`, for line comments. +*Scheduled Removal*: Stan 2.32 ## Brackets array syntax @@ -219,3 +226,30 @@ array[3] vector[7] mu; array[15, 12] matrix[7, 2] mu; array[2, 3, 4] cholesky_factor_cov[5, 6] mu; ``` + +*Scheduled Removal*: Stan 2.32 + + +## New Keywords + +*Deprecated*: The following identifiers will become +[reserved](#reserved-names) +in the language in +the specified version + +*Replacement*: Rename any variables or functions with these names. + +| Identifier | Version | +|------------|---------| +| array | 2.32 | +| lower | 2.32 | +| upper | 2.32 | +| offset | 2.32 | +| multiplier | 2.32 | + + +## Deprecated Functions + +Several built-in Stan functions have been deprecated. Consult the +[functions reference](https://mc-stan.org/docs/functions-reference/deprecated-functions.html) +for more information. diff --git a/src/reference-manual/index.Rmd b/src/reference-manual/index.Rmd index f98eafee4..936f6f737 100644 --- a/src/reference-manual/index.Rmd +++ b/src/reference-manual/index.Rmd @@ -26,9 +26,9 @@ for evaluating the results. This manual applies to all Stan interfaces. There are two additional interface-neutral manuals, the -[*Stan Functions Reference*]((https://mc-stan.org/docs/functions-reference/index.html) +[*Stan Functions Reference*](https://mc-stan.org/docs/functions-reference/index.html) listing all the built-in functions and their signatures, -and the [*Stan User's Guide*]((https://mc-stan.org/docs/stan-users-guide/index.html) +and the [*Stan User's Guide*](https://mc-stan.org/docs/stan-users-guide/index.html) providing examples and programming techniques. There is also a separate installation and getting started guide for each interface. diff --git a/src/reference-manual/types.Rmd b/src/reference-manual/types.Rmd index 1358aadd8..802df565a 100644 --- a/src/reference-manual/types.Rmd +++ b/src/reference-manual/types.Rmd @@ -75,8 +75,7 @@ and declares `z` to be a $12 \times 8 \times 15$ array of complex numbers. Prior to 2.26 Stan models used a different syntax. The old syntax has been deprecated and is described -in [the deprecated features -chapter]{#deprecated-features.appendix}. +in the [Deprecated Features] chapter. ### Constrained data types {-} @@ -1345,7 +1344,7 @@ variables; containers of any sizes may be assigned to function arguments. The constrained matrix types `cov_matrix[K]`, `corr_matrix[K]`, `cholesky_factor_cov[K]`, and `cholesky_factor_corr[K]` are only assignable to matrices of -dimensions `matrix[K, K]` types. +dimensions `matrix[K, K]` types. +-------------------+----------------------+----------------------------------------------+ | Function Argument | Local | Block | @@ -1462,12 +1461,12 @@ dimensions `matrix[K, K]` types. Additional array types follow the same basic template as the final -example in the table and can contain any of the previous types. +example in the table and can contain any of the previous types. The unsized version of arrays with more than one dimension is specified by using commas, e.g. `array[ , ]` is a 2-D array. For more on how function arguments and return types are declared, -consult the [User's Guide chapter on +consult the [User's Guide chapter on functions](https://mc-stan.org/docs/stan-users-guide/basic-functions-section.html#type-declarations-for-functions). ## Compound variable declaration and definition @@ -1585,4 +1584,4 @@ together, so long as the constraint for each variable is the same: ```stan real x, y; -``` \ No newline at end of file +``` diff --git a/src/stan-users-guide/using-stanc.Rmd b/src/stan-users-guide/using-stanc.Rmd index 4943138fb..5ef6c31ec 100644 --- a/src/stan-users-guide/using-stanc.Rmd +++ b/src/stan-users-guide/using-stanc.Rmd @@ -83,17 +83,17 @@ in two situations 1. A completely blank Stan program will produce the following warning message ``` Warning: Empty file 'empty.stan' detected; - this is a valid stan model but likely unintended! + this is a valid stan model but likely unintended! ``` 2. The use of any [deprecated features](https://mc-stan.org/docs/reference-manual/deprecated-features-appendix.html) will lead to warnings which will look as follows ``` - Warning in 'deprecated.stan', line 2, column 2: - Comments beginning with # are deprecated. - Please use // in place of # for line comments. + Warning in 'deprecated.stan', line 2, column 0: 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 stanc + --auto-format ``` - A single Stan program can produce many warnings during compilation. @@ -681,15 +681,15 @@ Some of the changes made are: ``` will be formatted as follows - + ```stan if (cond) { #result } ``` - + and similarly for For/While loops containing a single statement. - + ### Known issues The formatting and canonicalizing features of stanc3 are still under From a2e620d8b2f6e19959aa41e8245da50133e0516e Mon Sep 17 00:00:00 2001 From: Brian Ward Date: Thu, 18 Nov 2021 11:43:11 -0500 Subject: [PATCH 2/3] Minor cleanup --- src/reference-manual/deprecations.Rmd | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/reference-manual/deprecations.Rmd b/src/reference-manual/deprecations.Rmd index 8950fe325..4e01498df 100644 --- a/src/reference-manual/deprecations.Rmd +++ b/src/reference-manual/deprecations.Rmd @@ -234,8 +234,7 @@ array[2, 3, 4] cholesky_factor_cov[5, 6] mu; *Deprecated*: The following identifiers will become [reserved](#reserved-names) -in the language in -the specified version +in the language in the specified version. *Replacement*: Rename any variables or functions with these names. From 76662d635fc1e765617bf7badc30c44531ddf33b Mon Sep 17 00:00:00 2001 From: Brian Ward Date: Thu, 18 Nov 2021 12:35:55 -0500 Subject: [PATCH 3/3] Tweaks per review --- src/functions-reference/removed_functions.Rmd | 2 ++ src/reference-manual/deprecations.Rmd | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/src/functions-reference/removed_functions.Rmd b/src/functions-reference/removed_functions.Rmd index 6ae248562..5f26c63bd 100644 --- a/src/functions-reference/removed_functions.Rmd +++ b/src/functions-reference/removed_functions.Rmd @@ -2,3 +2,5 @@ Functions which once existed in the Stan language and have since been replaced or removed will be listed here. + +As of the current version of Stan, there are no such functions. diff --git a/src/reference-manual/deprecations.Rmd b/src/reference-manual/deprecations.Rmd index 4e01498df..f567cc2fd 100644 --- a/src/reference-manual/deprecations.Rmd +++ b/src/reference-manual/deprecations.Rmd @@ -10,7 +10,7 @@ Stan 2.23 and placed in [Removed Features]. The Stan compiler can many of these on the behalf of the user. Any feature which changes semantic meaning (such as the upgraded ODE solver -interface) will not be removed until a major version change (e.g. Stan 3.0). +interface) will not be removed until a major version change (e.g., Stan 3.0). ## Assignment with `<-`