Variable Transformation Functions
Variable transformation functions provide implementations of the built-in constraining and unconstraining transforms defined in Stan Reference Manual.
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, 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.
reals lower_bound_constrain(reals y, reals lb)
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).
reals lower_bound_jacobian(reals y, reals lb)
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.
Available since 2.37reals lower_bound_unconstrain(reals x, reals lb)
Takes a value x which is greater than lb and returns the corresponding unconstrained value.
Upper bounds
These functions perform the transform and inverse transform described in the Upper Bounded Scalar section.
reals upper_bound_constrain(reals y, reals ub)
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).
reals upper_bound_jacobian(reals x, reals ub)
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.
Available since 2.37reals upper_bound_unconstrain(reals x, reals ub)
Takes a value x which is less than ub and returns the corresponding unconstrained value.
Upper and lower bounds
These functions perform the transform and inverse transform described in the Lower and Upper Bounded Scalar section.
reals lower_upper_bound_constrain(reals y, reals lb, reals ub)
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).
reals lower_upper_bound_jacobian(reals y, reals lb, reals ub)
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.
Available since 2.37reals lower_upper_bound_unconstrain(reals x, reals lb, reals ub)
Takes a value x which is bounded between lb and ub and returns returns the corresponding unconstrained value.
Affine transforms
These functions perform the transform and inverse transform described in the Affinely Transformed Scalar section.
reals offset_multiplier_constrain(reals y, reals offset, reals mult)
Takes a value y, shift offset, and scale mult and returns a rescaled and shifted value.
reals offset_multiplier_jacobian(reals y, reals offset, reals mult)
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.
Available since 2.37reals offset_multiplier_unconstrain(reals x, reals offset, reals mult)
Takes a value x, shift offset, and scale mult and a value which has been un-scaled and un-shifted.
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 vectors 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.
vectors ordered_constrain(vectors y)
Takes a free vector y and returns a vector with elements in ascending order.
vectors ordered_jacobian(vectors y)
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.
Available since 2.37vectors ordered_unconstrain(vectors x)
Takes an ordered vector x and returns the corresponding free vector.
Positive order vectors
These functions perform the transform and inverse transform described in the Positive Ordered Vector section.
vectors positive_ordered_constrain(vectors y)
Takes a free vector y and returns a vector with positive elements in ascending order.
vectors positive_ordered_jacobian(vectors y)
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.
Available since 2.37vectors positive_ordered_unconstrain(vectors x)
Takes an ordered vector x with positive entries and returns the corresponding free vector.
Simplexes
These functions perform the transform and inverse transform described in the Unit Simplex section.
vectors simplex_constrain(vectors y)
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.
vectors simplex_jacobian(vectors y)
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.
Available since 2.37vectors simplex_unconstrain(vectors x)
Takes a simplex x and returns the corresponding free vector.
This returned vector will have one fewer elements compared to the input x.
Sum-to-zero vectors
These functions perform the transform and inverse transform described in the Zero Sum Vector section.
vectors sum_to_zero_constrain(vectors y)
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.
vectors sum_to_zero_jacobian(vectors y)
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.
Available since 2.37vectors sum_to_zero_unconstrain(vectors x)
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.
Unit vectors
These functions perform the transform and inverse transform described in the Unit Vector section.
vectors unit_vectors_constrain(vectors y)
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.
vectors unit_vectors_jacobian(vectors y)
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.
Available since 2.37vectors unit_vectors_unconstrain(vectors x)
Takes a vector x of unit length and returns the corresponding free vector.
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.
matrices cholesky_factor_corr_constrain(vectors y, int K)
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.
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)
vectors cholesky_factor_corr_unconstrain(matrices x)
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 $.
Cholesky factors of covariance matrices
These functions perform the transform and inverse transform described in the Cholesky Factors of Covariance Matrices section.
matrices cholesky_factor_cov_constrain(vectors y, int M, int N)
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.
matrices cholesky_factor_cov_jacobian(vectors y, int M, int N)
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.
Available since 2.37vectors cholesky_factor_cov_unconstrain(matrices x)
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\).
Correlation matrices
These functions perform the transform and inverse transform described in the Correlation Matrices section.
matrices corr_matrix_constrain(vectors y, int K)
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).
matrices corr_matrix_jacobian(vectors y, int K)
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.
Available since 2.37vectors corr_matrix_unconstrain(matrices x)
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}\).
Covariance matrices
These functions perform the transform and inverse transform described in the Covariance Matrices section.
matrices cov_matrix_constrain(vectors y, int K)
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).
matrices cov_matrix_jacobian(vectors y, int K)
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.
Available since 2.37vectors cov_matrix_unconstrain(matrices x)
Takes a \(K \times K\) positive definite matrix x and returns the corresponding free vector of size \(K + \binom{K}{2}\).
Column-stochastic matrices
These functions perform the transform and inverse transform described in the Stochastic Matrix section for column (left) stochastic matrices.
matrices stochastic_column_constrain(matrices y)
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\).
matrices stochastic_column_jacobian(matrices y)
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.
Available since 2.37matrices stochastic_column_unconstrain(matrices x)
Takes a left stochastic matrix x of size \(N+1 \times M\) and returns the corresponding free matrix of size \(N \times M\).
Row-stochastic matrices
These functions perform the transform and inverse transform described in the Stochastic Matrix section for row (right) stochastic matrices.
matrices stochastic_row_constrain(matrices y)
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\).
matrices stochastic_row_jacobian(matrices y)
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.
Available since 2.37matrices stochastic_row_unconstrain(matrices x)
Takes a right stochastic matrix x of size \(N \times M+1\) and returns the corresponding free matrix of size \(N \times M\).
Sum-to-zero matrices
The sum-to-zero matrix transforms map between unconstrained values and matrices whose rows and columns sum to zero; full definitions of the function and Jacobian can be found in the sum-to-zero matrix section of the Reference Manual.
matrices sum_to_zero_constrain(matrices y)
The constraining function maps an unconstrained N x M matrix to an (N + 1) x (M + 1) matrix for which the rows and columns all sum to zero. This function covers the incrementation of the log Jacobian because the incrementation is zero.
This returned matrix will have one extra row and column compared to the input y.
matrices sum_to_zero_jacobian(matrices y)
The constraining function maps an unconstrained N x M matrix to an (N + 1) x (M + 1) matrix for which the rows and columns all sum to zero. Because the log Jacobian incrementation is zero, this is identical to sum_to_zero_constrain.
This returned matrix will have one extra row and column compared to the input y.
matrices sum_to_zero_unconstrain(matrices x)
This function maps a matrix with rows that sum to zero and columns that sum to zero to an unconstrained matrix with one fewer row and and one fewer column.