[RFC] Add angle bijector

src/Bijectors.jl

@@ -43,6 +43,7 @@ export  TransformDistribution,
         PositiveDistribution,
         UnitDistribution,
         SimplexDistribution,
+        AngularDistribution,
         PDMatDistribution,
         link,
         invlink,
@@ -155,6 +156,8 @@ function logpdf_with_trans(d::UnivariateDistribution, x, transform::Bool)
     end
 end
 
+const AngularDistribution = Union{VonMises}
+
 ## Multivariate
 
 const SimplexDistribution = Union{Dirichlet}

src/bijectors/angle.jl

@@ -0,0 +1,20 @@
+# non-bijector from an angle to a circle
+# its "inverse" is a left inverse from the plane to an angle such that
+# (inv(Angle()) ∘ Angle())(θ) == θ and (Angle() ∘ inv(Angle()))(z) == normalize(z)
+# Instead of the logdetjac, we use that a standard bivariate normally distributed random
+# variable `z` upon normalization is uniformly distributed on the circle.
+# so the necessary adjustment to the logpdf by using `z` is -‖z‖^2/2
+# see https://mc-stan.org/docs/2_26/reference-manual/unit-vector-section.html
+
+struct Angle <: Bijector{0} end
+
+(b::Angle)(θ::Real) = [sincos(θ)...]
+
+(ib::Inverse{<:Angle})(z::AbstractVector{<:Real}) = atan(z...)
+
+logabsdetjac(::Angle, θ::Real) = one(θ) / 2
+
+function logabsdetjac(::Inverse{<:Angle}, z::AbstractVector{<:Real})
+    y, x = z
+    return -(x^2 + y^2) / 2
+end

src/interface.jl

@@ -152,6 +152,7 @@ include("bijectors/scale.jl")
 include("bijectors/shift.jl")
 include("bijectors/permute.jl")
 include("bijectors/simplex.jl")
+include("bijectors/angle.jl")
 include("bijectors/pd.jl")
 include("bijectors/corr.jl")
 include("bijectors/truncated.jl")

src/transformed_distribution.jl

@@ -56,6 +56,7 @@ bijector(d::Distributions.AbstractMvNormal) = Identity{1}()
 bijector(d::Distributions.AbstractMvLogNormal) = Log{1}()
 bijector(d::PositiveDistribution) = Log{0}()
 bijector(d::SimplexDistribution) = SimplexBijector{1}()
+bijector(d::AngularDistribution) = Angle()
 bijector(d::KSOneSided) = Logit(zero(eltype(d)), one(eltype(d)))
 
 bijector_bounded(d, a=minimum(d), b=maximum(d)) = Logit(a, b)