Add docs for link, invlink, and logpdf_with_trans (#351)

* Remove <Julia 1.1 check

* Fix a doctest

* Include docs output in gitignore

* Add docs for link, invlink, logpdf_with_trans

* Expand on logpdf_with_trans docs

* Bump patch

.gitignore

@@ -1,2 +1,2 @@
-/Manifest.toml
-/test/Manifest.toml
+Manifest.toml
+docs/build

Project.toml

@@ -1,6 +1,6 @@
 name = "Bijectors"
 uuid = "76274a88-744f-5084-9051-94815aaf08c4"
-version = "0.14.1"
+version = "0.14.2"
 
 [deps]
 ArgCheck = "dce04be8-c92d-5529-be00-80e4d2c0e197"

docs/src/index.md

@@ -1,6 +1,15 @@
 # Bijectors.jl
 
-This package implements a set of functions for transforming constrained random variables (e.g. simplexes, intervals) to Euclidean space. The 3 main functions implemented in this package are the `link`, `invlink` and `logpdf_with_trans` for a number of distributions. The distributions supported are:
+This package implements a set of functions for transforming constrained random variables (e.g. simplexes, intervals) to Euclidean space.
+The 3 main functions implemented in this package are the `link`, `invlink` and `logpdf_with_trans` for a number of distributions.
+
+```@docs
+Bijectors.link
+Bijectors.invlink
+Bijectors.logpdf_with_trans
+```
+
+The distributions supported are:
 
  1. `RealDistribution`: `Union{Cauchy, Gumbel, Laplace, Logistic, NoncentralT, Normal, NormalCanon, TDist}`,
  2. `PositiveDistribution`: `Union{BetaPrime, Chi, Chisq, Erlang, Exponential, FDist, Frechet, Gamma, InverseGamma, InverseGaussian, Kolmogorov, LogNormal, NoncentralChisq, NoncentralF, Rayleigh, Weibull}`,

src/Bijectors.jl

@@ -79,10 +79,6 @@ export TransformDistribution,
     InvertibleBatchNorm,
     elementwise
 
-if VERSION < v"1.1"
-    using Compat: eachcol
-end
-
 if VERSION < v"1.9"
     using Compat: stack
 end
@@ -130,7 +126,59 @@ end
 
 # Distributions
 
+"""
+    link(d::Distribution, x)
+
+Transforms the input `x` using the constrained-to-unconstrained bijector for
+distribution `d`.
+
+See also: [`invlink`](@ref).
+
+# Example
+
+```jldoctest
+julia> using Bijectors
+
+julia> d = LogNormal()   # support is (0, Inf)
+LogNormal{Float64}(μ=0.0, σ=1.0)
+
+julia> b = bijector(d)   # log function transforms to unconstrained space
+(::Base.Fix1{typeof(broadcast), typeof(log)}) (generic function with 1 method)
+
+julia> b(1.0)
+0.0
+
+julia> link(LogNormal(), 1.0)
+0.0
+```
+"""
 link(d::Distribution, x) = bijector(d)(x)
+
+"""
+    invlink(d::Distribution, y)
+
+Performs the inverse transform on a value `y` that was transformed using the
+constrained-to-unconstrained bijector for distribution `d`.
+
+It should hold that `invlink(d, link(d, x)) = x`.
+
+See also: [`link`](@ref).
+
+# Example
+
+```jldoctest
+julia> using Bijectors
+
+julia> d = LogNormal()    # support is (0, Inf)
+LogNormal{Float64}(μ=0.0, σ=1.0)
+
+julia> link(LogNormal(), 1.0)   # uses a log transform
+0.0
+
+julia> invlink(LogNormal(), 0.0)
+1.0
+```
+"""
 invlink(d::Distribution, y) = inverse(bijector(d))(y)
 
 # To still allow `logpdf_with_trans` to work with "batches" in a similar way
@@ -160,6 +208,43 @@ end
 _logabsdetjac_dist(d::LKJCholesky, x::Cholesky) = logabsdetjac(bijector(d), x)
 _logabsdetjac_dist(d::LKJCholesky, x::AbstractVector) = logabsdetjac.((bijector(d),), x)
 
+"""
+    logpdf_with_trans(d::Distribution, x, transform::Bool)
+
+If `transform` is `false`, `logpdf_with_trans` calculates the log probability
+density function (logpdf) of distribution `d` at `x`.
+
+If `transform` is `true`, `x` is transformed using the
+constrained-to-unconstrained bijector for distribution `d`, and then the logpdf
+of the resulting value is calculated with respect to the unconstrained
+(transformed) distribution. Equivalently, if `x` is distributed according to
+`d` and `y = link(d, x)` is distributed according to `td = transformed(d)`,
+then `logpdf_with_trans(d, x, true) = logpdf(td, y)`. This is accomplished
+by subtracting the log Jacobian of the transformation.
+
+# Example
+
+```jldoctest
+julia> using Bijectors
+
+julia> logpdf_with_trans(LogNormal(), ℯ, false)
+-2.4189385332046727
+
+julia> logpdf(LogNormal(), ℯ)  # Same as above
+-2.4189385332046727
+
+julia> logpdf_with_trans(LogNormal(), ℯ, true)
+-1.4189385332046727
+
+julia> # If x ~ LogNormal(), then log(x) ~ Normal()
+       logpdf(Normal(), 1.0)   
+-1.4189385332046727
+
+julia> # The difference between the two is due to the Jacobian
+       logabsdetjac(bijector(LogNormal()), ℯ)
+-1
+```
+"""
 function logpdf_with_trans(d::Distribution, x, transform::Bool)
     if ispd(d)
         return pd_logpdf_with_trans(d, x, transform)

src/bijectors/coupling.jl

@@ -166,7 +166,7 @@ julia> coupling(cl) # get the `Bijector` map `θ -> b(⋅, θ)`
 Shift
 
 julia> couple(cl, x) # get the `Bijector` resulting from `x`
-Shift([2.0])
+Shift{Vector{Float64}}([2.0])
 
 julia> with_logabsdet_jacobian(cl, x)
 ([3.0, 2.0, 3.0], 0.0)