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((a = asℝ₊, b = as𝕀)) # transform 2 real numbers a NamedTuple, with a > 0, 0 < b < 1

dimension(t::AbstractTransform)

The dimension (number of elements) that t transforms.

Types should implement this method.

transform(t, x)

Transform x using t.

transform_and_logjac(t, x)

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

inverse(t::AbstractTransform, y)

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

inverse(t)

Return a callable equivalen to y -> inverse(t, y).

inverse!(x, t::AbstractTransform, 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.

random_arg(x; kwargs...)

A random argument for a transformation.

Keyword arguments

A standard multivaritate normal or Cauchy is used, depending on cauchy, then scaled with scale. rng is the random number generator used.

random_value(t; kwargs...)

Random value from a transformation.

Keyword arguments

A standard multivaritate normal or Cauchy is used, depending on cauchy, then scaled with scale. rng is the random number generator used.

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

Transform to the real line (identity).

Transform to a non-negative real number.

Transform to a non-positive real number.

Transform to the unit interval (0, 1).

UnitVector(n)

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

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 Ω, such that Ω'*Ω is a correlation matrix (positive definite, with unit diagonal).

logjac_forwarddiff(f, x; handleNaN, 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, 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)

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.

struct Identity <: TransformVariables.ScalarTransform

Identity $x ↦ x$.

struct ScaledShiftedLogistic{T<:Real} <: TransformVariables.ScalarTransform

Maps to (scale, shift + scale) using x ↦ logistic(x)*scale + shift.

struct ShiftedExp{D, T<:Real} <: TransformVariables.ScalarTransform

Shifted exponential. When D::Bool == true, maps to (shift, ∞) using x ↦ shift + eˣ, otherwise to (-∞, shift) using x ↦ shift - eˣ.

struct ArrayTransform{T<:TransformVariables.AbstractTransform, M} <: TransformVariables.VectorTransform

Apply transformation repeatedly to create an array with given dims.

struct TransformTuple{K, T<:Tuple{Vararg{TransformVariables.AbstractTransform,K}}} <: TransformVariables.VectorTransform

Transform consecutive groups of real numbers to a tuple, using the given transformations.

struct TransformNamedTuple{names, T<:(Tuple{Vararg{TransformVariables.AbstractTransform,N}} where N)} <: TransformVariables.VectorTransform

Transform consecutive groups of real numbers to a named tuple, using the given transformations.

struct InverseTransform{T}

Inverse of the wrapped transform. Use the 1-argument version of inverse to construct.

An AbstractVector of <:Real elements.

Used internally as a type for transformations from vectors.

abstract type AbstractTransform

Supertype for all transformations in this package.

Interface

The user interface consists of

• dimension
• transform
• transform_and_logjac
• [inverse]@(ref), inverse!
• inverse_eltype.

abstract type ScalarTransform <: TransformVariables.AbstractTransform

Transform a scalar (real number) to another scalar.

Subtypes mustdefine transform, transform_and_logjac, and inverse; other methods of of the interface should have the right defaults.

abstract type VectorTransform <: TransformVariables.AbstractTransform

Transformation that transforms <: RealVectors to other values.

Implementation

Implements transform and transform_and_logjac via transform_with, and inverse via inverse!.

abstract type LogJacFlag

Flag used internally by the implementation of transformations, as explained below.

When calculating the log jacobian determinant for a matrix, initialize with

logjac_zero(flag, x)

and then accumulate with log jacobians as needed with +.

When flag is LogJac, methods should return the log Jacobian as the second argument, otherwise NoLogJac, which simply combines to itself with +, serving as an empty placeholder. This allows methods to share code of the two implementations.

Calculate log Jacobian as the second value.

Don't calculate log Jacobian, return NOLOGJAC as the second value.

logjac_zero(?, T)

Initial value for log Jacobian calculations.

Workaround for https://github.com/JuliaLang/julia/issues/14919 to make transformation types callable.

TODO: remove when this issue is closed, also possibly remove MacroTools as a dependency if not used elsewhere.

transform_with(flag::LogJacFlag, t::AbstractTransform, x::RealVector)

Transform elements of x, starting using transformation.

The first value returned is the transformed value, the second the log Jacobian determinant or a placeholder, depending on flag.

In contrast to [transform] and [transform_and_logjac], this method always assumes that x is a RealVector, for efficient traversal. Some types implement the latter two via this method.

Implementations should assume generalized indexing on x.

_transform_tuple(flag, x, index)

Helper function for transforming tuples. Used internally, to help type inference. Use via transfom_tuple only.

_inverse!_tuple(x, ts, ys)

Helper function for inverting tuples of transformations. Used internally.

_inverse_eltype_tuple(ts, ys)

Helper function determining element type of inverses from tuples. Used internally.

unit_triangular_dimension(n)

Number of elements (strictly) above the diagonal in an $n×n$ matrix.

(y, r, ℓ) =

l2_remainder_transform(flag, x, r)

Given $x ∈ ℝ$ and $0 ≤ r ≤ 1$, return (y, r′) such that

1. $y² + r′² = r²$,

2. $y: |y| ≤ r$ is mapped with a bijection from x.

ℓ is the log Jacobian (whether it is evaluated depends on flag).

(x, r′) =

l2_remainder_inverse(y, r)

Inverse of l2_remainder_transform in x and y.