diff --git a/docs/make.jl b/docs/make.jl index 983991b4..4d3d3f2e 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -9,6 +9,7 @@ pages = [ "Tutorials" => [ "Adding a new measure" => "adding.md", "Affine transformations" => "affine.md", + "Variate transformations" => "vartransform.md", ], "API Reference" => [ "MeasureBase" => "api_measurebase.md", diff --git a/docs/src/vartransform.md b/docs/src/vartransform.md new file mode 100644 index 00000000..3c0ce937 --- /dev/null +++ b/docs/src/vartransform.md @@ -0,0 +1,9 @@ +# Variate Transformations + +Often one needs to find a map `f` that transports samples of probability measure `μ` into samples of another probability measure `v`. More generally, `μ` to `v` can be measures. Then `v` is the [pushforward measure](https://en.wikipedia.org/wiki/Pushforward_measure) of measure `μ` under such `f`. + +Using [`vartransform`](@ref) we can (for many measures) automatically generate this function `f = vartransform(v, μ)` so that [`pushfwd(f, μ)`](@ref) becomes equal to `v`. Instead of sampling `∫(L, v)` we can now sample `∫(L∘f, μ)` by transforming the sampled points `X_μ` to sample points `X_v = f.(X_μ)`. + +A typical application arises in nested sampling which natively uses `μ = StdUniform()^n` as its base measure, while many MCMC sampling algorithms work best in an unbounded space and prefer base measures such as `μ = StdNormal()^n` or `μ = StdLogistic()^n`. + +Transformation functions `f = vartransform(v, μ)` support `f_inverse = InverseFunctions.inverse(f)` and `x_v, ladj = ChangesOfVariables.with_logabsdet_jacobian(f, x_μ)`.