From fd3d31b453015fae857c739c7d95e66ee767bd8c Mon Sep 17 00:00:00 2001 From: Brian Ward Date: Tue, 18 Mar 2025 16:17:45 -0400 Subject: [PATCH 1/3] Start working on transforms documentation --- src/_quarto.yml | 1 + src/functions-reference/_quarto.yml | 1 + src/functions-reference/functions_index.qmd | 225 ++++++++++ .../transform_functions.qmd | 384 ++++++++++++++++++ src/reference-manual/statements.qmd | 4 +- src/stan-users-guide/user-functions.qmd | 6 +- 6 files changed, 616 insertions(+), 5 deletions(-) create mode 100644 src/functions-reference/transform_functions.qmd diff --git a/src/_quarto.yml b/src/_quarto.yml index 0a641af0b..a202fded4 100644 --- a/src/_quarto.yml +++ b/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 diff --git a/src/functions-reference/_quarto.yml b/src/functions-reference/_quarto.yml index f3c4b0675..bc6e83acb 100644 --- a/src/functions-reference/_quarto.yml +++ b/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 diff --git a/src/functions-reference/functions_index.qmd b/src/functions-reference/functions_index.qmd index abb0de6cf..9c286b136 100644 --- a/src/functions-reference/functions_index.qmd +++ b/src/functions-reference/functions_index.qmd @@ -599,6 +599,36 @@ pagetitle: Alphabetical Index -
[`(matrix A) : matrix`](matrix_operations.qmd#index-entry-a7eaa217876baa0054d78dfff05f5685ef6261bb) (matrix_operations.html)
+**cholesky_factor_corr_constrain**: + + -
[`(vectors y, int K) : matrices`](transform_functions.qmd#index-entry-13178bf49e47f4d98c973800329f95f8fd49bfa1) (transform_functions.html)
+ + +**cholesky_factor_corr_jacobian**: + + -
[`(vectors y, int K) : matrices`](transform_functions.qmd#index-entry-1e720292cb09512b6fdca84e4cc39a087f43ec0a) (transform_functions.html)
+ + +**cholesky_factor_corr_unconstrain**: + + -
[`(matrices x) : vectors`](transform_functions.qmd#index-entry-98b8008a7ecf84ed0131fe5e84c2a239b3739d30) (transform_functions.html)
+ + +**cholesky_factor_cov_constrain**: + + -
[`(vectors y, int N, int M) : matrices`](transform_functions.qmd#index-entry-2d79251581281da7f1d0374b5eee9dcc9f45b531) (transform_functions.html)
+ + +**cholesky_factor_cov_jacobian**: + + -
[`(vectors y, int N, int M) : matrices`](transform_functions.qmd#index-entry-1d85ce3dc05fdfabac696a15f6c4d76726e873da) (transform_functions.html)
+ + +**cholesky_factor_cov_unconstrain**: + + -
[`(matrices x) : vectors`](transform_functions.qmd#index-entry-74c3b28f5b00bf51f6299872cce7f2b1a18bf3ac) (transform_functions.html)
+ + **choose**: -
[`(int x, int y) : int`](real-valued_basic_functions.qmd#index-entry-fd4d9124ce89bf38a7ca1601e28f14947fcae3ba) (real-valued_basic_functions.html)
@@ -665,6 +695,21 @@ pagetitle: Alphabetical Index -
[`(Z z) : Z`](complex-valued_basic_functions.qmd#index-entry-17692d922273aaba0c5317617aab6585dda28bfa) (complex-valued_basic_functions.html)
+**corr_matrix_constrain**: + + -
[`(vectors y, int K) : matrices`](transform_functions.qmd#index-entry-594161bab69b742477ec84f4a399816cc0d939a1) (transform_functions.html)
+ + +**corr_matrix_jacobian**: + + -
[`(vectors y, int K) : matrices`](transform_functions.qmd#index-entry-a3ce311c60e3c6821b434df3f73f83c5e037a03b) (transform_functions.html)
+ + +**corr_matrix_unconstrain**: + + -
[`(matrices x) : vectors`](transform_functions.qmd#index-entry-0fcba057e29e1ae091121cb62708675880f50c39) (transform_functions.html)
+ + **cos**: -
[`(complex z) : complex`](complex-valued_basic_functions.qmd#index-entry-3d86aa681cf64514f405ada706ad9969e5f33080) (complex-valued_basic_functions.html)
@@ -687,6 +732,21 @@ pagetitle: Alphabetical Index -
[`(vectors x1, vectors x2, real alpha, real rho) : matrix`](removed_functions.qmd#index-entry-70b15de7e29e4e64f05ca3fc552da349d4a66c1f) (removed_functions.html)
+**cov_matrix_constrain**: + + -
[`(vectors y, int K) : matrices`](transform_functions.qmd#index-entry-6dc98b07eda2e6dfde0020cf98dae68b590aad28) (transform_functions.html)
+ + +**cov_matrix_jacobian**: + + -
[`(vectors y, int K) : matrices`](transform_functions.qmd#index-entry-cad2be5fc2ee16a8419b70db0422629b843de6c3) (transform_functions.html)
+ + +**cov_matrix_unconstrain**: + + -
[`(matrices x) : vectors`](transform_functions.qmd#index-entry-00d19b2a52626d58b6b07f2d27fdd2dbad3c12c0) (transform_functions.html)
+ + **crossprod**: -
[`(matrix x) : matrix`](matrix_operations.qmd#index-entry-c5372c9d5715e11b5d87a465d6d671d608ef9513) (matrix_operations.html)
@@ -1853,6 +1913,36 @@ pagetitle: Alphabetical Index -
[`(reals mu, reals sigma) : R`](positive_continuous_distributions.qmd#index-entry-ea103d5de1264a7df987cedd3cb455d3302557af) (positive_continuous_distributions.html)
+**lower_bound_constrain**: + + -
[`(reals y, reals l) : reals`](transform_functions.qmd#index-entry-236441f9d40cf0949226403711061cb387db43de) (transform_functions.html)
+ + +**lower_bound_jacobian**: + + -
[`(reals y, reals l) : reals`](transform_functions.qmd#index-entry-8b830436d4cfd285a8b3abfa92585fd670a1538f) (transform_functions.html)
+ + +**lower_bound_unconstrain**: + + -
[`(reals x, reals l) : reals`](transform_functions.qmd#index-entry-1fed1e6f5d90930463a64e7e8483dadc5cf2b394) (transform_functions.html)
+ + +**lower_upper_bound_constrain**: + + -
[`(reals y, reals l, reals u) : reals`](transform_functions.qmd#index-entry-1545a300be6300bd526ef940efc1a478106d2224) (transform_functions.html)
+ + +**lower_upper_bound_jacobian**: + + -
[`(reals y, reals l, reals u) : reals`](transform_functions.qmd#index-entry-5959c7191ca70019d809bb0a18a63c49ace9eab0) (transform_functions.html)
+ + +**lower_upper_bound_unconstrain**: + + -
[`(reals x, reals l, reals y) : reals`](transform_functions.qmd#index-entry-d5fd8e155f784d39e502b34df89f720e9527b8a1) (transform_functions.html)
+ + ## M **machine_precision**: @@ -2425,6 +2515,21 @@ pagetitle: Alphabetical Index -
[`(function ode, vector initial_state, real initial_time, array[] real times, data real rel_tol, data real abs_tol, int max_num_steps, ...) : array[] vector`](higher-order_functions.qmd#index-entry-1fd0eab9e49603406a50ad94820da2fb10dec2bc) (higher-order_functions.html)
+**offset_multiplier_constrain**: + + -
[`(reals y, reals offset, reals mult) : reals`](transform_functions.qmd#index-entry-c55eb604debca345fb51ad9d71cb36b6f20bb60e) (transform_functions.html)
+ + +**offset_multiplier_jacobian**: + + -
[`(reals y, reals offset, reals mult) : reals`](transform_functions.qmd#index-entry-2448386d5029a2ea68a25d2eac851459f98eb968) (transform_functions.html)
+ + +**offset_multiplier_unconstrain**: + + -
[`(reals x, reals offset, reals mult) : reals`](transform_functions.qmd#index-entry-6ed536361121ffb486071705925b0107a779e401) (transform_functions.html)
+ + **one_hot_array**: -
[`(int n, int k) : array[] real`](matrix_operations.qmd#index-entry-268289da1aa3a477c94f93562ea8dec0d09ca486) (matrix_operations.html)
@@ -2759,6 +2864,16 @@ pagetitle: Alphabetical Index -
[`(real x, real y) : int`](real-valued_basic_functions.qmd#index-entry-d1b0b32e522a6d270bdccaa3b56f1dfaef2dfa1f) (real-valued_basic_functions.html)
+**ordered_constrain**: + + -
[`(vectors y) : vectors`](transform_functions.qmd#index-entry-ef08c8144bb3789c27d35f7a7c30cd57f8a9a573) (transform_functions.html)
+ + +**ordered_jacobian**: + + -
[`(vectors y) : vectors`](transform_functions.qmd#index-entry-6372fc8ee07f534b79aa45d152097a421af0a938) (transform_functions.html)
+ + **ordered_logistic**: -
[distribution statement](bounded_discrete_distributions.qmd#index-entry-2bffcaec141463bcf3650a49ab910f0e9b02c0b0) (bounded_discrete_distributions.html)
@@ -2817,6 +2932,11 @@ pagetitle: Alphabetical Index -
[`(real eta, vector c) : int`](bounded_discrete_distributions.qmd#index-entry-ce1eb98cf9c98edbf6d662f465f30c9816c1d6fe) (bounded_discrete_distributions.html)
+**ordered_unconstrain**: + + -
[`(vectors x) : vectors`](transform_functions.qmd#index-entry-66bebbbf4a16907781a03d7910e05157b57546ae) (transform_functions.html)
+ + **owens_t**: -
[`(real h, real a) : real`](real-valued_basic_functions.qmd#index-entry-1ebaab3f9c8786de6e45b245eb0557156a1b2a77) (real-valued_basic_functions.html)
@@ -3000,6 +3120,21 @@ pagetitle: Alphabetical Index -
[`() : real`](real-valued_basic_functions.qmd#index-entry-21afff517501f022247efe89c81a255a74533422) (real-valued_basic_functions.html)
+**positive_ordered_constrain**: + + -
[`(vectors y) : vectors`](transform_functions.qmd#index-entry-a5bd3aeff6187e7710c5c9aede0aa53b0bf05605) (transform_functions.html)
+ + +**positive_ordered_jacobian**: + + -
[`(vectors y) : vectors`](transform_functions.qmd#index-entry-72ae38a185968521d676ce568e4dd9dfb0ec3211) (transform_functions.html)
+ + +**positive_ordered_unconstrain**: + + -
[`(vectors x) : vectors`](transform_functions.qmd#index-entry-ea0b4a03eff5caa57b2d154df97f2c8a63b820e5) (transform_functions.html)
+ + **pow**: -
[`(complex x, complex y) : complex`](complex-valued_basic_functions.qmd#index-entry-a687c481b458dcd50e13b27c0423402b6332fc08) (complex-valued_basic_functions.html)
@@ -3289,6 +3424,21 @@ pagetitle: Alphabetical Index -
[`(vector v, int i, int n) : vector`](matrix_operations.qmd#index-entry-71cb7ac02f1e74f4b6fff77caa9b5ef0bd15346a) (matrix_operations.html)
+**simplex_constrain**: + + -
[`(vector y) : vector`](transform_functions.qmd#index-entry-3e22ee2a51803d957f375b3f5e55b1cabe890c4e) (transform_functions.html)
+ + +**simplex_jacobian**: + + -
[`(vector y) : vector`](transform_functions.qmd#index-entry-66d0300aa5ac5570ba501e9e1ce12d1671674f9f) (transform_functions.html)
+ + +**simplex_unconstrain**: + + -
[`(vector x) : vector`](transform_functions.qmd#index-entry-dd2e5ceedad5808827ce616fbbe24360727b6b2b) (transform_functions.html)
+ + **sin**: -
[`(complex z) : complex`](complex-valued_basic_functions.qmd#index-entry-13f23f848a721cdfa87c2d1f4b4067cb9df6911e) (complex-valued_basic_functions.html)
@@ -3501,6 +3651,36 @@ pagetitle: Alphabetical Index -
[`(real x) : real`](real-valued_basic_functions.qmd#index-entry-b5b8e03f66b31507dac3535af6f2d8f615e4a3af) (real-valued_basic_functions.html)
+**stochastic_column_constrain**: + + -
[`(matrices y) : matrices`](transform_functions.qmd#index-entry-4dbd1cdc02cc83f417b72d0ce15257683589e66c) (transform_functions.html)
+ + +**stochastic_column_jacobian**: + + -
[`(matrices y) : matrices`](transform_functions.qmd#index-entry-a21e88d79c0bb4cc8424754bfac7f0bfada0be42) (transform_functions.html)
+ + +**stochastic_column_unconstrain**: + + -
[`(matrices x) : matrices`](transform_functions.qmd#index-entry-a04a2804c70fb0fe2219a7d11244837772f7d404) (transform_functions.html)
+ + +**stochastic_row_constrain**: + + -
[`(matrices y) : matrices`](transform_functions.qmd#index-entry-e2ce12f9782fbeb39c70aa822e3b8a5d4ef4baf8) (transform_functions.html)
+ + +**stochastic_row_jacobian**: + + -
[`(matrices y) : matrices`](transform_functions.qmd#index-entry-b4c7ad92b82702ad1209da8fa540ff52110b0bf0) (transform_functions.html)
+ + +**stochastic_row_unconstrain**: + + -
[`(matrices x) : matrices`](transform_functions.qmd#index-entry-4bf40767700b7e2fc07e1045d565df3dc93422ee) (transform_functions.html)
+ + **student_t**: -
[distribution statement](unbounded_continuous_distributions.qmd#index-entry-2483b90edc6356f6ed17c209456b226b1bc0099b) (unbounded_continuous_distributions.html)
@@ -3561,6 +3741,21 @@ pagetitle: Alphabetical Index -
[`(vector x) : real`](matrix_operations.qmd#index-entry-a3848926d02b63042a5cca7f5f2114a98d5a3b54) (matrix_operations.html)
+**sum_to_zero_constrain**: + + -
[`(vectors y) : vectors`](transform_functions.qmd#index-entry-6c0d205ee6463bcaa0673c8d9607d2ca20bf2860) (transform_functions.html)
+ + +**sum_to_zero_jacobian**: + + -
[`(vectors y) : vectors`](transform_functions.qmd#index-entry-aeaf42b6a6102bf306ab44b353d64e75c52f5867) (transform_functions.html)
+ + +**sum_to_zero_unconstrain**: + + -
[`(vectors x) : vectors`](transform_functions.qmd#index-entry-43bd9130545904d1b8cea836c9621a69cd06f361) (transform_functions.html)
+ + **svd**: -
[`(complex_matrix A) : tuple(complex_matrix, vector, complex_matrix)`](complex_matrix_operations.qmd#index-entry-250461905ab5c8f3351131c12e8ea6f1b3e68795) (complex_matrix_operations.html)
@@ -3783,6 +3978,36 @@ pagetitle: Alphabetical Index -
[`(int n) : vector`](matrix_operations.qmd#index-entry-2dec8337a5bdb9528da444f890d895306c7de4e2) (matrix_operations.html)
+**unit_vectors_constrain**: + + -
[`(vectors y) : vectors`](transform_functions.qmd#index-entry-3e7ebedc4498436d0a2336970080bf855c52eaa7) (transform_functions.html)
+ + +**unit_vectors_jacobian**: + + -
[`(vectors y) : vectors`](transform_functions.qmd#index-entry-dad75a5d7cfa2f707b43c61f4208876d4f1ff189) (transform_functions.html)
+ + +**unit_vectors_unconstrain**: + + -
[`(vectors x) : vectors`](transform_functions.qmd#index-entry-8030393eb30e7d856eced92680f3c9e8454c19d2) (transform_functions.html)
+ + +**upper_bound_constrain**: + + -
[`(reals y, reals u) : reals`](transform_functions.qmd#index-entry-53375a5789505642682018f4c331597652f14194) (transform_functions.html)
+ + +**upper_bound_jacobian**: + + -
[`(reals x, reals u) : reals`](transform_functions.qmd#index-entry-0d83614a1071769ccb6a725cee97458ec29e649b) (transform_functions.html)
+ + +**upper_bound_unconstrain**: + + -
[`(reals x, reals u) : reals`](transform_functions.qmd#index-entry-b911cf1f15054b02c6816d632d19879ff32e7a31) (transform_functions.html)
+ + ## V **variance**: diff --git a/src/functions-reference/transform_functions.qmd b/src/functions-reference/transform_functions.qmd new file mode 100644 index 000000000..9fc2ce034 --- /dev/null +++ b/src/functions-reference/transform_functions.qmd @@ -0,0 +1,384 @@ +--- +pagetitle: Variable Transformation Functions +--- + +# Variable Transformation Functions + +These functions provide direct access to the ability to +constrain and unconstrain variables using the built-in transformations +as defined in the [Stan Reference Manual](https://mc-stan.org/docs/reference-manual/transforms.html). + +For each of the built-in variable transforms, there are 3 functions exposed. A +`_constrain` function that maps from free variables to constrained variables (the "inverse transform"), +a `_unconstrain` function that maps from the constrained space back to free variables (the "transform"), +and a [`_jacobian` function](https://mc-stan.org/docs/reference-manual/statements.html#increment-log-density-with-a-change-of-variables-adjustment), +which computes the same value as the `_constrain` function while also +incrementing the target with the relevant change of variables adjustment. + +For this page, variables named `y` are unconstrained, while variables named `x` +are in the constrained space. The unconstraining functions will cause rejections +if their input is not properly in the constrained space. + +## Transforms for scalars + +Note: It is possible to use these transforms with arrays and other containers like `vector`s. +This results in elementwise application of the transform. + +### Lower bounds + + +\index{{\tt \bfseries lower\_bound\_constrain }!{\tt (reals y, reals l): reals}|hyperpage} + +`reals` **`lower_bound_constrain`**`(reals y, reals l)`
\newline + +{{< since 2.37 >}} + + +\index{{\tt \bfseries lower\_bound\_jacobian }!{\tt (reals y, reals l): reals}|hyperpage} + +`reals` **`lower_bound_jacobian`**`(reals y, reals l)`
\newline + +{{< since 2.37 >}} + + +\index{{\tt \bfseries lower\_bound\_unconstrain }!{\tt (reals x, reals l): reals}|hyperpage} + +`reals` **`lower_bound_unconstrain`**`(reals x, reals l)`
\newline + +{{< since 2.37 >}} + +### Upper Bounds + + +\index{{\tt \bfseries upper\_bound\_constrain }!{\tt (reals y, reals u): reals}|hyperpage} + +`reals` **`upper_bound_constrain`**`(reals y, reals u)`
\newline + +{{< since 2.37 >}} + + +\index{{\tt \bfseries upper\_bound\_jacobian }!{\tt (reals x, reals u): reals}|hyperpage} + +`reals` **`upper_bound_jacobian`**`(reals x, reals u)`
\newline + +{{< since 2.37 >}} + + +\index{{\tt \bfseries upper\_bound\_unconstrain }!{\tt (reals x, reals u): reals}|hyperpage} + +`reals` **`upper_bound_unconstrain`**`(reals x, reals u)`
\newline + +{{< since 2.37 >}} + +### Upper and lower bounds + + +\index{{\tt \bfseries lower\_upper\_bound\_constrain }!{\tt (reals y, reals l, reals u): reals}|hyperpage} + +`reals` **`lower_upper_bound_constrain`**`(reals y, reals l, reals u)`
\newline + +{{< since 2.37 >}} + + +\index{{\tt \bfseries lower\_upper\_bound\_jacobian }!{\tt (reals y, reals l, reals u): reals}|hyperpage} + +`reals` **`lower_upper_bound_jacobian`**`(reals y, reals l, reals u)`
\newline + +{{< since 2.37 >}} + +\index{{\tt \bfseries lower\_upper\_bound\_unconstrain }!{\tt (reals x, reals l, reals y): reals}|hyperpage} + +`reals` **`lower_upper_bound_unconstrain`**`(reals x, reals l, reals y)`
\newline + +{{< since 2.37 >}} + +### Affine transforms + + +\index{{\tt \bfseries offset\_multiplier\_constrain }!{\tt (reals y, reals offset, reals mult): reals}|hyperpage} + +`reals` **`offset_multiplier_constrain`**`(reals y, reals offset, reals mult)`
\newline + +{{< since 2.37 >}} + + +\index{{\tt \bfseries offset\_multiplier\_jacobian }!{\tt (reals y, reals offset, reals mult): reals}|hyperpage} + +`reals` **`offset_multiplier_jacobian`**`(reals y, reals offset, reals mult)`
\newline + +{{< since 2.37 >}} + + +\index{{\tt \bfseries offset\_multiplier\_unconstrain }!{\tt (reals x, reals offset, reals mult): reals}|hyperpage} + +`reals` **`offset_multiplier_unconstrain`**`(reals x, reals offset, reals mult)`
\newline + +{{< since 2.37 >}} + +## Transforms for constrained vectors + +These functions constrain entire vectors. Note that +this ocassionally leads to a change in length, which will be +noted in the documentation for the relevant functions. + +Where `vectors` is used, this indicates that either a `vector` +or a (possibly multidimensional) array of `vector`s may be +provided. The array will be processed element by element. + +### Ordered vectors + + +\index{{\tt \bfseries ordered\_constrain }!{\tt (vectors y): vectors}|hyperpage} + +`vectors` **`ordered_constrain`**`(vectors y)`
\newline + +{{< since 2.37 >}} + + +\index{{\tt \bfseries ordered\_jacobian }!{\tt (vectors y): vectors}|hyperpage} + +`vectors` **`ordered_jacobian`**`(vectors y)`
\newline + +{{< since 2.37 >}} + + +\index{{\tt \bfseries ordered\_unconstrain }!{\tt (vectors x): vectors}|hyperpage} + +`vectors` **`ordered_unconstrain`**`(vectors x)`
\newline + +{{< since 2.37 >}} + +### Positive order vectors + + +\index{{\tt \bfseries positive\_ordered\_constrain }!{\tt (vectors y): vectors}|hyperpage} + +`vectors` **`positive_ordered_constrain`**`(vectors y)`
\newline + +{{< since 2.37 >}} + + +\index{{\tt \bfseries positive\_ordered\_jacobian }!{\tt (vectors y): vectors}|hyperpage} + +`vectors` **`positive_ordered_jacobian`**`(vectors y)`
\newline + +{{< since 2.37 >}} + + +\index{{\tt \bfseries positive\_ordered\_unconstrain }!{\tt (vectors x): vectors}|hyperpage} + +`vectors` **`positive_ordered_unconstrain`**`(vectors x)`
\newline + +{{< since 2.37 >}} + +### Simplices + + +\index{{\tt \bfseries simplex\_constrain }!{\tt (vector y): vector}|hyperpage} + +`vector` **`simplex_constrain`**`(vector y)`
\newline + +{{< since 2.37 >}} + + +\index{{\tt \bfseries simplex\_jacobian }!{\tt (vector y): vector}|hyperpage} + +`vector` **`simplex_jacobian`**`(vector y)`
\newline + +{{< since 2.37 >}} + + +\index{{\tt \bfseries simplex\_unconstrain }!{\tt (vector x): vector}|hyperpage} + +`vector` **`simplex_unconstrain`**`(vector x)`
\newline + +{{< since 2.37 >}} + +### Zero-sum vectors + + +\index{{\tt \bfseries sum\_to\_zero\_constrain }!{\tt (vectors y): vectors}|hyperpage} + +`vectors` **`sum_to_zero_constrain`**`(vectors y)`
\newline + +{{< since 2.37 >}} + + +\index{{\tt \bfseries sum\_to\_zero\_jacobian }!{\tt (vectors y): vectors}|hyperpage} + +`vectors` **`sum_to_zero_jacobian`**`(vectors y)`
\newline + +{{< since 2.37 >}} + + +\index{{\tt \bfseries sum\_to\_zero\_unconstrain }!{\tt (vectors x): vectors}|hyperpage} + +`vectors` **`sum_to_zero_unconstrain`**`(vectors x)`
\newline + +{{< since 2.37 >}} + +### Unit vectors + + +\index{{\tt \bfseries unit\_vectors\_constrain }!{\tt (vectors y): vectors}|hyperpage} + +`vectors` **`unit_vectors_constrain`**`(vectors y)`
\newline + +{{< since 2.37 >}} + + +\index{{\tt \bfseries unit\_vectors\_jacobian }!{\tt (vectors y): vectors}|hyperpage} + +`vectors` **`unit_vectors_jacobian`**`(vectors y)`
\newline + +{{< since 2.37 >}} + + +\index{{\tt \bfseries unit\_vectors\_unconstrain }!{\tt (vectors x): vectors}|hyperpage} + +`vectors` **`unit_vectors_unconstrain`**`(vectors x)`
\newline + +{{< since 2.37 >}} + +## Transforms for constrained matrices + +Similarly to the above, `vectors` means a `vector` or array thereof, +and `matrices` means a `matrix` or array thereof. + +### Cholesky factors of correlation matrices + + +\index{{\tt \bfseries cholesky\_factor\_corr\_constrain }!{\tt (vectors y, int K): matrices}|hyperpage} + +`matrices` **`cholesky_factor_corr_constrain`**`(vectors y, int K)`
\newline + +{{< since 2.37 >}} + + +\index{{\tt \bfseries cholesky\_factor\_corr\_jacobian }!{\tt (vectors y, int K): matrices}|hyperpage} + +`matrices` **`cholesky_factor_corr_jacobian`**`(vectors y, int K)`
\newline + +{{< since 2.37 >}} + + +\index{{\tt \bfseries cholesky\_factor\_corr\_unconstrain }!{\tt (matrices x): vectors}|hyperpage} + +`vectors` **`cholesky_factor_corr_unconstrain`**`(matrices x)`
\newline + +{{< since 2.37 >}} + +### Cholesky factors of covariance matrices + + +\index{{\tt \bfseries cholesky\_factor\_cov\_constrain }!{\tt (vectors y, int N, int M): matrices}|hyperpage} + +`matrices` **`cholesky_factor_cov_constrain`**`(vectors y, int N, int M)`
\newline + +{{< since 2.37 >}} + + +\index{{\tt \bfseries cholesky\_factor\_cov\_jacobian }!{\tt (vectors y, int N, int M): matrices}|hyperpage} + +`matrices` **`cholesky_factor_cov_jacobian`**`(vectors y, int N, int M)`
\newline + +{{< since 2.37 >}} + + +\index{{\tt \bfseries cholesky\_factor\_cov\_unconstrain }!{\tt (matrices x): vectors}|hyperpage} + +`vectors` **`cholesky_factor_cov_unconstrain`**`(matrices x)`
\newline + +{{< since 2.37 >}} + +### Correlation matrices + + +\index{{\tt \bfseries corr\_matrix\_constrain }!{\tt (vectors y, int K): matrices}|hyperpage} + +`matrices` **`corr_matrix_constrain`**`(vectors y, int K)`
\newline + +{{< since 2.37 >}} + + +\index{{\tt \bfseries corr\_matrix\_jacobian }!{\tt (vectors y, int K): matrices}|hyperpage} + +`matrices` **`corr_matrix_jacobian`**`(vectors y, int K)`
\newline + +{{< since 2.37 >}} + + +\index{{\tt \bfseries corr\_matrix\_unconstrain }!{\tt (matrices x): vectors}|hyperpage} + +`vectors` **`corr_matrix_unconstrain`**`(matrices x)`
\newline + +{{< since 2.37 >}} + +### Covariance matrices + + +\index{{\tt \bfseries cov\_matrix\_constrain }!{\tt (vectors y, int K): matrices}|hyperpage} + +`matrices` **`cov_matrix_constrain`**`(vectors y, int K)`
\newline + +{{< since 2.37 >}} + + +\index{{\tt \bfseries cov\_matrix\_jacobian }!{\tt (vectors y, int K): matrices}|hyperpage} + +`matrices` **`cov_matrix_jacobian`**`(vectors y, int K)`
\newline + +{{< since 2.37 >}} + + +\index{{\tt \bfseries cov\_matrix\_unconstrain }!{\tt (matrices x): vectors}|hyperpage} + +`vectors` **`cov_matrix_unconstrain`**`(matrices x)`
\newline + +{{< since 2.37 >}} + +### Column-stochastic matrices + + +\index{{\tt \bfseries stochastic\_column\_constrain }!{\tt (matrices y): matrices}|hyperpage} + +`matrices` **`stochastic_column_constrain`**`(matrices y)`
\newline + +{{< since 2.37 >}} + + +\index{{\tt \bfseries stochastic\_column\_jacobian }!{\tt (matrices y): matrices}|hyperpage} + +`matrices` **`stochastic_column_jacobian`**`(matrices y)`
\newline + +{{< since 2.37 >}} + + +\index{{\tt \bfseries stochastic\_column\_unconstrain }!{\tt (matrices x): matrices}|hyperpage} + +`matrices` **`stochastic_column_unconstrain`**`(matrices x)`
\newline + +{{< since 2.37 >}} + +### Row-stochastic matrices + + +\index{{\tt \bfseries stochastic\_row\_constrain }!{\tt (matrices y): matrices}|hyperpage} + +`matrices` **`stochastic_row_constrain`**`(matrices y)`
\newline + +{{< since 2.37 >}} + + +\index{{\tt \bfseries stochastic\_row\_jacobian }!{\tt (matrices y): matrices}|hyperpage} + +`matrices` **`stochastic_row_jacobian`**`(matrices y)`
\newline + +{{< since 2.37 >}} + + +\index{{\tt \bfseries stochastic\_row\_unconstrain }!{\tt (matrices x): matrices}|hyperpage} + +`matrices` **`stochastic_row_unconstrain`**`(matrices x)`
\newline + +{{< since 2.37 >}} diff --git a/src/reference-manual/statements.qmd b/src/reference-manual/statements.qmd index b44ad928a..2779d637a 100644 --- a/src/reference-manual/statements.qmd +++ b/src/reference-manual/statements.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 b;` in parameters diff --git a/src/stan-users-guide/user-functions.qmd b/src/stan-users-guide/user-functions.qmd index 554ffa77b..dba3de65e 100644 --- a/src/stan-users-guide/user-functions.qmd +++ b/src/stan-users-guide/user-functions.qmd @@ -296,7 +296,7 @@ change of variables for arbitrary parameters. For example, this function recreates the built-in `` 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` 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); From fad38d0afb93045b76792cab0abbf42c66c02334 Mon Sep 17 00:00:00 2001 From: Brian Ward Date: Wed, 19 Mar 2025 15:11:01 -0400 Subject: [PATCH 2/3] Skeleton complete --- src/functions-reference/functions_index.qmd | 10 +- .../transform_functions.qmd | 233 +++++++++++++++--- src/reference-manual/transforms.qmd | 12 +- 3 files changed, 209 insertions(+), 46 deletions(-) diff --git a/src/functions-reference/functions_index.qmd b/src/functions-reference/functions_index.qmd index 9c286b136..1f2011502 100644 --- a/src/functions-reference/functions_index.qmd +++ b/src/functions-reference/functions_index.qmd @@ -616,12 +616,12 @@ pagetitle: Alphabetical Index **cholesky_factor_cov_constrain**: - -
[`(vectors y, int N, int M) : matrices`](transform_functions.qmd#index-entry-2d79251581281da7f1d0374b5eee9dcc9f45b531) (transform_functions.html)
+ -
[`(vectors y, int M, int N) : matrices`](transform_functions.qmd#index-entry-0cddde7e0aa5cc9213f393acebb3b13b68b7bfa8) (transform_functions.html)
**cholesky_factor_cov_jacobian**: - -
[`(vectors y, int N, int M) : matrices`](transform_functions.qmd#index-entry-1d85ce3dc05fdfabac696a15f6c4d76726e873da) (transform_functions.html)
+ -
[`(vectors y, int M, int N) : matrices`](transform_functions.qmd#index-entry-fd1e2249d8d133c4bf9d8e6b44f67c9c69314da3) (transform_functions.html)
**cholesky_factor_cov_unconstrain**: @@ -3426,17 +3426,17 @@ pagetitle: Alphabetical Index **simplex_constrain**: - -
[`(vector y) : vector`](transform_functions.qmd#index-entry-3e22ee2a51803d957f375b3f5e55b1cabe890c4e) (transform_functions.html)
+ -
[`(vectors y) : vectors`](transform_functions.qmd#index-entry-055048ff4bc60482699857e7993258efc99d45f0) (transform_functions.html)
**simplex_jacobian**: - -
[`(vector y) : vector`](transform_functions.qmd#index-entry-66d0300aa5ac5570ba501e9e1ce12d1671674f9f) (transform_functions.html)
+ -
[`(vectors y) : vectors`](transform_functions.qmd#index-entry-446c0a0a855c1f82fe5f0df51dddf43419abd15f) (transform_functions.html)
**simplex_unconstrain**: - -
[`(vector x) : vector`](transform_functions.qmd#index-entry-dd2e5ceedad5808827ce616fbbe24360727b6b2b) (transform_functions.html)
+ -
[`(vectors x) : vectors`](transform_functions.qmd#index-entry-ffa2ad29148676e3139f6d81a3fba15199481f30) (transform_functions.html)
**sin**: diff --git a/src/functions-reference/transform_functions.qmd b/src/functions-reference/transform_functions.qmd index 9fc2ce034..620538358 100644 --- a/src/functions-reference/transform_functions.qmd +++ b/src/functions-reference/transform_functions.qmd @@ -21,15 +21,23 @@ if their input is not properly in the constrained space. ## Transforms for scalars +These transformations take unconstrained values on the real number line and +either restrict them to part of it or shift and scale their values. Note: It is possible to use these transforms with arrays and other containers like `vector`s. -This results in elementwise application of the transform. +This results in elementwise application of the transform. If the `y` argument is +a container, the others must be either scalars or containers of exactly the same size. ### Lower bounds +These functions perform the mathematical transform described in the +[Lower Bounded Scalar section](https://mc-stan.org/docs/reference-manual/transforms.html#lower-bound-transform.section). + \index{{\tt \bfseries lower\_bound\_constrain }!{\tt (reals y, reals l): reals}|hyperpage} `reals` **`lower_bound_constrain`**`(reals y, reals l)`
\newline +Takes a value `y` and lower bound `l` and returns a corresponding value +which is greater than `l` (except for the possibility of numeric precision issues). {{< since 2.37 >}} @@ -37,82 +45,114 @@ This results in elementwise application of the transform. \index{{\tt \bfseries lower\_bound\_jacobian }!{\tt (reals y, reals l): reals}|hyperpage} `reals` **`lower_bound_jacobian`**`(reals y, reals l)`
\newline +Takes a value `y` and lower bound `l` and returns a corresponding value +which is greater than `l` (except for the possibility of numeric precision issues). +This function also increments the `target` variable +with the corresponding change of variables adjustment. {{< since 2.37 >}} \index{{\tt \bfseries lower\_bound\_unconstrain }!{\tt (reals x, reals l): reals}|hyperpage} `reals` **`lower_bound_unconstrain`**`(reals x, reals l)`
\newline - +Takes a value `x` which is greater than `l` and returns the corresponding +unconstrained value. {{< since 2.37 >}} -### Upper Bounds +### Upper bounds + +These functions perform the mathematical transform described in the +[Upper Bounded Scalar section](https://mc-stan.org/docs/reference-manual/transforms.html#upper-bounded-scalar). \index{{\tt \bfseries upper\_bound\_constrain }!{\tt (reals y, reals u): reals}|hyperpage} `reals` **`upper_bound_constrain`**`(reals y, reals u)`
\newline - +Takes a value `y` and upper bound `u` and returns a corresponding value +which is less than `u` (except for the possibility of numeric precision issues). {{< since 2.37 >}} \index{{\tt \bfseries upper\_bound\_jacobian }!{\tt (reals x, reals u): reals}|hyperpage} `reals` **`upper_bound_jacobian`**`(reals x, reals u)`
\newline +Takes a value `y` and upper bound `u` and returns a corresponding value +which is less than `u` (except for the possibility of numeric precision issues). +This function also increments the `target` variable +with the corresponding change of variables adjustment. {{< since 2.37 >}} \index{{\tt \bfseries upper\_bound\_unconstrain }!{\tt (reals x, reals u): reals}|hyperpage} `reals` **`upper_bound_unconstrain`**`(reals x, reals u)`
\newline - +Takes a value `x` which is less than `u` and returns the corresponding +unconstrained value. {{< since 2.37 >}} ### Upper and lower bounds +These functions perform the mathematical transform described in the +[Lower and Upper Bounded Scalar section](https://mc-stan.org/docs/reference-manual/transforms.html#logit-transform-jacobian.section). + \index{{\tt \bfseries lower\_upper\_bound\_constrain }!{\tt (reals y, reals l, reals u): reals}|hyperpage} `reals` **`lower_upper_bound_constrain`**`(reals y, reals l, reals u)`
\newline - +Takes a value `y`, lower bound `l`, and upper bound `u` and returns a corresponding value +which is bounded between `l` and `u` (except for the possibility of numeric precision issues). {{< since 2.37 >}} \index{{\tt \bfseries lower\_upper\_bound\_jacobian }!{\tt (reals y, reals l, reals u): reals}|hyperpage} `reals` **`lower_upper_bound_jacobian`**`(reals y, reals l, reals u)`
\newline +Takes a value `y`, lower bound `l`, and upper bound `u` and returns a corresponding value +which is bounded between `l` and `u` (except for the possibility of numeric precision issues). +This function also increments the `target` variable +with the corresponding change of variables adjustment. {{< since 2.37 >}} \index{{\tt \bfseries lower\_upper\_bound\_unconstrain }!{\tt (reals x, reals l, reals y): reals}|hyperpage} `reals` **`lower_upper_bound_unconstrain`**`(reals x, reals l, reals y)`
\newline - +Takes a value `x` which is bounded between `l` and `u` and returns returns the corresponding +unconstrained value. {{< since 2.37 >}} ### Affine transforms +These functions perform the mathematical transform described in the +[Affinely Transformed Scalar section](https://mc-stan.org/docs/reference-manual/transforms.html#affinely-transformed-scalar). + \index{{\tt \bfseries offset\_multiplier\_constrain }!{\tt (reals y, reals offset, reals mult): reals}|hyperpage} `reals` **`offset_multiplier_constrain`**`(reals y, reals offset, reals mult)`
\newline - +Takes a value `y`, shift `offset`, and scale `mult` and returns a shifted +and re-scaled value. {{< since 2.37 >}} \index{{\tt \bfseries offset\_multiplier\_jacobian }!{\tt (reals y, reals offset, reals mult): reals}|hyperpage} `reals` **`offset_multiplier_jacobian`**`(reals y, reals offset, reals mult)`
\newline +Takes a value `y`, shift `offset`, and scale `mult` and returns a shifted +and re-scaled value. +This function also increments the `target` variable +with the corresponding change of variables adjustment. {{< since 2.37 >}} \index{{\tt \bfseries offset\_multiplier\_unconstrain }!{\tt (reals x, reals offset, reals mult): reals}|hyperpage} `reals` **`offset_multiplier_unconstrain`**`(reals x, reals offset, reals mult)`
\newline - +Takes a value `x`, shift `offset`, and scale `mult` and a value which has been un-scaled +and un-shifted. {{< since 2.37 >}} ## Transforms for constrained vectors @@ -127,117 +167,172 @@ provided. The array will be processed element by element. ### Ordered vectors +These functions perform the mathematical transform described in the +[Ordered Vector section](https://mc-stan.org/docs/reference-manual/transforms.html#ordered-vector). + \index{{\tt \bfseries ordered\_constrain }!{\tt (vectors y): vectors}|hyperpage} `vectors` **`ordered_constrain`**`(vectors y)`
\newline - +Takes a free vector `y` and returns a vector such that each element is smaller +than the next. {{< since 2.37 >}} \index{{\tt \bfseries ordered\_jacobian }!{\tt (vectors y): vectors}|hyperpage} `vectors` **`ordered_jacobian`**`(vectors y)`
\newline +Takes a free vector `y` and returns a vector such that each element is smaller +than the next. +This function also increments the `target` variable +with the corresponding change of variables adjustment. {{< since 2.37 >}} \index{{\tt \bfseries ordered\_unconstrain }!{\tt (vectors x): vectors}|hyperpage} `vectors` **`ordered_unconstrain`**`(vectors x)`
\newline - +Takes an ordered vector `x` and returns the corresponding free vector. {{< since 2.37 >}} ### Positive order vectors +These functions perform the mathematical transform described in the +[Positive Ordered Vector section](https://mc-stan.org/docs/reference-manual/transforms.html#positive-ordered-vector). + \index{{\tt \bfseries positive\_ordered\_constrain }!{\tt (vectors y): vectors}|hyperpage} `vectors` **`positive_ordered_constrain`**`(vectors y)`
\newline - +Takes a free vector `y` and returns a vector such that each element is positive and +smaller than its successor. {{< since 2.37 >}} \index{{\tt \bfseries positive\_ordered\_jacobian }!{\tt (vectors y): vectors}|hyperpage} `vectors` **`positive_ordered_jacobian`**`(vectors y)`
\newline +Takes a free vector `y` and returns a vector such that each element is positive and +smaller than its successor. +This function also increments the `target` variable +with the corresponding change of variables adjustment. {{< since 2.37 >}} \index{{\tt \bfseries positive\_ordered\_unconstrain }!{\tt (vectors x): vectors}|hyperpage} `vectors` **`positive_ordered_unconstrain`**`(vectors x)`
\newline - +Takes an ordered vector `x` with positive entries and returns the corresponding free vector. {{< since 2.37 >}} ### Simplices - -\index{{\tt \bfseries simplex\_constrain }!{\tt (vector y): vector}|hyperpage} +These functions perform the mathematical transform described in the +[Unit Simplex section](https://mc-stan.org/docs/reference-manual/transforms.html#simplex-transform.section). + + +\index{{\tt \bfseries simplex\_constrain }!{\tt (vectors y): vectors}|hyperpage} -`vector` **`simplex_constrain`**`(vector y)`
\newline +`vectors` **`simplex_constrain`**`(vectors y)`
\newline +Takes a free vector `y` and returns a simplex (a vector such that each element +is between `0` and `1`, and the sum of the elements is `1`). +This returned vector will have one extra element compared to the input `y`. {{< since 2.37 >}} - -\index{{\tt \bfseries simplex\_jacobian }!{\tt (vector y): vector}|hyperpage} + +\index{{\tt \bfseries simplex\_jacobian }!{\tt (vectors y): vectors}|hyperpage} -`vector` **`simplex_jacobian`**`(vector y)`
\newline +`vectors` **`simplex_jacobian`**`(vectors y)`
\newline +Takes a free vector `y` and returns a simplex (a vector such that each element +is between `0` and `1`, and the sum of the elements is `1`). +This returned vector will have one extra element compared to the input `y`. + +This function also increments the `target` variable +with the corresponding change of variables adjustment. {{< since 2.37 >}} - -\index{{\tt \bfseries simplex\_unconstrain }!{\tt (vector x): vector}|hyperpage} + +\index{{\tt \bfseries simplex\_unconstrain }!{\tt (vectors x): vectors}|hyperpage} -`vector` **`simplex_unconstrain`**`(vector x)`
\newline +`vectors` **`simplex_unconstrain`**`(vectors x)`
\newline +Takes a simplex `x` and returns the corresponding free vector. +This returned vector will have one fewer elements compared to the input `x`. {{< since 2.37 >}} ### Zero-sum vectors +These functions perform the mathematical transform described in the +[Zero Sum Vector section](https://mc-stan.org/docs/reference-manual/transforms.html#zero-sum-vector). + \index{{\tt \bfseries sum\_to\_zero\_constrain }!{\tt (vectors y): vectors}|hyperpage} `vectors` **`sum_to_zero_constrain`**`(vectors y)`
\newline +Takes a free vector `y` and returns a vector such that the elements +sum to `0`. +This returned vector will have one extra element compared to the input `y`. {{< since 2.37 >}} \index{{\tt \bfseries sum\_to\_zero\_jacobian }!{\tt (vectors y): vectors}|hyperpage} `vectors` **`sum_to_zero_jacobian`**`(vectors y)`
\newline +Takes a free vector `y` and returns a vector such that the elements +sum to `0`. +The returned vector will have one extra element compared to the input `y`. + +This function also increments the `target` variable +with the corresponding change of variables adjustment. {{< since 2.37 >}} \index{{\tt \bfseries sum\_to\_zero\_unconstrain }!{\tt (vectors x): vectors}|hyperpage} `vectors` **`sum_to_zero_unconstrain`**`(vectors x)`
\newline +Takes a vector `x` with elements that sum to `0` and returns the +corresponding free vector. +This returned vector will have one fewer elements compared to the input `x`. {{< since 2.37 >}} ### Unit vectors +These functions perform the mathematical transform described in the +[Unit Vector section](https://mc-stan.org/docs/reference-manual/transforms.html#unit-vector.section). + \index{{\tt \bfseries unit\_vectors\_constrain }!{\tt (vectors y): vectors}|hyperpage} `vectors` **`unit_vectors_constrain`**`(vectors y)`
\newline - +Takes a free vector `y` and returns a vector with Euclidian length `1`, e.g. +`norm2(unit_vectors_constrain(y)) == 1` for any `y` that has a positive +and finite norm itself. Note that, in particular, this function rejects +if given a vector of all zeros. {{< since 2.37 >}} \index{{\tt \bfseries unit\_vectors\_jacobian }!{\tt (vectors y): vectors}|hyperpage} `vectors` **`unit_vectors_jacobian`**`(vectors y)`
\newline +Takes a free vector `y` and returns a vector with Euclidian length `1`. +This function rejects if given a vector of all zeros. +This function also increments the `target` variable +with the corresponding change of variables adjustment. {{< since 2.37 >}} \index{{\tt \bfseries unit\_vectors\_unconstrain }!{\tt (vectors x): vectors}|hyperpage} `vectors` **`unit_vectors_unconstrain`**`(vectors x)`
\newline - +Takes a vector `x` of unit length and returns the corresponding free vector. {{< since 2.37 >}} ## Transforms for constrained matrices @@ -247,16 +342,25 @@ and `matrices` means a `matrix` or array thereof. ### Cholesky factors of correlation matrices + +These functions perform the mathematical transform described in the +[Cholesky Factors of Correlation Matrices section](https://mc-stan.org/docs/reference-manual/transforms.html#cholesky-factors-of-correlation-matrices). + \index{{\tt \bfseries cholesky\_factor\_corr\_constrain }!{\tt (vectors y, int K): matrices}|hyperpage} `matrices` **`cholesky_factor_corr_constrain`**`(vectors y, int K)`
\newline - +Takes a vector `y` and integer `K`, where `length(y) == choose(K, 2)`, and returns +a `K` by `K` Cholesky factor of a correlation matrix. {{< since 2.37 >}} \index{{\tt \bfseries cholesky\_factor\_corr\_jacobian }!{\tt (vectors y, int K): matrices}|hyperpage} +Takes a vector `y` and integer `K`, where `length(y) == choose(K, 2)`, and returns +a `K` by `K` Cholesky factor of a correlation matrix. +This function also increments the `target` variable +with the corresponding change of variables adjustment. `matrices` **`cholesky_factor_corr_jacobian`**`(vectors y, int K)`
\newline {{< since 2.37 >}} @@ -265,120 +369,169 @@ and `matrices` means a `matrix` or array thereof. \index{{\tt \bfseries cholesky\_factor\_corr\_unconstrain }!{\tt (matrices x): vectors}|hyperpage} `vectors` **`cholesky_factor_corr_unconstrain`**`(matrices x)`
\newline - +Takes `x`, a lower triangular square ($K$ by $K$) matrix which is the Cholesky factor of a correlation matrix, +and returns a corresponding free vector of length $K\choose 2$. {{< since 2.37 >}} ### Cholesky factors of covariance matrices - -\index{{\tt \bfseries cholesky\_factor\_cov\_constrain }!{\tt (vectors y, int N, int M): matrices}|hyperpage} +These functions perform the mathematical transform described in the +[Cholesky Factors of Covariance Matrices section](https://mc-stan.org/docs/reference-manual/transforms.html#cholesky-factors-of-covariance-matrices). -`matrices` **`cholesky_factor_cov_constrain`**`(vectors y, int N, int M)`
\newline + +\index{{\tt \bfseries cholesky\_factor\_cov\_constrain }!{\tt (vectors y, int M, int N): matrices}|hyperpage} +`matrices` **`cholesky_factor_cov_constrain`**`(vectors y, int M, int N)`
\newline +Takes a free vector `y` and integers `M` and `N` and returns the `M` by `N` Cholesky +factor of a covariance matrix. Note that `y` must have length `N + choose(N, 2) + (M - N) * N`, +and `M` must be greater than or equal to `N`. {{< since 2.37 >}} - -\index{{\tt \bfseries cholesky\_factor\_cov\_jacobian }!{\tt (vectors y, int N, int M): matrices}|hyperpage} + +\index{{\tt \bfseries cholesky\_factor\_cov\_jacobian }!{\tt (vectors y, int M, int N): matrices}|hyperpage} -`matrices` **`cholesky_factor_cov_jacobian`**`(vectors y, int N, int M)`
\newline +`matrices` **`cholesky_factor_cov_jacobian`**`(vectors y, int M, int N)`
\newline +Takes a free vector `y` and integers `M` and `N` and returns the `M` by `N` Cholesky +factor of a covariance matrix. Note that `y` must have length `N + choose(N, 2) + (M - N) * N`, +and `M` must be greater than or equal to `N`. +This function also increments the `target` variable +with the corresponding change of variables adjustment. {{< since 2.37 >}} \index{{\tt \bfseries cholesky\_factor\_cov\_unconstrain }!{\tt (matrices x): vectors}|hyperpage} `vectors` **`cholesky_factor_cov_unconstrain`**`(matrices x)`
\newline +Takes a $M$ by $N$ Cholesky factor of a covariance matrix `x` and returns +the corresponding free vector of length $N + N\choose 2 + (M - N)N$. {{< since 2.37 >}} ### Correlation matrices +These functions perform the mathematical transform described in the +[Correlation Matrices section](https://mc-stan.org/docs/reference-manual/transforms.html#correlation-matrix-transform.section). + \index{{\tt \bfseries corr\_matrix\_constrain }!{\tt (vectors y, int K): matrices}|hyperpage} `matrices` **`corr_matrix_constrain`**`(vectors y, int K)`
\newline - +Takes a vector `y` and integer `K`, where `length(y) == choose(K, 2)`, and returns +a `K` by `K` correlation matrix. {{< since 2.37 >}} \index{{\tt \bfseries corr\_matrix\_jacobian }!{\tt (vectors y, int K): matrices}|hyperpage} `matrices` **`corr_matrix_jacobian`**`(vectors y, int K)`
\newline +Takes a vector `y` and integer `K`, where `length(y) == choose(K, 2)`, and returns +a `K` by `K` correlation matrix. +This function also increments the `target` variable +with the corresponding change of variables adjustment. {{< since 2.37 >}} \index{{\tt \bfseries corr\_matrix\_unconstrain }!{\tt (matrices x): vectors}|hyperpage} `vectors` **`corr_matrix_unconstrain`**`(matrices x)`
\newline - +Takes a $K$ by $K$ correlation matrix `x` and returns the corresponding +free vector of size $K\choose 2$. {{< since 2.37 >}} ### Covariance matrices +These functions perform the mathematical transform described in the +[Covariance Matrices section](https://mc-stan.org/docs/reference-manual/transforms.html#covariance-matrices). + \index{{\tt \bfseries cov\_matrix\_constrain }!{\tt (vectors y, int K): matrices}|hyperpage} `matrices` **`cov_matrix_constrain`**`(vectors y, int K)`
\newline - +Takes a vector `y` and integer `K`, where `length(y) == K + choose(K, 2)`, and returns +a `K` by `K` covariance matrix. {{< since 2.37 >}} \index{{\tt \bfseries cov\_matrix\_jacobian }!{\tt (vectors y, int K): matrices}|hyperpage} `matrices` **`cov_matrix_jacobian`**`(vectors y, int K)`
\newline +Takes a vector `y` and integer `K`, where `length(y) == K + choose(K, 2)`, and returns +a `K` by `K` covariance matrix. +This function also increments the `target` variable +with the corresponding change of variables adjustment. {{< since 2.37 >}} \index{{\tt \bfseries cov\_matrix\_unconstrain }!{\tt (matrices x): vectors}|hyperpage} `vectors` **`cov_matrix_unconstrain`**`(matrices x)`
\newline - +Takes a $K$ by $K$ covariance matrix `x` and returns the corresponding +free vector of size $K + K\choose 2$. {{< since 2.37 >}} ### Column-stochastic matrices +These functions perform the mathematical transform described in the +[Stochastic Matrix section](https://mc-stan.org/docs/reference-manual/transforms.html#stochastic-matrix-transform.section). + \index{{\tt \bfseries stochastic\_column\_constrain }!{\tt (matrices y): matrices}|hyperpage} `matrices` **`stochastic_column_constrain`**`(matrices y)`
\newline - +Takes a free matrix `y` of size $N$ by $M$ and returns a left stochastic matrix +(a matrix where each column is a simplex) of size $N+1$ by $M$. {{< since 2.37 >}} \index{{\tt \bfseries stochastic\_column\_jacobian }!{\tt (matrices y): matrices}|hyperpage} `matrices` **`stochastic_column_jacobian`**`(matrices y)`
\newline +Takes a free matrix `y` of size $N$ by $M$ and returns a left stochastic matrix +(a matrix where each column is a simplex) of size $N+1$ by $M$. +This function also increments the `target` variable +with the corresponding change of variables adjustment. {{< since 2.37 >}} \index{{\tt \bfseries stochastic\_column\_unconstrain }!{\tt (matrices x): matrices}|hyperpage} `matrices` **`stochastic_column_unconstrain`**`(matrices x)`
\newline - +Takes a left stochastic matrix `x` of size $N+1$ by $M$ and returns the corresponding +free matrix of size $N$ by $M$. {{< since 2.37 >}} ### Row-stochastic matrices +These functions perform the mathematical transform described in the +[Stochastic Matrix section](https://mc-stan.org/docs/reference-manual/transforms.html#stochastic-matrix-transform.section). + \index{{\tt \bfseries stochastic\_row\_constrain }!{\tt (matrices y): matrices}|hyperpage} `matrices` **`stochastic_row_constrain`**`(matrices y)`
\newline - +Takes a free matrix `y` of size $N$ by $M$ and returns a right stochastic matrix +(a matrix where each row is a simplex) of size $N$ by $M+1$. {{< since 2.37 >}} \index{{\tt \bfseries stochastic\_row\_jacobian }!{\tt (matrices y): matrices}|hyperpage} `matrices` **`stochastic_row_jacobian`**`(matrices y)`
\newline +Takes a free matrix `y` of size $N$ by $M$ and returns a right stochastic matrix +(a matrix where each row is a simplex) of size $N$ by $M+1$. +This function also increments the `target` variable +with the corresponding change of variables adjustment. {{< since 2.37 >}} \index{{\tt \bfseries stochastic\_row\_unconstrain }!{\tt (matrices x): matrices}|hyperpage} `matrices` **`stochastic_row_unconstrain`**`(matrices x)`
\newline - +Takes a right stochastic matrix `x` of size $N$ by $M+1$ and returns the corresponding +free matrix of size $N$ by $M$. {{< since 2.37 >}} diff --git a/src/reference-manual/transforms.qmd b/src/reference-manual/transforms.qmd index e40392511..85083fadd 100644 --- a/src/reference-manual/transforms.qmd +++ b/src/reference-manual/transforms.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. From 949aa23ee491025ffcfea278e1829bfc5db9e517 Mon Sep 17 00:00:00 2001 From: Brian Ward Date: Thu, 20 Mar 2025 09:57:13 -0400 Subject: [PATCH 3/3] Changes per review --- src/functions-reference/functions_index.qmd | 18 +- .../transform_functions.qmd | 290 +++++++++--------- 2 files changed, 162 insertions(+), 146 deletions(-) diff --git a/src/functions-reference/functions_index.qmd b/src/functions-reference/functions_index.qmd index 1f2011502..ebfa0de5d 100644 --- a/src/functions-reference/functions_index.qmd +++ b/src/functions-reference/functions_index.qmd @@ -1915,32 +1915,32 @@ pagetitle: Alphabetical Index **lower_bound_constrain**: - -
[`(reals y, reals l) : reals`](transform_functions.qmd#index-entry-236441f9d40cf0949226403711061cb387db43de) (transform_functions.html)
+ -
[`(reals y, reals lb) : reals`](transform_functions.qmd#index-entry-e152c4494a196c9bd932faad21a3555c712d102c) (transform_functions.html)
**lower_bound_jacobian**: - -
[`(reals y, reals l) : reals`](transform_functions.qmd#index-entry-8b830436d4cfd285a8b3abfa92585fd670a1538f) (transform_functions.html)
+ -
[`(reals y, reals lb) : reals`](transform_functions.qmd#index-entry-dda4a6ffc09ae6ffec4218c092003fea973c174e) (transform_functions.html)
**lower_bound_unconstrain**: - -
[`(reals x, reals l) : reals`](transform_functions.qmd#index-entry-1fed1e6f5d90930463a64e7e8483dadc5cf2b394) (transform_functions.html)
+ -
[`(reals x, reals lb) : reals`](transform_functions.qmd#index-entry-d178c95f782831ea0616fdc58b25d16826f98164) (transform_functions.html)
**lower_upper_bound_constrain**: - -
[`(reals y, reals l, reals u) : reals`](transform_functions.qmd#index-entry-1545a300be6300bd526ef940efc1a478106d2224) (transform_functions.html)
+ -
[`(reals y, reals lb, reals ub) : reals`](transform_functions.qmd#index-entry-d44d27ade0aed4fc8aa29d480aa1cbd767281f72) (transform_functions.html)
**lower_upper_bound_jacobian**: - -
[`(reals y, reals l, reals u) : reals`](transform_functions.qmd#index-entry-5959c7191ca70019d809bb0a18a63c49ace9eab0) (transform_functions.html)
+ -
[`(reals y, reals lb, reals ub) : reals`](transform_functions.qmd#index-entry-fa7585cac2eb147a254907e9aacffb346393c41e) (transform_functions.html)
**lower_upper_bound_unconstrain**: - -
[`(reals x, reals l, reals y) : reals`](transform_functions.qmd#index-entry-d5fd8e155f784d39e502b34df89f720e9527b8a1) (transform_functions.html)
+ -
[`(reals x, reals lb, reals ub) : reals`](transform_functions.qmd#index-entry-da54a8c2ddfb181210e40b0e47d122f16713af86) (transform_functions.html)
@@ -3995,17 +3995,17 @@ pagetitle: Alphabetical Index **upper_bound_constrain**: - -
[`(reals y, reals u) : reals`](transform_functions.qmd#index-entry-53375a5789505642682018f4c331597652f14194) (transform_functions.html)
+ -
[`(reals y, reals ub) : reals`](transform_functions.qmd#index-entry-762c88752de52b0a7df91820157122b1ddd4e9f1) (transform_functions.html)
**upper_bound_jacobian**: - -
[`(reals x, reals u) : reals`](transform_functions.qmd#index-entry-0d83614a1071769ccb6a725cee97458ec29e649b) (transform_functions.html)
+ -
[`(reals x, reals ub) : reals`](transform_functions.qmd#index-entry-f2ff19db2443c6d37b95266808e87959db60e3cd) (transform_functions.html)
**upper_bound_unconstrain**: - -
[`(reals x, reals u) : reals`](transform_functions.qmd#index-entry-b911cf1f15054b02c6816d632d19879ff32e7a31) (transform_functions.html)
+ -
[`(reals x, reals ub) : reals`](transform_functions.qmd#index-entry-2addb4ba29c3510e0935adaeb229c3bb34d49798) (transform_functions.html)
diff --git a/src/functions-reference/transform_functions.qmd b/src/functions-reference/transform_functions.qmd index 620538358..26ab84f77 100644 --- a/src/functions-reference/transform_functions.qmd +++ b/src/functions-reference/transform_functions.qmd @@ -4,146 +4,153 @@ pagetitle: Variable Transformation Functions # Variable Transformation Functions -These functions provide direct access to the ability to -constrain and unconstrain variables using the built-in transformations -as defined in the [Stan Reference Manual](https://mc-stan.org/docs/reference-manual/transforms.html). - -For each of the built-in variable transforms, there are 3 functions exposed. A -`_constrain` function that maps from free variables to constrained variables (the "inverse transform"), -a `_unconstrain` function that maps from the constrained space back to free variables (the "transform"), -and a [`_jacobian` function](https://mc-stan.org/docs/reference-manual/statements.html#increment-log-density-with-a-change-of-variables-adjustment), +Variable transformation functions provide implementations of the built-in constraining +and unconstraining transforms defined in [Stan Reference Manual](https://mc-stan.org/docs/reference-manual/transforms.html). + +For each of the built-in variable transforms there are three functions +named after the transform with differing suffixes. A `_unconstrain` function +that maps from the constrained space back to free variables (the "transform"), +A `_constrain` function that maps from free variables to constrained variables +(the "inverse transform"), and a +[`_jacobian` function](https://mc-stan.org/docs/reference-manual/statements.html#increment-log-density-with-a-change-of-variables-adjustment), which computes the same value as the `_constrain` function while also -incrementing the target with the relevant change of variables adjustment. +incrementing the Jacobian accumulator with the log Jacobian determinant. For this page, variables named `y` are unconstrained, while variables named `x` -are in the constrained space. The unconstraining functions will cause rejections -if their input is not properly in the constrained space. +are in the constrained space. The unconstraining functions will reject if their +input does not satisfy the declared constraint. ## Transforms for scalars These transformations take unconstrained values on the real number line and -either restrict them to part of it or shift and scale their values. -Note: It is possible to use these transforms with arrays and other containers like `vector`s. -This results in elementwise application of the transform. If the `y` argument is +either constrain the, to a subset of the real line with a lower bound, upper bound, or both, +or provide an affine map that does not constrain values but can help with shifting +and scaling them so they are more standardized. + +The functions are all overloaded to apply to containers elementwise. If the `y` argument is a container, the others must be either scalars or containers of exactly the same size. ### Lower bounds -These functions perform the mathematical transform described in the +These functions perform the transform and inverse transform described in the [Lower Bounded Scalar section](https://mc-stan.org/docs/reference-manual/transforms.html#lower-bound-transform.section). - -\index{{\tt \bfseries lower\_bound\_constrain }!{\tt (reals y, reals l): reals}|hyperpage} + +\index{{\tt \bfseries lower\_bound\_constrain }!{\tt (reals y, reals lb): reals}|hyperpage} -`reals` **`lower_bound_constrain`**`(reals y, reals l)`
\newline -Takes a value `y` and lower bound `l` and returns a corresponding value -which is greater than `l` (except for the possibility of numeric precision issues). +`reals` **`lower_bound_constrain`**`(reals y, reals lb)`
\newline +Takes a value `y` and lower bound `lb` and returns the corresponding value +which is greater than `lb` (except for the possibility of rounding due to +numeric precision issues, in which case it will be equal to the bound). {{< since 2.37 >}} - -\index{{\tt \bfseries lower\_bound\_jacobian }!{\tt (reals y, reals l): reals}|hyperpage} + +\index{{\tt \bfseries lower\_bound\_jacobian }!{\tt (reals y, reals lb): reals}|hyperpage} -`reals` **`lower_bound_jacobian`**`(reals y, reals l)`
\newline -Takes a value `y` and lower bound `l` and returns a corresponding value -which is greater than `l` (except for the possibility of numeric precision issues). +`reals` **`lower_bound_jacobian`**`(reals y, reals lb)`
\newline +Takes a value `y` and lower bound `lb` and returns the corresponding value +which is greater than `lb` (except for the possibility of rounding due to +numeric precision issues, in which case it will be equal to the bound). -This function also increments the `target` variable +This function also increments the Jacobian accumulator with the corresponding change of variables adjustment. {{< since 2.37 >}} - -\index{{\tt \bfseries lower\_bound\_unconstrain }!{\tt (reals x, reals l): reals}|hyperpage} + +\index{{\tt \bfseries lower\_bound\_unconstrain }!{\tt (reals x, reals lb): reals}|hyperpage} -`reals` **`lower_bound_unconstrain`**`(reals x, reals l)`
\newline -Takes a value `x` which is greater than `l` and returns the corresponding +`reals` **`lower_bound_unconstrain`**`(reals x, reals lb)`
\newline +Takes a value `x` which is greater than `lb` and returns the corresponding unconstrained value. {{< since 2.37 >}} ### Upper bounds -These functions perform the mathematical transform described in the +These functions perform the transform and inverse transform described in the [Upper Bounded Scalar section](https://mc-stan.org/docs/reference-manual/transforms.html#upper-bounded-scalar). - -\index{{\tt \bfseries upper\_bound\_constrain }!{\tt (reals y, reals u): reals}|hyperpage} + +\index{{\tt \bfseries upper\_bound\_constrain }!{\tt (reals y, reals ub): reals}|hyperpage} -`reals` **`upper_bound_constrain`**`(reals y, reals u)`
\newline -Takes a value `y` and upper bound `u` and returns a corresponding value -which is less than `u` (except for the possibility of numeric precision issues). +`reals` **`upper_bound_constrain`**`(reals y, reals ub)`
\newline +Takes a value `y` and upper bound `ub` and returns the corresponding value +which is less than `ub` (except for the possibility of rounding due to +numeric precision issues, in which case it will be equal to the bound). {{< since 2.37 >}} - -\index{{\tt \bfseries upper\_bound\_jacobian }!{\tt (reals x, reals u): reals}|hyperpage} + +\index{{\tt \bfseries upper\_bound\_jacobian }!{\tt (reals x, reals ub): reals}|hyperpage} -`reals` **`upper_bound_jacobian`**`(reals x, reals u)`
\newline -Takes a value `y` and upper bound `u` and returns a corresponding value -which is less than `u` (except for the possibility of numeric precision issues). +`reals` **`upper_bound_jacobian`**`(reals x, reals ub)`
\newline +Takes a value `y` and upper bound `ub` and returns the corresponding value +which is less than `ub` (except for the possibility of rounding due to +numeric precision issues, in which case it will be equal to the bound). -This function also increments the `target` variable +This function also increments the Jacobian accumulator with the corresponding change of variables adjustment. {{< since 2.37 >}} - -\index{{\tt \bfseries upper\_bound\_unconstrain }!{\tt (reals x, reals u): reals}|hyperpage} + +\index{{\tt \bfseries upper\_bound\_unconstrain }!{\tt (reals x, reals ub): reals}|hyperpage} -`reals` **`upper_bound_unconstrain`**`(reals x, reals u)`
\newline -Takes a value `x` which is less than `u` and returns the corresponding +`reals` **`upper_bound_unconstrain`**`(reals x, reals ub)`
\newline +Takes a value `x` which is less than `ub` and returns the corresponding unconstrained value. {{< since 2.37 >}} ### Upper and lower bounds -These functions perform the mathematical transform described in the +These functions perform the transform and inverse transform described in the [Lower and Upper Bounded Scalar section](https://mc-stan.org/docs/reference-manual/transforms.html#logit-transform-jacobian.section). - -\index{{\tt \bfseries lower\_upper\_bound\_constrain }!{\tt (reals y, reals l, reals u): reals}|hyperpage} + +\index{{\tt \bfseries lower\_upper\_bound\_constrain }!{\tt (reals y, reals lb, reals ub): reals}|hyperpage} -`reals` **`lower_upper_bound_constrain`**`(reals y, reals l, reals u)`
\newline -Takes a value `y`, lower bound `l`, and upper bound `u` and returns a corresponding value -which is bounded between `l` and `u` (except for the possibility of numeric precision issues). +`reals` **`lower_upper_bound_constrain`**`(reals y, reals lb, reals ub)`
\newline +Takes a value `y`, lower bound `lb`, and upper bound `ub` and returns the corresponding value +which is bounded between `lb` and `ub` (except for the possibility of rounding due to +numeric precision issues, in which case it will be equal to the bound). {{< since 2.37 >}} - -\index{{\tt \bfseries lower\_upper\_bound\_jacobian }!{\tt (reals y, reals l, reals u): reals}|hyperpage} + +\index{{\tt \bfseries lower\_upper\_bound\_jacobian }!{\tt (reals y, reals lb, reals ub): reals}|hyperpage} -`reals` **`lower_upper_bound_jacobian`**`(reals y, reals l, reals u)`
\newline -Takes a value `y`, lower bound `l`, and upper bound `u` and returns a corresponding value -which is bounded between `l` and `u` (except for the possibility of numeric precision issues). +`reals` **`lower_upper_bound_jacobian`**`(reals y, reals lb, reals ub)`
\newline +Takes a value `y`, lower bound `lb`, and upper bound `ub` and returns the corresponding value +which is bounded between `lb` and `ub` (except for the possibility of rounding due to +numeric precision issues, in which case it will be equal to the bound). -This function also increments the `target` variable +This function also increments the Jacobian accumulator with the corresponding change of variables adjustment. {{< since 2.37 >}} - -\index{{\tt \bfseries lower\_upper\_bound\_unconstrain }!{\tt (reals x, reals l, reals y): reals}|hyperpage} + +\index{{\tt \bfseries lower\_upper\_bound\_unconstrain }!{\tt (reals x, reals lb, reals ub): reals}|hyperpage} -`reals` **`lower_upper_bound_unconstrain`**`(reals x, reals l, reals y)`
\newline -Takes a value `x` which is bounded between `l` and `u` and returns returns the corresponding +`reals` **`lower_upper_bound_unconstrain`**`(reals x, reals lb, reals ub)`
\newline +Takes a value `x` which is bounded between `lb` and `ub` and returns returns the corresponding unconstrained value. {{< since 2.37 >}} ### Affine transforms -These functions perform the mathematical transform described in the +These functions perform the transform and inverse transform described in the [Affinely Transformed Scalar section](https://mc-stan.org/docs/reference-manual/transforms.html#affinely-transformed-scalar). \index{{\tt \bfseries offset\_multiplier\_constrain }!{\tt (reals y, reals offset, reals mult): reals}|hyperpage} `reals` **`offset_multiplier_constrain`**`(reals y, reals offset, reals mult)`
\newline -Takes a value `y`, shift `offset`, and scale `mult` and returns a shifted -and re-scaled value. +Takes a value `y`, shift `offset`, and scale `mult` and returns a rescaled and shifted value. {{< since 2.37 >}} \index{{\tt \bfseries offset\_multiplier\_jacobian }!{\tt (reals y, reals offset, reals mult): reals}|hyperpage} `reals` **`offset_multiplier_jacobian`**`(reals y, reals offset, reals mult)`
\newline -Takes a value `y`, shift `offset`, and scale `mult` and returns a shifted -and re-scaled value. +Takes a value `y`, shift `offset`, and scale `mult` and returns a rescaled and shifted value. -This function also increments the `target` variable +This function also increments the Jacobian accumulator with the corresponding change of variables adjustment. {{< since 2.37 >}} @@ -157,9 +164,8 @@ and un-shifted. ## Transforms for constrained vectors -These functions constrain entire vectors. Note that -this ocassionally leads to a change in length, which will be -noted in the documentation for the relevant functions. +These functions constrain entire vectors hollistically. +Some transforms also change the length of the vector, as noted in the documentation. Where `vectors` is used, this indicates that either a `vector` or a (possibly multidimensional) array of `vector`s may be @@ -167,25 +173,23 @@ provided. The array will be processed element by element. ### Ordered vectors -These functions perform the mathematical transform described in the +These functions perform the transform and inverse transform described in the [Ordered Vector section](https://mc-stan.org/docs/reference-manual/transforms.html#ordered-vector). \index{{\tt \bfseries ordered\_constrain }!{\tt (vectors y): vectors}|hyperpage} `vectors` **`ordered_constrain`**`(vectors y)`
\newline -Takes a free vector `y` and returns a vector such that each element is smaller -than the next. +Takes a free vector `y` and returns a vector with elements in ascending order. {{< since 2.37 >}} \index{{\tt \bfseries ordered\_jacobian }!{\tt (vectors y): vectors}|hyperpage} `vectors` **`ordered_jacobian`**`(vectors y)`
\newline -Takes a free vector `y` and returns a vector such that each element is smaller -than the next. +Takes a free vector `y` and returns a vector with elements in ascending order. -This function also increments the `target` variable +This function also increments the Jacobian accumulator with the corresponding change of variables adjustment. {{< since 2.37 >}} @@ -198,25 +202,23 @@ Takes an ordered vector `x` and returns the corresponding free vector. ### Positive order vectors -These functions perform the mathematical transform described in the +These functions perform the transform and inverse transform described in the [Positive Ordered Vector section](https://mc-stan.org/docs/reference-manual/transforms.html#positive-ordered-vector). \index{{\tt \bfseries positive\_ordered\_constrain }!{\tt (vectors y): vectors}|hyperpage} `vectors` **`positive_ordered_constrain`**`(vectors y)`
\newline -Takes a free vector `y` and returns a vector such that each element is positive and -smaller than its successor. +Takes a free vector `y` and returns a vector with positive elements in ascending order. {{< since 2.37 >}} \index{{\tt \bfseries positive\_ordered\_jacobian }!{\tt (vectors y): vectors}|hyperpage} `vectors` **`positive_ordered_jacobian`**`(vectors y)`
\newline -Takes a free vector `y` and returns a vector such that each element is positive and -smaller than its successor. +Takes a free vector `y` and returns a vector with positive elements in ascending order. -This function also increments the `target` variable +This function also increments the Jacobian accumulator with the corresponding change of variables adjustment. {{< since 2.37 >}} @@ -227,9 +229,9 @@ with the corresponding change of variables adjustment. Takes an ordered vector `x` with positive entries and returns the corresponding free vector. {{< since 2.37 >}} -### Simplices +### Simplexes -These functions perform the mathematical transform described in the +These functions perform the transform and inverse transform described in the [Unit Simplex section](https://mc-stan.org/docs/reference-manual/transforms.html#simplex-transform.section). @@ -237,7 +239,7 @@ These functions perform the mathematical transform described in the `vectors` **`simplex_constrain`**`(vectors y)`
\newline Takes a free vector `y` and returns a simplex (a vector such that each element -is between `0` and `1`, and the sum of the elements is `1`). +is between `0` and `1`, and the sum of the elements is `1`, up to rounding errors). This returned vector will have one extra element compared to the input `y`. {{< since 2.37 >}} @@ -247,11 +249,11 @@ This returned vector will have one extra element compared to the input `y`. `vectors` **`simplex_jacobian`**`(vectors y)`
\newline Takes a free vector `y` and returns a simplex (a vector such that each element -is between `0` and `1`, and the sum of the elements is `1`). +is between `0` and `1`, and the sum of the elements is `1`, up to rounding errors). This returned vector will have one extra element compared to the input `y`. -This function also increments the `target` variable +This function also increments the Jacobian accumulator with the corresponding change of variables adjustment. {{< since 2.37 >}} @@ -266,7 +268,7 @@ This returned vector will have one fewer elements compared to the input `x`. ### Zero-sum vectors -These functions perform the mathematical transform described in the +These functions perform the transform and inverse transform described in the [Zero Sum Vector section](https://mc-stan.org/docs/reference-manual/transforms.html#zero-sum-vector). @@ -288,7 +290,7 @@ sum to `0`. The returned vector will have one extra element compared to the input `y`. -This function also increments the `target` variable +This function also increments the Jacobian accumulator with the corresponding change of variables adjustment. {{< since 2.37 >}} @@ -304,27 +306,27 @@ This returned vector will have one fewer elements compared to the input `x`. ### Unit vectors -These functions perform the mathematical transform described in the +These functions perform the transform and inverse transform described in the [Unit Vector section](https://mc-stan.org/docs/reference-manual/transforms.html#unit-vector.section). \index{{\tt \bfseries unit\_vectors\_constrain }!{\tt (vectors y): vectors}|hyperpage} `vectors` **`unit_vectors_constrain`**`(vectors y)`
\newline -Takes a free vector `y` and returns a vector with Euclidian length `1`, e.g. +Takes a free vector `y` and returns a vector with unit length, i.e., `norm2(unit_vectors_constrain(y)) == 1` for any `y` that has a positive -and finite norm itself. Note that, in particular, this function rejects -if given a vector of all zeros. +and finite norm itself (if `y` does not, the function rejects). +Note that, in particular, this implies the function rejects if given a vector of all zeros. {{< since 2.37 >}} \index{{\tt \bfseries unit\_vectors\_jacobian }!{\tt (vectors y): vectors}|hyperpage} `vectors` **`unit_vectors_jacobian`**`(vectors y)`
\newline -Takes a free vector `y` and returns a vector with Euclidian length `1`. +Takes a free vector `y` and returns a vector with unit length. This function rejects if given a vector of all zeros. -This function also increments the `target` variable +This function also increments the Jacobian accumulator with the corresponding change of variables adjustment. {{< since 2.37 >}} @@ -343,7 +345,7 @@ and `matrices` means a `matrix` or array thereof. ### Cholesky factors of correlation matrices -These functions perform the mathematical transform described in the +These functions perform the transform and inverse transform described in the [Cholesky Factors of Correlation Matrices section](https://mc-stan.org/docs/reference-manual/transforms.html#cholesky-factors-of-correlation-matrices). @@ -351,7 +353,9 @@ These functions perform the mathematical transform described in the `matrices` **`cholesky_factor_corr_constrain`**`(vectors y, int K)`
\newline Takes a vector `y` and integer `K`, where `length(y) == choose(K, 2)`, and returns -a `K` by `K` Cholesky factor of a correlation matrix. +a `K` by `K` Cholesky factor of a correlation matrix. This matrix is a Cholesky factor +of a covariance matrix (i.e., a lower triangular matrix with a strictly positive diagonal), +but with the additional constraint that each row is of unit length. {{< since 2.37 >}} @@ -359,7 +363,7 @@ a `K` by `K` Cholesky factor of a correlation matrix. Takes a vector `y` and integer `K`, where `length(y) == choose(K, 2)`, and returns a `K` by `K` Cholesky factor of a correlation matrix. -This function also increments the `target` variable +This function also increments the Jacobian accumulator with the corresponding change of variables adjustment. `matrices` **`cholesky_factor_corr_jacobian`**`(vectors y, int K)`
\newline @@ -369,13 +373,15 @@ with the corresponding change of variables adjustment. \index{{\tt \bfseries cholesky\_factor\_corr\_unconstrain }!{\tt (matrices x): vectors}|hyperpage} `vectors` **`cholesky_factor_corr_unconstrain`**`(matrices x)`
\newline -Takes `x`, a lower triangular square ($K$ by $K$) matrix which is the Cholesky factor of a correlation matrix, -and returns a corresponding free vector of length $K\choose 2$. +Takes `x`, a ($K \times K$) matrix which is the Cholesky factor of a +correlation matrix (a lower triangular matrix with a strictly positive +diagonal and each row having unit length), +and returns the corresponding free vector of length $ imes $. {{< since 2.37 >}} ### Cholesky factors of covariance matrices -These functions perform the mathematical transform described in the +These functions perform the transform and inverse transform described in the [Cholesky Factors of Covariance Matrices section](https://mc-stan.org/docs/reference-manual/transforms.html#cholesky-factors-of-covariance-matrices). @@ -383,7 +389,10 @@ These functions perform the mathematical transform described in the `matrices` **`cholesky_factor_cov_constrain`**`(vectors y, int M, int N)`
\newline Takes a free vector `y` and integers `M` and `N` and returns the `M` by `N` Cholesky -factor of a covariance matrix. Note that `y` must have length `N + choose(N, 2) + (M - N) * N`, +factor of a covariance matrix. This matrix is a lower triangular matrix $L$, with a strictly +positive diagonal, such that $L^T L$ is positive definite. + +Note that `y` must have length `N + choose(N, 2) + (M - N) * N`, and `M` must be greater than or equal to `N`. {{< since 2.37 >}} @@ -392,10 +401,13 @@ and `M` must be greater than or equal to `N`. `matrices` **`cholesky_factor_cov_jacobian`**`(vectors y, int M, int N)`
\newline Takes a free vector `y` and integers `M` and `N` and returns the `M` by `N` Cholesky -factor of a covariance matrix. Note that `y` must have length `N + choose(N, 2) + (M - N) * N`, +factor of a covariance matrix. This matrix is a lower triangular matrix $L$, with a strictly +positive diagonal, such that $L^T L$ is positive definite. + +Note that `y` must have length `N + choose(N, 2) + (M - N) * N`, and `M` must be greater than or equal to `N`. -This function also increments the `target` variable +This function also increments the Jacobian accumulator with the corresponding change of variables adjustment. {{< since 2.37 >}} @@ -403,14 +415,15 @@ with the corresponding change of variables adjustment. \index{{\tt \bfseries cholesky\_factor\_cov\_unconstrain }!{\tt (matrices x): vectors}|hyperpage} `vectors` **`cholesky_factor_cov_unconstrain`**`(matrices x)`
\newline -Takes a $M$ by $N$ Cholesky factor of a covariance matrix `x` and returns -the corresponding free vector of length $N + N\choose 2 + (M - N)N$. +Takes a $M \times N$ matrix `x` which is a Cholesky factor of a covariance matrix +(a matrix $L$ such that $L^T L$ is positive definite) and returns +the corresponding free vector of length $N + \binom{N}{2} + (M - N)N$. {{< since 2.37 >}} ### Correlation matrices -These functions perform the mathematical transform described in the +These functions perform the transform and inverse transform described in the [Correlation Matrices section](https://mc-stan.org/docs/reference-manual/transforms.html#correlation-matrix-transform.section). @@ -418,7 +431,7 @@ These functions perform the mathematical transform described in the `matrices` **`corr_matrix_constrain`**`(vectors y, int K)`
\newline Takes a vector `y` and integer `K`, where `length(y) == choose(K, 2)`, and returns -a `K` by `K` correlation matrix. +a `K` by `K` correlation matrix (a positive definite matrix with a unit diagonal). {{< since 2.37 >}} @@ -426,9 +439,9 @@ a `K` by `K` correlation matrix. `matrices` **`corr_matrix_jacobian`**`(vectors y, int K)`
\newline Takes a vector `y` and integer `K`, where `length(y) == choose(K, 2)`, and returns -a `K` by `K` correlation matrix. +a `K` by `K` correlation matrix (a positive definite matrix with a unit diagonal). -This function also increments the `target` variable +This function also increments the Jacobian accumulator with the corresponding change of variables adjustment. {{< since 2.37 >}} @@ -436,13 +449,14 @@ with the corresponding change of variables adjustment. \index{{\tt \bfseries corr\_matrix\_unconstrain }!{\tt (matrices x): vectors}|hyperpage} `vectors` **`corr_matrix_unconstrain`**`(matrices x)`
\newline -Takes a $K$ by $K$ correlation matrix `x` and returns the corresponding -free vector of size $K\choose 2$. +Takes a $K \times K$ matrix `x` which is a correlation matrix (a positive definite +matrix with a unit diagonal) and returns the corresponding free vector of +size $\binom{K}{2}$. {{< since 2.37 >}} ### Covariance matrices -These functions perform the mathematical transform described in the +These functions perform the transform and inverse transform described in the [Covariance Matrices section](https://mc-stan.org/docs/reference-manual/transforms.html#covariance-matrices). @@ -450,7 +464,7 @@ These functions perform the mathematical transform described in the `matrices` **`cov_matrix_constrain`**`(vectors y, int K)`
\newline Takes a vector `y` and integer `K`, where `length(y) == K + choose(K, 2)`, and returns -a `K` by `K` covariance matrix. +a `K` by `K` covariance matrix (a positive definite matrix). {{< since 2.37 >}} @@ -458,9 +472,9 @@ a `K` by `K` covariance matrix. `matrices` **`cov_matrix_jacobian`**`(vectors y, int K)`
\newline Takes a vector `y` and integer `K`, where `length(y) == K + choose(K, 2)`, and returns -a `K` by `K` covariance matrix. +a `K` by `K` covariance matrix (a positive definite matrix). -This function also increments the `target` variable +This function also increments the Jacobian accumulator with the corresponding change of variables adjustment. {{< since 2.37 >}} @@ -468,31 +482,32 @@ with the corresponding change of variables adjustment. \index{{\tt \bfseries cov\_matrix\_unconstrain }!{\tt (matrices x): vectors}|hyperpage} `vectors` **`cov_matrix_unconstrain`**`(matrices x)`
\newline -Takes a $K$ by $K$ covariance matrix `x` and returns the corresponding -free vector of size $K + K\choose 2$. +Takes a $K \times K$ positive definite matrix `x` and returns the corresponding +free vector of size $K + \binom{K}{2}$. {{< since 2.37 >}} ### Column-stochastic matrices -These functions perform the mathematical transform described in the -[Stochastic Matrix section](https://mc-stan.org/docs/reference-manual/transforms.html#stochastic-matrix-transform.section). +These functions perform the transform and inverse transform described in the +[Stochastic Matrix section](https://mc-stan.org/docs/reference-manual/transforms.html#stochastic-matrix-transform.section) +for column (left) stochastic matrices. \index{{\tt \bfseries stochastic\_column\_constrain }!{\tt (matrices y): matrices}|hyperpage} `matrices` **`stochastic_column_constrain`**`(matrices y)`
\newline -Takes a free matrix `y` of size $N$ by $M$ and returns a left stochastic matrix -(a matrix where each column is a simplex) of size $N+1$ by $M$. +Takes a free matrix `y` of size $N \times M$ and returns a left stochastic matrix +(a matrix where each column is a simplex) of size $N+1 \times M$. {{< since 2.37 >}} \index{{\tt \bfseries stochastic\_column\_jacobian }!{\tt (matrices y): matrices}|hyperpage} `matrices` **`stochastic_column_jacobian`**`(matrices y)`
\newline -Takes a free matrix `y` of size $N$ by $M$ and returns a left stochastic matrix -(a matrix where each column is a simplex) of size $N+1$ by $M$. +Takes a free matrix `y` of size $N \times M$ and returns a left stochastic matrix +(a matrix where each column is a simplex) of size $N+1 \times M$. -This function also increments the `target` variable +This function also increments the Jacobian accumulator with the corresponding change of variables adjustment. {{< since 2.37 >}} @@ -500,31 +515,32 @@ with the corresponding change of variables adjustment. \index{{\tt \bfseries stochastic\_column\_unconstrain }!{\tt (matrices x): matrices}|hyperpage} `matrices` **`stochastic_column_unconstrain`**`(matrices x)`
\newline -Takes a left stochastic matrix `x` of size $N+1$ by $M$ and returns the corresponding -free matrix of size $N$ by $M$. +Takes a left stochastic matrix `x` of size $N+1 \times M$ and returns the corresponding +free matrix of size $N \times M$. {{< since 2.37 >}} ### Row-stochastic matrices -These functions perform the mathematical transform described in the -[Stochastic Matrix section](https://mc-stan.org/docs/reference-manual/transforms.html#stochastic-matrix-transform.section). +These functions perform the transform and inverse transform described in the +[Stochastic Matrix section](https://mc-stan.org/docs/reference-manual/transforms.html#stochastic-matrix-transform.section) +for row (right) stochastic matrices. \index{{\tt \bfseries stochastic\_row\_constrain }!{\tt (matrices y): matrices}|hyperpage} `matrices` **`stochastic_row_constrain`**`(matrices y)`
\newline -Takes a free matrix `y` of size $N$ by $M$ and returns a right stochastic matrix -(a matrix where each row is a simplex) of size $N$ by $M+1$. +Takes a free matrix `y` of size $N \times M$ and returns a right stochastic matrix +(a matrix where each row is a simplex) of size $N \times M+1$. {{< since 2.37 >}} \index{{\tt \bfseries stochastic\_row\_jacobian }!{\tt (matrices y): matrices}|hyperpage} `matrices` **`stochastic_row_jacobian`**`(matrices y)`
\newline -Takes a free matrix `y` of size $N$ by $M$ and returns a right stochastic matrix -(a matrix where each row is a simplex) of size $N$ by $M+1$. +Takes a free matrix `y` of size $N \times M$ and returns a right stochastic matrix +(a matrix where each row is a simplex) of size $N \times M+1$. -This function also increments the `target` variable +This function also increments the Jacobian accumulator with the corresponding change of variables adjustment. {{< since 2.37 >}} @@ -532,6 +548,6 @@ with the corresponding change of variables adjustment. \index{{\tt \bfseries stochastic\_row\_unconstrain }!{\tt (matrices x): matrices}|hyperpage} `matrices` **`stochastic_row_unconstrain`**`(matrices x)`
\newline -Takes a right stochastic matrix `x` of size $N$ by $M+1$ and returns the corresponding -free matrix of size $N$ by $M$. +Takes a right stochastic matrix `x` of size $N \times M+1$ and returns the corresponding +free matrix of size $N \times M$. {{< since 2.37 >}}