Merge pull request #625 from stan-dev/removals/2-32

[Stan 2.33] Update documentation on expiring deprecations

src/functions-reference/deprecated_functions.Rmd

@@ -8,39 +8,8 @@ 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.33
-
-
-## `fabs` function
-
-*Deprecated*: The unary function `fabs` is deprecated.
-
-*Replacement*: Use the unary function `abs` instead. Note that the return type
-for `abs` is different for integer overloads, but this replacement is safe due
-to Stan's type promotion rules.
-
-*Scheduled Removal*: Stan 2.33
+these on the behalf of the user for the entire deprecation window and at least
+one version following the removal.
 
 
 ## Integer division with `operator/`
@@ -345,65 +314,3 @@ the same size.
 
 The parameters, real data, and integer data will be passed from the
 solver directly to the system function.
-
-
-## Exponentiated quadratic covariance functions {#cov_exp_quad}
-
-These covariance functions have been replaced by those described in:
-
-```{r results='asis', echo=FALSE}
-if (knitr::is_html_output()) {
-  cat(' * <a href="gaussian-process-covariance-functions.html">Gaussian Process Covariance Functions</a>\n')
-}
-```
-
-With magnitude $\alpha$ and length scale $l$, the exponentiated quadratic kernel is:
-
-$$
-k(x_i, x_j) = \alpha^2 \exp \left(-\dfrac{1}{2\rho^2} \sum_{d=1}^D (x_{i,d} - x_{j,d})^2 \right)
-$$
-
-<!-- matrix; cov_exp_quad; (row_vectors x, real alpha, real rho); -->
-\index{{\tt \bfseries cov\_exp\_quad }!{\tt (row\_vectors x, real alpha, real rho): matrix}|hyperpage}
-
-`matrix` **`cov_exp_quad`**`(row_vectors x, real alpha, real rho)`<br>\newline
-The covariance matrix with an exponentiated quadratic kernel of x.
-`r since("2.16, deprecated since 2.20, scheduled for removal in 2.33")`
-
-<!-- matrix; cov_exp_quad; (vectors x, real alpha, real rho); -->
-\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)`<br>\newline
-The covariance matrix with an exponentiated quadratic kernel of x.
-`r since("2.16, deprecated since 2.20, scheduled for removal in 2.33")`
-
-<!-- matrix; cov_exp_quad; (array[] real x, real alpha, real rho); -->
-\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)`<br>\newline
-The covariance matrix with an exponentiated quadratic kernel of x.
-`r since("2.16, deprecated since 2.20, scheduled for removal in 2.33")`
-
-<!-- matrix; cov_exp_quad; (row_vectors x1, row_vectors x2, real alpha, real rho); -->
-\index{{\tt \bfseries cov\_exp\_quad }!{\tt (row\_vectors x1, row\_vectors x2, real alpha, real rho): matrix}|hyperpage}
-
-`matrix` **`cov_exp_quad`**`(row_vectors x1, row_vectors x2, real alpha, real rho)`<br>\newline
-The covariance matrix with an exponentiated quadratic kernel of x1 and
-x2.
-`r since("2.18, deprecated since 2.20, scheduled for removal in 2.33")`
-
-<!-- matrix; cov_exp_quad; (vectors x1, vectors x2, real alpha, real rho); -->
-\index{{\tt \bfseries cov\_exp\_quad }!{\tt (vectors x1, vectors x2, real alpha, real rho): matrix}|hyperpage}
-
-`matrix` **`cov_exp_quad`**`(vectors x1, vectors x2, real alpha, real rho)`<br>\newline
-The covariance matrix with an exponentiated quadratic kernel of x1 and
-x2.
-`r since("2.18, deprecated since 2.20, scheduled for removal in 2.33")`
-
-<!-- matrix; cov_exp_quad; (array[] real x1, array[] real x2, real alpha, real rho); -->
-\index{{\tt \bfseries cov\_exp\_quad }!{\tt (array[] real x1, array[] real x2, real alpha, real rho): matrix}|hyperpage}
-
-`matrix` **`cov_exp_quad`**`(array[] real x1, array[] real x2, real alpha, real rho)`<br>\newline
-The covariance matrix with an exponentiated quadratic kernel of x1 and
-x2.
-`r since("2.18, deprecated since 2.20, scheduled for removal in 2.33")`

src/functions-reference/real-valued_basic_functions.Rmd

@@ -380,14 +380,11 @@ value returned by the Stan program.
 
 Stan provides a special built-in function `target()` that takes no
 arguments and returns the current value of the log probability
-accumulator.[^fn_lp]  This function is primarily useful for debugging
+accumulator. This function is primarily useful for debugging
 purposes, where for instance, it may be used with a print statement to
 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 Stan 2.33.0.
 
 <!-- real; target; (); -->
 \index{{\tt \bfseries target }!{\tt (): real}|hyperpage}
@@ -396,17 +393,8 @@ has been deprecated; using it will print a warning.  The function
 Return the current value of the log probability accumulator.
 `r since("2.10")`
 
-<!-- real; get_lp; (); -->
-\index{{\tt \bfseries get\_lp }!{\tt (): real}|hyperpage}
-
-`real` **`get_lp`**`()`<br>\newline
-Return the current value of the log probability accumulator;
-**deprecated;** - use `target()` instead.
-`r since("2.5, scheduled for removal in 2.33.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
-model block.
+`target` acts like a function ending in `_lp`, meaning that it may only may only
+be used in the model block.
 
 ## Logical functions
 
@@ -724,13 +712,6 @@ of those types, `abs` returns the same type where each element has had its
 absolute value taken.
 `r since("2.0, vectorized in 2.30")`
 
-<!-- R; fabs; (T x); -->
-\index{{\tt \bfseries fabs }!{\tt (T x): R}|hyperpage}
-
-`R` **`fabs`**`(T x)`<br>\newline
-absolute value of x
-`r since("2.0, vectorized in 2.13, deprecated in 2.30")`
-
 <!-- real; fdim; (real x, real y); -->
 \index{{\tt \bfseries fdim }!{\tt (real x, real y): real}|hyperpage}
 
@@ -1317,26 +1298,6 @@ defined for positive a and nonnegative z. \[ \mathrm{gamma\_q}(a,z) =
 Vectorized implementation of the `gamma_q` function
 `r since("2.25")`
 
-<!-- real; binomial_coefficient_log; (real x, real y); -->
-\index{{\tt \bfseries binomial\_coefficient\_log }!{\tt (real x, real y): real}|hyperpage}
-
-`real` **`binomial_coefficient_log`**`(real x, real y)`<br>\newline
-_**Warning:**_ This function is deprecated and should be replaced with
-`lchoose`. Return the natural logarithm of the binomial coefficient of
-x and y. For non-negative integer inputs, the binomial coefficient
-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, scheduled for removal in 2.33")`
-
-<!-- R; binomial_coefficient_log; (T1 x, T2 y); -->
-\index{{\tt \bfseries binomial\_coefficient\_log }!{\tt (T1 x, T2 y): R}|hyperpage}
-
-`R` **`binomial_coefficient_log`**`(T1 x, T2 y)`<br>\newline
-Vectorized implementation of the `binomial_coefficient_log` function
-`r since("2.25")`
-
 <!-- int; choose; (int x, int y); -->
 \index{{\tt \bfseries choose }!{\tt (int x, int y): int}|hyperpage}
 
@@ -1546,24 +1507,6 @@ Return z plus the result of x multiplied by y. \[ \text{fma}(x,y,z) =
 (x \times y) + z \]
 `r since("2.0")`
 
-<!-- real; multiply_log; (real x, real y); -->
-\index{{\tt \bfseries multiply\_log }!{\tt (real x, real y): real}|hyperpage}
-
-`real` **`multiply_log`**`(real x, real y)`<br>\newline
-_**Warning:**_ This function is deprecated and should be replaced with
-`lmultiply`. Return the product of x and the natural logarithm of y.
-\[ \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 since 2.10, scheduled for removal in 2.33")`
-
-<!-- R; multiply_log; (T1 x, T2 y); -->
-\index{{\tt \bfseries multiply\_log }!{\tt (T1 x, T2 y): R}|hyperpage}
-
-`R` **`multiply_log`**`(T1 x, T2 y)`<br>\newline
-Vectorized implementation of the `multiply_log` function
-`r since("2.25")`
-
 <!-- real; ldexp; (real x, int y); -->
 \index{{\tt \bfseries ldexp }!{\tt (real x, int y): real}|hyperpage}
 

src/functions-reference/removed_functions.Rmd

@@ -1,6 +1,96 @@
 # Removed Functions
 
 Functions which once existed in the Stan language and have since been replaced
-or removed will be listed here.
+or removed are listed here.
 
-As of the current version of Stan, there are no such functions.
+
+## `multiply_log` and `binomial_coefficient_log` functions
+
+*Removed*: Currently two non-conforming functions ending in suffix
+  `_log`.
+
+*Replacement*: Replace `multiply_log(...)` with `lmultiply(...)`.
+ Replace `binomial_coefficient_log(...)` with `lchoose(...)`.
+
+*Removed In*: Stan 2.33
+
+
+## `get_lp()` function
+
+*Removed*: The built-in no-argument function `get_lp()` is deprecated.
+
+*Replacement*: Use the no-argument function `target()` instead.
+
+*Removed In*: Stan 2.33
+
+## `fabs` function
+
+*Removed*: The unary function `fabs` is deprecated.
+
+*Replacement*: Use the unary function `abs` instead. Note that the return type
+for `abs` is different for integer overloads, but this replacement is safe due
+to Stan's type promotion rules.
+
+*Removed In*: Stan 2.33
+
+
+## Exponentiated quadratic covariance functions {#cov_exp_quad}
+
+These covariance functions have been replaced by those described in:
+
+```{r results='asis', echo=FALSE}
+if (knitr::is_html_output()) {
+  cat(' * <a href="gaussian-process-covariance-functions.html">Gaussian Process Covariance Functions</a>\n')
+}
+```
+
+With magnitude $\alpha$ and length scale $l$, the exponentiated quadratic kernel is:
+
+$$
+k(x_i, x_j) = \alpha^2 \exp \left(-\dfrac{1}{2\rho^2} \sum_{d=1}^D (x_{i,d} - x_{j,d})^2 \right)
+$$
+
+<!-- matrix; cov_exp_quad; (row_vectors x, real alpha, real rho); -->
+\index{{\tt \bfseries cov\_exp\_quad }!{\tt (row\_vectors x, real alpha, real rho): matrix}|hyperpage}
+
+`matrix` **`cov_exp_quad`**`(row_vectors x, real alpha, real rho)`<br>\newline
+The covariance matrix with an exponentiated quadratic kernel of x.
+`r since("2.16, deprecated since 2.20, removed in in 2.33")`
+
+<!-- matrix; cov_exp_quad; (vectors x, real alpha, real rho); -->
+\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)`<br>\newline
+The covariance matrix with an exponentiated quadratic kernel of x.
+`r since("2.16, deprecated since 2.20, removed in in 2.33")`
+
+<!-- matrix; cov_exp_quad; (array[] real x, real alpha, real rho); -->
+\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)`<br>\newline
+The covariance matrix with an exponentiated quadratic kernel of x.
+`r since("2.16, deprecated since 2.20, removed in in 2.33")`
+
+<!-- matrix; cov_exp_quad; (row_vectors x1, row_vectors x2, real alpha, real rho); -->
+\index{{\tt \bfseries cov\_exp\_quad }!{\tt (row\_vectors x1, row\_vectors x2, real alpha, real rho): matrix}|hyperpage}
+
+`matrix` **`cov_exp_quad`**`(row_vectors x1, row_vectors x2, real alpha, real rho)`<br>\newline
+The covariance matrix with an exponentiated quadratic kernel of x1 and
+x2.
+`r since("2.18, deprecated since 2.20, removed in in 2.33")`
+
+<!-- matrix; cov_exp_quad; (vectors x1, vectors x2, real alpha, real rho); -->
+\index{{\tt \bfseries cov\_exp\_quad }!{\tt (vectors x1, vectors x2, real alpha, real rho): matrix}|hyperpage}
+
+`matrix` **`cov_exp_quad`**`(vectors x1, vectors x2, real alpha, real rho)`<br>\newline
+The covariance matrix with an exponentiated quadratic kernel of x1 and
+x2.
+`r since("2.18, deprecated since 2.20, removed in in 2.33")`
+
+<!-- matrix; cov_exp_quad; (array[] real x1, array[] real x2, real alpha, real rho); -->
+\index{{\tt \bfseries cov\_exp\_quad }!{\tt (array[] real x1, array[] real x2, real alpha, real rho): matrix}|hyperpage}
+
+`matrix` **`cov_exp_quad`**`(array[] real x1, array[] real x2, real alpha, real rho)`<br>\newline
+The covariance matrix with an exponentiated quadratic kernel of x1 and
+x2.
+`r since("2.18, deprecated since 2.20, removed in in 2.33")`