dimension(t::AbstractTransform)

The dimension (number of elements) that t transforms.

Types should implement this method.

transform(t, x)

Transform x using t.

transform(t).

Return a callable equivalent to x -> transform(t, x) that transforms its argument:

transform(t, x) == transform(t)(x)

transform_and_logjac(t, x)

Transform x using t; calculating the log Jacobian determinant, returned as the second value.

inverse(t, y)

Return x so that transform(t, x) ≈ y.

inverse(t)

Return a callable equivalent to y -> inverse(t, y). t can also be a callable created with transform, so the following holds:

inverse(t)(y) == inverse(t, y) == inverse(transform(t))(y)

inverse!(x, transformation, y)

Put inverse(t, y) into a preallocated vector x, returning x.

Generalized indexing should be assumed on x.

See inverse_eltype for determining the type of x.

inverse_eltype(t::AbstractTransform, y)

The element type for vector x so that inverse!(x, t, y) works.

transform_logdensity(t, f, x)

Let $y = t(x)$, and $f(y)$ a log density at y. This function evaluates f ∘ t as a log density, taking care of the log Jacobian correction.

domain_label(transformation, index)

Return a string that can be used to for identifying a coordinate. Mainly for debugging and generating graphs and data summaries.

Transformations may provide a heuristic label.

Transformations should implement _domain_label.

Example

julia> t = as((a = asℝ₊,
            b = as(Array, asℝ₋, 1, 1),
            c = corr_cholesky_factor(2)));

julia> [domain_label(t, i) for i in 1:dimension(t)]
3-element Vector{String}:
 ".a"
 ".b[1,1]"
 ".c[1]"

as(T, args...)

Shorthand for constructing transformations with image in T. args determines or modifies behavior, details depend on T.

Not all transformations have an as method, some just have direct constructors. See methods(as) for a list.

Examples

as(Real, -∞, 1)          # transform a real number to (-∞, 1)
as(Array, 10, 2)         # reshape 20 real numbers to a 10x2 matrix
as(Array, as𝕀, 10)       # transform 10 real numbers to (0, 1)
as((a = asℝ₊, b = as𝕀)) # transform 2 real numbers a NamedTuple, with a > 0, 0 < b < 1
as(SArray{1,2,3}, as𝕀)  # transform to a static array of positive numbers

Placeholder representing of infinity for specifing interval boundaries. Supports the - operator, ie -∞.

as(Real, left, right)

Return a transformation that transforms a single real number to the given (open) interval.

left < right is required, but may be -∞ or ∞, respectively, in which case the appropriate transformation is selected. See ∞.

Some common transformations are predefined as constants, see asℝ, asℝ₋, asℝ₊, as𝕀.

Transform to the real line (identity). See as.

asℝ and as_real are equivalent alternatives.

Transform to a positive real number. See as.

asℝ₊ and as_positive_real are equivalent alternatives.

Transform to a negative real number. See as.

asℝ₋ and as_negative_real are equivalent alternatives.

Transform to the unit interval (0, 1). See as.

as𝕀 and as_unit_interval are equivalent alternatives.

UnitVector(n)

Transform n-1 real numbers to a unit vector of length n, under the Euclidean norm.

UnitSimplex(n)

Transform n-1 real numbers to a vector of length n whose elements are non-negative and sum to one.

CorrCholeskyFactor(n)

Cholesky factor of a correlation matrix of size n.

Transforms $n×(n-1)/2$ real numbers to an $n×n$ upper-triangular matrix U, such that U'*U is a correlation matrix (positive definite, with unit diagonal).

Notes

If

• z is a vector of n IID standard normal variates,

• σ is an n-element vector of standard deviations,

• U is obtained from CorrCholeskyFactor(n),

then Diagonal(σ) * U' * z will be a multivariate normal with the given variances and correlation matrix U' * U.

corr_cholesky_factor(n)

Transform into a Cholesky factor of a correlation matrix.

If the argument is a (positive) integer n, it determines the size of the output n × n, resulting in a Matrix.

If the argument is SMatrix{N,N}, an SMatrix is produced.

Contant(value)

Placeholder for inserting a constant. Inverse checks equality with ==.

logjac_forwarddiff(f, x; handleNaN, chunk, cfg)

Calculate the log Jacobian determinant of f at x using `ForwardDiff.

Note

f should be a bijection, mapping from vectors of real numbers to vectors of equal length.

When handleNaN = true (the default), NaN log Jacobians are converted to -Inf.

value_and_logjac_forwarddiff(
    f,
    x;
    flatten,
    handleNaN,
    chunk,
    cfg
)

Calculate the value and the log Jacobian determinant of f at x. flatten is used to get a vector out of the result that makes f a bijection.

CustomTransform(g, f, flatten; chunk, cfg)

Wrap a custom transform y = f(transform(g, x))in a type that calculates the log Jacobian of∂y/∂xusingForwardDiff` when necessary.

Usually, g::TransformReals, but when an integer is used, it amounts to the identity transformation with that dimension.

flatten should take the result from f, and return a flat vector with no redundant elements, so that $x ↦ y$ is a bijection. For example, for a covariance matrix the elements below the diagonal should be removed.

chunk and cfg can be used to configure ForwardDiff.JacobianConfig. cfg is used directly, while chunk = ForwardDiff.Chunk{N}() can be used to obtain a type-stable configuration.