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..ebfa0de5d 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 M, int N) : matrices`](transform_functions.qmd#index-entry-0cddde7e0aa5cc9213f393acebb3b13b68b7bfa8) (transform_functions.html)
+ + +**cholesky_factor_cov_jacobian**: + + -
[`(vectors y, int M, int N) : matrices`](transform_functions.qmd#index-entry-fd1e2249d8d133c4bf9d8e6b44f67c9c69314da3) (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 lb) : reals`](transform_functions.qmd#index-entry-e152c4494a196c9bd932faad21a3555c712d102c) (transform_functions.html)
+ + +**lower_bound_jacobian**: + + -
[`(reals y, reals lb) : reals`](transform_functions.qmd#index-entry-dda4a6ffc09ae6ffec4218c092003fea973c174e) (transform_functions.html)
+ + +**lower_bound_unconstrain**: + + -
[`(reals x, reals lb) : reals`](transform_functions.qmd#index-entry-d178c95f782831ea0616fdc58b25d16826f98164) (transform_functions.html)
+ + +**lower_upper_bound_constrain**: + + -
[`(reals y, reals lb, reals ub) : reals`](transform_functions.qmd#index-entry-d44d27ade0aed4fc8aa29d480aa1cbd767281f72) (transform_functions.html)
+ + +**lower_upper_bound_jacobian**: + + -
[`(reals y, reals lb, reals ub) : reals`](transform_functions.qmd#index-entry-fa7585cac2eb147a254907e9aacffb346393c41e) (transform_functions.html)
+ + +**lower_upper_bound_unconstrain**: + + -
[`(reals x, reals lb, reals ub) : reals`](transform_functions.qmd#index-entry-da54a8c2ddfb181210e40b0e47d122f16713af86) (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**: + + -
[`(vectors y) : vectors`](transform_functions.qmd#index-entry-055048ff4bc60482699857e7993258efc99d45f0) (transform_functions.html)
+ + +**simplex_jacobian**: + + -
[`(vectors y) : vectors`](transform_functions.qmd#index-entry-446c0a0a855c1f82fe5f0df51dddf43419abd15f) (transform_functions.html)
+ + +**simplex_unconstrain**: + + -
[`(vectors x) : vectors`](transform_functions.qmd#index-entry-ffa2ad29148676e3139f6d81a3fba15199481f30) (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 ub) : reals`](transform_functions.qmd#index-entry-762c88752de52b0a7df91820157122b1ddd4e9f1) (transform_functions.html)
+ + +**upper_bound_jacobian**: + + -
[`(reals x, reals ub) : reals`](transform_functions.qmd#index-entry-f2ff19db2443c6d37b95266808e87959db60e3cd) (transform_functions.html)
+ + +**upper_bound_unconstrain**: + + -
[`(reals x, reals ub) : reals`](transform_functions.qmd#index-entry-2addb4ba29c3510e0935adaeb229c3bb34d49798) (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..26ab84f77 --- /dev/null +++ b/src/functions-reference/transform_functions.qmd @@ -0,0 +1,553 @@ +--- +pagetitle: Variable Transformation Functions +--- + +# Variable Transformation Functions + +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 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 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 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 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 lb): reals}|hyperpage} + +`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 lb): reals}|hyperpage} + +`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 Jacobian accumulator +with the corresponding change of variables adjustment. +{{< since 2.37 >}} + + +\index{{\tt \bfseries lower\_bound\_unconstrain }!{\tt (reals x, reals lb): reals}|hyperpage} + +`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 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 ub): reals}|hyperpage} + +`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 ub): reals}|hyperpage} + +`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 Jacobian accumulator +with the corresponding change of variables adjustment. +{{< since 2.37 >}} + + +\index{{\tt \bfseries upper\_bound\_unconstrain }!{\tt (reals x, reals ub): reals}|hyperpage} + +`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 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 lb, reals ub): reals}|hyperpage} + +`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 lb, reals ub): reals}|hyperpage} + +`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 Jacobian accumulator +with the corresponding change of variables adjustment. +{{< since 2.37 >}} + +\index{{\tt \bfseries lower\_upper\_bound\_unconstrain }!{\tt (reals x, reals lb, reals ub): reals}|hyperpage} + +`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 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 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 rescaled and shifted value. + +This function also increments the Jacobian accumulator +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 + +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 +provided. The array will be processed element by element. + +### Ordered vectors + +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 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 with elements in ascending order. + +This function also increments the Jacobian accumulator +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 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 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 with positive elements in ascending order. + +This function also increments the Jacobian accumulator +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 >}} + +### Simplexes + +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). + + +\index{{\tt \bfseries simplex\_constrain }!{\tt (vectors y): vectors}|hyperpage} + +`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`, up to rounding errors). + +This returned vector will have one extra element compared to the input `y`. +{{< since 2.37 >}} + + +\index{{\tt \bfseries simplex\_jacobian }!{\tt (vectors y): vectors}|hyperpage} + +`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`, up to rounding errors). + +This returned vector will have one extra element compared to the input `y`. + +This function also increments the Jacobian accumulator +with the corresponding change of variables adjustment. +{{< since 2.37 >}} + + +\index{{\tt \bfseries simplex\_unconstrain }!{\tt (vectors x): vectors}|hyperpage} + +`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 transform and inverse 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 Jacobian accumulator +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 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 unit length, i.e., +`norm2(unit_vectors_constrain(y)) == 1` for any `y` that has a positive +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 unit length. +This function rejects if given a vector of all zeros. + +This function also increments the Jacobian accumulator +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 + +Similarly to the above, `vectors` means a `vector` or array thereof, +and `matrices` means a `matrix` or array thereof. + +### Cholesky factors of correlation matrices + + +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). + + +\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. 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 >}} + + +\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 Jacobian accumulator +with the corresponding change of variables adjustment. +`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 +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 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). + + +\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. 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 >}} + + +\index{{\tt \bfseries cholesky\_factor\_cov\_jacobian }!{\tt (vectors y, int M, int N): matrices}|hyperpage} + +`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. 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 Jacobian accumulator +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 \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 transform and inverse 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 (a positive definite matrix with a unit diagonal). +{{< 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 (a positive definite matrix with a unit diagonal). + +This function also increments the Jacobian accumulator +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 \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 transform and inverse 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 (a positive definite 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 (a positive definite matrix). + +This function also increments the Jacobian accumulator +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 \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 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 \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 \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 Jacobian accumulator +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 \times M$ and returns the corresponding +free matrix of size $N \times M$. +{{< since 2.37 >}} + +### Row-stochastic matrices + +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 \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 \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 Jacobian accumulator +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 \times M+1$ and returns the corresponding +free matrix of size $N \times M$. +{{< 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/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. 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);