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 f51dc1032..0855e5a8d 100644 --- a/src/functions-reference/deprecated_functions.Rmd +++ b/src/functions-reference/deprecated_functions.Rmd @@ -1,19 +1,55 @@ # 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. -```{r results='asis', echo=FALSE} -if (knitr::is_html_output()) { - cat(' * cov_exp_quad\n') -} -``` ## integrate_ode_rk45, integrate_ode_adams, integrate_ode_bdf ODE Integrators {#functions-old-ode-solver} @@ -166,7 +202,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 +* 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, @@ -198,21 +234,21 @@ $$ `matrix` **`cov_exp_quad`**`(row_vectors x, real alpha, real rho)`
\newline The covariance matrix with an exponentiated quadratic kernel of x. -`r since("2.16")` +`r since("2.16, deprecated since 2.20, scheduled for removal in 2.32")` \index{{\tt \bfseries cov\_exp\_quad }!{\tt (vectors x, real alpha, real rho): matrix}|hyperpage} `matrix` **`cov_exp_quad`**`(vectors x, real alpha, real rho)`
\newline The covariance matrix with an exponentiated quadratic kernel of x. -`r since("2.16")` +`r since("2.16, deprecated since 2.20, scheduled for removal in 2.32")` \index{{\tt \bfseries cov\_exp\_quad }!{\tt (array[] real x, real alpha, real rho): matrix}|hyperpage} `matrix` **`cov_exp_quad`**`(array[] real x, real alpha, real rho)`
\newline The covariance matrix with an exponentiated quadratic kernel of x. -`r since("2.16")` +`r since("2.16, deprecated since 2.20, scheduled for removal in 2.32")` \index{{\tt \bfseries cov\_exp\_quad }!{\tt (row\_vectors x1, row\_vectors x2, real alpha, real rho): matrix}|hyperpage} @@ -220,7 +256,7 @@ The covariance matrix with an exponentiated quadratic kernel of x. `matrix` **`cov_exp_quad`**`(row_vectors x1, row_vectors x2, real alpha, real rho)`
\newline The covariance matrix with an exponentiated quadratic kernel of x1 and x2. -`r since("2.18")` +`r since("2.18, deprecated since 2.20, scheduled for removal in 2.32")` \index{{\tt \bfseries cov\_exp\_quad }!{\tt (vectors x1, vectors x2, real alpha, real rho): matrix}|hyperpage} @@ -228,7 +264,7 @@ x2. `matrix` **`cov_exp_quad`**`(vectors x1, vectors x2, real alpha, real rho)`
\newline The covariance matrix with an exponentiated quadratic kernel of x1 and x2. -`r since("2.18")` +`r since("2.18, deprecated since 2.20, scheduled for removal in 2.32")` \index{{\tt \bfseries cov\_exp\_quad }!{\tt (array[] real x1, array[] real x2, real alpha, real rho): matrix}|hyperpage} @@ -236,4 +272,4 @@ x2. `matrix` **`cov_exp_quad`**`(array[] real x1, array[] real x2, real alpha, real rho)`
\newline The covariance matrix with an exponentiated quadratic kernel of x1 and x2. -`r since("2.18")` +`r since("2.18, deprecated since 2.20, scheduled for removal in 2.32")` diff --git a/src/functions-reference/real-valued_basic_functions.Rmd b/src/functions-reference/real-valued_basic_functions.Rmd index c22728df4..a9d34c0c5 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 since 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..5f26c63bd --- /dev/null +++ b/src/functions-reference/removed_functions.Rmd @@ -0,0 +1,6 @@ +# Removed Functions + +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 1681270e8..f567cc2fd 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,29 @@ 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 ba7348c67..9c8e60d57 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