Merge pull request #864 from stan-dev/exposed-transforms

Document built-in transformation functions

Author: bob-carpenter

src/_quarto.yml

@@ -212,6 +212,7 @@ website:
             - functions-reference/mixed_operations.qmd
             - functions-reference/compound_arithmetic_and_assignment.qmd
             - functions-reference/higher-order_functions.qmd
+            - functions-reference/transform_functions.qmd
             - functions-reference/deprecated_functions.qmd
             - functions-reference/removed_functions.qmd
             - functions-reference/conventions_for_probability_functions.qmd

src/functions-reference/_quarto.yml

@@ -47,6 +47,7 @@ book:
         - mixed_operations.qmd
         - compound_arithmetic_and_assignment.qmd
         - higher-order_functions.qmd
+        - transform_functions.qmd
         - deprecated_functions.qmd
         - removed_functions.qmd
         - conventions_for_probability_functions.qmd

src/functions-reference/functions_index.qmd

@@ -378,7 +378,7 @@ For example, here is a program which recreates the existing
 
 ```stan
 functions {
-  real upper_bound_jacobian(real x, real ub) {
+  real my_upper_bound_jacobian(real x, real ub) {
     jacobian += x;
     return ub - exp(x);
   }
@@ -390,7 +390,7 @@ parameters {
   real b_raw;
 }
 transformed parameters {
-  real b = upper_bound_jacobian(b_raw, ub);
+  real b = my_upper_bound_jacobian(b_raw, ub);
 }
 model {
   // use b as if it was declared `real<upper=ub> b;` in parameters

src/functions-reference/transform_functions.qmd

@@ -17,6 +17,9 @@ This chapter provides a definition of the transforms used for each
 type of variable.   For examples of how to declare and define these
 variables in a Stan program, see section
 [Variable declaration](types.qmd#variable-declaration.section).
+To directly access the functional form of these transformations
+from inside the Stan language, see [Variable Transformation Functions](https://mc-stan.org/docs/functions-reference/transform_functions.html)
+in the _Functions Reference_.
 
 Stan converts models to C++ classes which define probability
 functions with support on all of $\mathbb{R}^K$, where $K$ is the number
@@ -459,6 +462,13 @@ p_Y(y)
 $$
 
 
+## Positive ordered vector
+
+Placeholder.
+
+The positive ordered transformation is defined in the same style
+as the ordered transformation above, but with the first element being
+exponentiated to ensure positivity.
 
 ## Zero sum vector
 
@@ -753,7 +763,7 @@ $$
 
 ## Stochastic Matrix {#stochastic-matrix-transform.section}
 
-The `column_stochastic_matrix[N, M]` and `row_stochastic_matrix[N, M]` type in
+The `column_stochastic_matrix[N, M]` and `row_stochastic_matrix[M, N]` type in
 Stan represents an $N \times M$ matrix where each column (row) is a unit simplex
 of dimension $N$. In other words, each column (row) of the matrix is a vector
 constrained to have non-negative entries that sum to one.

src/reference-manual/statements.qmd

@@ -296,7 +296,7 @@ change of variables for arbitrary parameters.
 For example, this function recreates the built-in
 `<upper=x>` transform on real numbers:
 ```stan
-real upper_bound_jacobian(real x, real ub) {
+real my_upper_bound_jacobian(real x, real ub) {
   jacobian += x;
   return ub - exp(x);
 }
@@ -306,7 +306,7 @@ It can be used as a replacement for `real<lower=ub>` as follows:
 
 ```stan
 functions {
-  // upper_bound_jacobian as above
+  // my_upper_bound_jacobian as above
 }
 data {
   real ub;
@@ -315,7 +315,7 @@ parameters {
   real b_raw;
 }
 transformed parameters {
-  real b = upper_bound_jacobian(b_raw, ub);
+  real b = my_upper_bound_jacobian(b_raw, ub);
 }
 model {
   b ~ lognormal(0, 1);