[WIP] [RFQ] Add vartransform documentation

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",

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_μ)`.