Introduction

Some problems, especially in numerical integration and Markov Chain Monte Carlo, benefit from transformation of variables: for example, if $σ > 0$ is a standard deviation parameter, it is usually better to work with log(σ) which can take any value on the real line. However, in general such transformations require correcting density functions by the determinant of their Jacobian matrix, usually referred to as "the Jacobian".

Also, is usually easier to code MCMC algorithms to work with vectors of real numbers, which may represent a "flattened" version of parameters, and would need to be decomposed into individual parameters, which themselves may be arrays, tuples, or special objects like lower triangular matrices.

This package is designed to help with both of these use cases. For example, consider the "8 schools" problem from Chapter 5.5 of Gelman et al (2013), in which SAT scores $y_{ij}$ in $J=8$ schools are modeled using a conditional normal

\[y_{ij} ∼ N(θⱼ, σ²)\]

and the $θⱼ$ are assume to have a hierarchical prior distribution

\[θⱼ ∼ N(μ, τ²)\]

For this problem, one could define a transformation

using TransformVariables
t = as((μ = asℝ, σ = asℝ₊, τ = asℝ₊, θs = as(Array, 8)))
dimension(t)

11

which would then yield a NamedTuple with the given names, with one of them being a Vector:

julia> x = randn(dimension(t))11-element Vector{Float64}:
  0.06193274031408013
  0.2784058141640002
 -0.5958244153640522
  0.04665938957338174
  1.0857940215432762
 -1.5765649225859841
  0.1759399913010747
  0.8653808054093252
  0.972024394360624
  1.546409924955377
 -0.5841980481085709
julia> y = transform(t, x)(μ = 0.06193274031408013, σ = 1.3210221779582236, τ = 0.5511080366004918, θs = [0.04665938957338174, 1.0857940215432762, -1.5765649225859841, 0.1759399913010747, 0.8653808054093252, 0.972024394360624, 1.546409924955377, -0.5841980481085709])
julia> keys(y)(:μ, :σ, :τ, :θs)
julia> y.θs8-element Vector{Float64}:
  0.04665938957338174
  1.0857940215432762
 -1.5765649225859841
  0.1759399913010747
  0.8653808054093252
  0.972024394360624
  1.546409924955377
 -0.5841980481085709

Further worked examples of using this package can be found in the DynamicHMCExamples.jl repository. It is recommended that the user reads those first, and treats this documentation as a reference.

General interface

Defining transformations

The as constructor and aggregations

Some transformations, particularly aggregations use the function as as the constructor. Aggregating transformations are built from other transformations to transform consecutive (blocks of) real numbers into the desired domain.

It is recommended that you use as(Array, ...) and friends (as(Vector, ...), as(Matrix, ...)) for repeating the same transformation, and named tuples such as as((μ = ..., σ = ...)) for transforming into named parameters. For extracting parameters in log likelihoods, consider Parameters.jl.

See methods(as) for all the constructors, ?as for their documentation.

Scalar transforms

The symbol ∞ is a placeholder for infinity. It does not correspond to Inf, but acts as a placeholder for the correct dispatch. -∞ is valid.

as(Real, a, b) defines transformations to finite and (semi-)infinite subsets of the real line, where a and b can be -∞ and ∞, respectively.

The following constants are defined for common cases.

Special arrays

Miscellaneous transformations

Defining custom transformations