Add MvLogitNormal

[sethaxen]

Implements #1771

[sethaxen]

Currently it takes a different approach than MvLogNormal. MvLogNormal wraps an MvNormal, so it cannot be parameterized like an MvNormalCanon or other AbstractMvNormal types. MvLogitNormal instead wraps an AbstractMvNormal, which allows it to also wrap MvNormalCanon or any user-defined AbstractMvNormal type.

[codecov-commenter]

Codecov Report

Attention: 2 lines in your changes are missing coverage. Please review.

Files	Coverage Δ
src/Distributions.jl	100.00% <ø> (ø)
src/multivariates.jl	44.82% <ø> (ø)
src/multivariate/mvlogitnormal.jl	97.14% <97.14%> (ø)

... and 1 file with indirect coverage changes

📢 Thoughts on this report? Let us know!.

[ParadaCarleton]

Is there a reason the generic methods don't work? I think we should probably be using something more generic.

[sethaxen]

The generic methods treat the field names as parameters, which here looks weird because the field contains another distribution:

julia> using Distributions, LinearAlgebra

julia> d = MvLogitNormal(randn(3), exp(Symmetric(randn(3, 3))))
MvLogitNormal{FullNormal}(
dim: 3
μ: [-0.6695883087710813, -0.4262204488438936, 1.5508073295811842]
Σ: [1.8911987804702053 0.038814771826912765 1.2907448948413436; 0.038814771826912765 0.7054789545738211 0.06748072828787553; 1.2907448948413436 0.06748072828787553 0.9560938804684098]
)


julia> invoke(Base.show, Tuple{IO,Distribution}, stdout, d)
MvLogitNormal{FullNormal}(
normal: FullNormal(
dim: 3
μ: [-0.6695883087710813, -0.4262204488438936, 1.5508073295811842]
Σ: [1.8911987804702053 0.038814771826912765 1.2907448948413436; 0.038814771826912765 0.7054789545738211 0.06748072828787553; 1.2907448948413436 0.06748072828787553 0.9560938804684098]
)

)

julia> d = MvLogitNormal{MvNormalCanon}(randn(3), exp(Symmetric(randn(3, 3))))
MvLogitNormal{FullNormalCanon}(
μ: [-12.008515816447346, 9.221467028160104, 0.9303379007669893]
h: [-1.3761114231540177, 2.320365757512754, -0.05647292940406612]
J: [0.7714588053672484 0.9492070250024665 -0.929895944697952; 0.9492070250024665 1.6622992471750913 -1.7304512340037166; -0.929895944697952 -1.7304512340037166 5.088641347774431]
)


julia> invoke(Base.show, Tuple{IO,Distribution}, stdout, d)
MvLogitNormal{FullNormalCanon}(
normal: FullNormalCanon(
μ: [-12.008515816447346, 9.221467028160104, 0.9303379007669893]
h: [-1.3761114231540177, 2.320365757512754, -0.05647292940406612]
J: [0.7714588053672484 0.9492070250024665 -0.929895944697952; 0.9492070250024665 1.6622992471750913 -1.7304512340037166; -0.929895944697952 -1.7304512340037166 5.088641347774431]
)

)

We could use show_multiline, but this requires knowledge of the names of the parameters of the AbstractMvNormal, which we don't know, since Distributions doesn't have an API function for parameter names, just values.

[devmotion]

Looks very good, thank you! I only had a few minor comments.

[devmotion]

I'm not completely sure anymore but I assume we don't have any statistical test utilities for e.g. hypothesis tests of samples? IIRC KS tests are used for the univariate distributions but I assume we don't have anything for multi- or matrixvariate distributions.

[sethaxen]

This is the closest I can find, which just checks that a 1x1 matrix distribution is consistent with the univariate distribution it reduces to:

Distributions.jl/test/matrixvariates.jl

Lines 193 to 199 in b21e515

	function test_draws_against_univariate_cdf(D::MatrixDistribution, d::UnivariateDistribution)
	α = 0.025
	M = 100000
	matvardraws = [rand(D)[1] for m in 1:M]
	@test pvalue_kolmogorovsmirnoff(matvardraws, d) >= α
	nothing
	end

[devmotion]

Thank you for checking! Would be useful to have something similar for multivariate distributions (generally, IMO we should provide test utilities such that you can check more easily that you implement the interface correctly) but better to do this in a separate PR.