Change to ValueSupport interface

Project.toml

@@ -32,6 +32,7 @@ ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210"
 JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
-
+Unitful = "1986cc42-f94f-5a68-af5c-568840ba703d"
+
 [targets]
-test = ["Calculus", "Distributed", "FiniteDifferences", "ForwardDiff", "JSON", "StaticArrays", "Test"]
+test = ["Calculus", "Distributed", "FiniteDifferences", "ForwardDiff", "JSON", "StaticArrays", "Test", "Unitful"]

docs/src/types.md

@@ -7,7 +7,7 @@ All samplers and distributions provided in this package are organized into a typ
 The root of this type hierarchy is `Sampleable`. The abstract type `Sampleable` subsumes any types of objects from which one can draw samples, which particularly includes *samplers* and *distributions*. Formally, `Sampleable` is defined as
 
 ```julia
-abstract type Sampleable{F<:VariateForm,S<:ValueSupport} end
+abstract type Sampleable{F<:VariateForm,S<:Support} end
 ```
 
 It has two type parameters that define the kind of samples that can be drawn therefrom.
@@ -31,18 +31,19 @@ The `VariateForm` sub-types defined in `Distributions.jl` are:
 `Multivariate` | a numeric vector | A matrix, each column being a sample
 `Matrixvariate` | a numeric matrix | An array of matrices, each element being a sample matrix
 
-### ValueSupport
+### Support
 
 ```@doc
-Distributions.ValueSupport
+Distributions.Support
 ```
 
-The `ValueSupport` sub-types defined in `Distributions.jl` are:
+The `Support` sub-types defined in `Distributions.jl` are:
 
 **Type** | **Element type** | **Descriptions**
 --- | --- | ---
-`Discrete` | `Int` | Samples take discrete values
-`Continuous` | `Float64` | Samples take continuous real values
+`CountableSupport{T}` | `T` | Samples take any discrete values
+`ContiguousSupport{T <: Integer}` | `T` | Samples take any contiguous integer values
+`ContinuousSupport{T <: Number}` | `T` | Samples take continuous values
 
 Multiple samples are often organized into an array, depending on the variate form.
 
@@ -62,29 +63,18 @@ rand!(::AbstractRNG, ::Sampleable, ::AbstractArray)
 We use `Distribution`, a subtype of `Sampleable` as defined below, to capture probabilistic distributions. In addition to being sampleable, a *distribution* typically comes with an explicit way to combine its domain, probability density functions, among many other quantities.
 
 ```julia
-abstract type Distribution{F<:VariateForm,S<:ValueSupport} <: Sampleable{F,S} end
+abstract type Distribution{F<:VariateForm,S<:Support} <: Sampleable{F,S} end
 ```
 
 ```@doc
 Distributions.Distribution
 ```
 
-To simplify the use in practice, we introduce a series of type alias as follows:
+To simplify the use in practice, we introduce a series of type aliases as follows:
 ```julia
-const UnivariateDistribution{S<:ValueSupport}   = Distribution{Univariate,S}
-const MultivariateDistribution{S<:ValueSupport} = Distribution{Multivariate,S}
-const MatrixDistribution{S<:ValueSupport}       = Distribution{Matrixvariate,S}
-const NonMatrixDistribution = Union{UnivariateDistribution, MultivariateDistribution}
-
-const DiscreteDistribution{F<:VariateForm}   = Distribution{F,Discrete}
-const ContinuousDistribution{F<:VariateForm} = Distribution{F,Continuous}
-
-const DiscreteUnivariateDistribution     = Distribution{Univariate,    Discrete}
-const ContinuousUnivariateDistribution   = Distribution{Univariate,    Continuous}
-const DiscreteMultivariateDistribution   = Distribution{Multivariate,  Discrete}
-const ContinuousMultivariateDistribution = Distribution{Multivariate,  Continuous}
-const DiscreteMatrixDistribution         = Distribution{Matrixvariate, Discrete}
-const ContinuousMatrixDistribution       = Distribution{Matrixvariate, Continuous}
+const UnivariateDistribution{S<:Support}   = Distribution{Univariate,S}
+const MultivariateDistribution{S<:Support} = Distribution{Multivariate,S}
+const MatrixDistribution{S<:Support}       = Distribution{Matrixvariate,S}
 ```
 
 All methods applicable to `Sampleable` also applies to `Distribution`. The API for distributions of different variate forms are different (refer to [univariates](@ref univariates), [multivariates](@ref multivariates), and [matrix](@ref matrix-variates) for details).

src/Distributions.jl

@@ -31,19 +31,31 @@ export
 
     # generic types
     VariateForm,
-    ValueSupport,
+    Support,
+    CountableSupport,
+    ContiguousSupport,
+    ContinuousSupport,
+    DiscontinuousSupport,
+    UnionSupport,
     Univariate,
     Multivariate,
     Matrixvariate,
-    Discrete,
-    Continuous,
     Sampleable,
     Distribution,
     UnivariateDistribution,
     MultivariateDistribution,
     MatrixDistribution,
     NoncentralHypergeometric,
-    NonMatrixDistribution,
+    SufficientStats,
+    AbstractMvNormal,
+    AbstractMixtureModel,
+    UnivariateMixture,
+    MultivariateMixture,
+
+    # Deprecated const types
+    ValueSupport,
+    Continuous,
+    Discrete,
     DiscreteDistribution,
     ContinuousDistribution,
     DiscreteUnivariateDistribution,
@@ -52,11 +64,6 @@ export
     ContinuousUnivariateDistribution,
     ContinuousMultivariateDistribution,
     ContinuousMatrixDistribution,
-    SufficientStats,
-    AbstractMvNormal,
-    AbstractMixtureModel,
-    UnivariateMixture,
-    MultivariateMixture,
 
     # distribution types
     Arcsine,

src/common.jl

@@ -10,24 +10,33 @@ struct Multivariate  <: VariateForm end
 struct Matrixvariate <: VariateForm end
 
 """
-`S <: ValueSupport` specifies the support of sample elements,
-either discrete or continuous.
-"""
-abstract type ValueSupport end
-struct Discrete   <: ValueSupport end
-struct Continuous <: ValueSupport end
+`S <: Support{T}` specifies the support of sample elements as T,
+either discrete, continuous or other.
+"""
+abstract type Support{N} end
+struct ContinuousSupport{N <: Number} <: Support{N} end
+abstract type CountableSupport{C} <: Support{C} end
+struct ContiguousSupport{C <: Integer} <: CountableSupport{C} end
+struct UnionSupport{N1, N2,
+                    S1 <: Support{N1},
+                    S2 <: Support{N2}} <:
+                        Support{Union{N1, N2}} end
+
+const DiscontinuousSupport{I, F} =
+    UnionSupport{I, F, <: CountableSupport{I},
+                 ContinuousSupport{F}} where {I <: Number, F <: Number}
 
 ## Sampleable
 
 """
-    Sampleable{F<:VariateForm,S<:ValueSupport}
+    Sampleable{F<:VariateForm,S<:Support}
 
 `Sampleable` is any type able to produce random values.
 Parametrized by a `VariateForm` defining the dimension of samples
-and a `ValueSupport` defining the domain of possibly sampled values.
+and a `Support` defining the domain of possibly sampled values.
 Any `Sampleable` implements the `Base.rand` method.
 """
-abstract type Sampleable{F<:VariateForm,S<:ValueSupport} end
+abstract type Sampleable{F<:VariateForm,S<:Support} end
 
 """
     length(s::Sampleable)
@@ -49,14 +58,15 @@ Base.size(s::Sampleable{Univariate}) = ()
 Base.size(s::Sampleable{Multivariate}) = (length(s),)
 
 """
-    eltype(::Type{Sampleable})
+    eltype(::Type{<:Sampleable})
+    eltype(::Type{<:Support{N}})
 
 The default element type of a sample. This is the type of elements of the samples generated
 by the `rand` method. However, one can provide an array of different element types to
 store the samples using `rand!`.
 """
-Base.eltype(::Type{<:Sampleable{F,Discrete}}) where {F} = Int
-Base.eltype(::Type{<:Sampleable{F,Continuous}}) where {F} = Float64
+Base.eltype(::Type{<:Sampleable{F, <: Support{N}}}) where {F, N} = N
+Base.eltype(::Type{<:Support{N}}) where {N} = N
 
 """
     nsamples(s::Sampleable)
@@ -67,41 +77,28 @@ into an array, depending on the variate form.
 nsamples(t::Type{Sampleable}, x::Any)
 nsamples(::Type{D}, x::Number) where {D<:Sampleable{Univariate}} = 1
 nsamples(::Type{D}, x::AbstractArray) where {D<:Sampleable{Univariate}} = length(x)
-nsamples(::Type{D}, x::AbstractVector) where {D<:Sampleable{Multivariate}} = 1
+nsamples(::Type{D}, x::AbstractArray{<:AbstractVector}) where {D<:Sampleable{Multivariate}} = length(x)
+nsamples(::Type{D}, x::AbstractVector{<:Number}) where {D<:Sampleable{Multivariate}} = 1
 nsamples(::Type{D}, x::AbstractMatrix) where {D<:Sampleable{Multivariate}} = size(x, 2)
-nsamples(::Type{D}, x::Number) where {D<:Sampleable{Matrixvariate}} = 1
-nsamples(::Type{D}, x::Array{Matrix{T}}) where {D<:Sampleable{Matrixvariate},T<:Number} = length(x)
+nsamples(::Type{D}, x::AbstractMatrix{<:Number}) where {D<:Sampleable{Matrixvariate}} = 1
+nsamples(::Type{D}, x::AbstractArray{<:AbstractMatrix{T}}) where {D<:Sampleable{Matrixvariate},T<:Number} = length(x)
 
 """
-    Distribution{F<:VariateForm,S<:ValueSupport} <: Sampleable{F,S}
+    Distribution{F<:VariateForm,S<:Support} <: Sampleable{F,S}
 
 `Distribution` is a `Sampleable` generating random values from a probability
 distribution. Distributions define a Probability Distribution Function (PDF)
 to implement with `pdf` and a Cumulated Distribution Function (CDF) to implement
 with `cdf`.
 """
-abstract type Distribution{F<:VariateForm,S<:ValueSupport} <: Sampleable{F,S} end
-
-const UnivariateDistribution{S<:ValueSupport}   = Distribution{Univariate,S}
-const MultivariateDistribution{S<:ValueSupport} = Distribution{Multivariate,S}
-const MatrixDistribution{S<:ValueSupport}       = Distribution{Matrixvariate,S}
-const NonMatrixDistribution = Union{UnivariateDistribution, MultivariateDistribution}
-
-const DiscreteDistribution{F<:VariateForm}   = Distribution{F,Discrete}
-const ContinuousDistribution{F<:VariateForm} = Distribution{F,Continuous}
-
-const DiscreteUnivariateDistribution     = Distribution{Univariate,    Discrete}
-const ContinuousUnivariateDistribution   = Distribution{Univariate,    Continuous}
-const DiscreteMultivariateDistribution   = Distribution{Multivariate,  Discrete}
-const ContinuousMultivariateDistribution = Distribution{Multivariate,  Continuous}
-const DiscreteMatrixDistribution         = Distribution{Matrixvariate, Discrete}
-const ContinuousMatrixDistribution       = Distribution{Matrixvariate, Continuous}
+abstract type Distribution{F<:VariateForm,S<:Support} <: Sampleable{F,S} end
 
-variate_form(::Type{Distribution{VF,VS}}) where {VF<:VariateForm,VS<:ValueSupport} = VF
-variate_form(::Type{T}) where {T<:Distribution} = variate_form(supertype(T))
+const UnivariateDistribution{S<:Support}   = Distribution{Univariate,S}
+const MultivariateDistribution{S<:Support} = Distribution{Multivariate,S}
+const MatrixDistribution{S<:Support}       = Distribution{Matrixvariate,S}
 
-value_support(::Type{Distribution{VF,VS}}) where {VF<:VariateForm,VS<:ValueSupport} = VS
-value_support(::Type{T}) where {T<:Distribution} = value_support(supertype(T))
+variate_form(::Type{<:Sampleable{VF, <:Support}}) where {VF<:VariateForm} = VF
+value_support(::Type{<:Sampleable{<:VariateForm,VS}}) where {VS<:Support} = VS
 
 # allow broadcasting over distribution objects
 # to be decided: how to handle multivariate/matrixvariate distributions?
@@ -116,18 +113,18 @@ const DistributionType{D<:Distribution} = Type{D}
 const IncompleteFormulation = Union{DistributionType,IncompleteDistribution}
 
 """
-    succprob(d::DiscreteUnivariateDistribution)
+    succprob(d::UnivariateDistribution{ContiguousSupport{T}})
 
 Get the probability of success.
 """
-succprob(d::DiscreteUnivariateDistribution)
+succprob(d::UnivariateDistribution{<:ContiguousSupport})
 
 """
-    failprob(d::DiscreteUnivariateDistribution)
+    failprob(d::UnivariateDistribution{ContiguousSupport{T}})
 
 Get the probability of failure.
 """
-failprob(d::DiscreteUnivariateDistribution)
+failprob(d::UnivariateDistribution{<:ContiguousSupport})
 
 # Temporary fix to handle RFunctions dependencies
 """

src/conversion.jl

@@ -1,5 +1,5 @@
 
-# Discrete univariate
+# Integer univariate
 
 convert(::Type{Binomial}, d::Bernoulli) = Binomial(1, d.p)
 

src/deprecates.jl

@@ -2,7 +2,7 @@
 
 @Base.deprecate expected_logdet meanlogdet
 
-function probs(d::DiscreteUnivariateDistribution)
+function probs(d::UnivariateDistribution{<:ContiguousSupport})
     Base.depwarn("probs(d::$(typeof(d))) is deprecated. Please use pdf(d) instead.", :probs)
     return pdf(d)
 end
@@ -40,4 +40,19 @@ for fun in [:pdf, :logpdf,
     end
 end
 
-@deprecate pdf(d::DiscreteUnivariateDistribution) pdf.(Ref(d), support(d))
+@deprecate pdf(d::UnivariateDistribution{<:ContiguousSupport}) pdf.(Ref(d), support(d))
+
+# No longer proposing use of many const aliases
+Base.@deprecate_binding ValueSupport Support{Float64}
+Base.@deprecate_binding Discrete     ContiguousSupport{Int}
+Base.@deprecate_binding Continuous   ContinuousSupport{Float64}
+
+const DiscreteDistribution{F<:VariateForm}   = Distribution{F,Discrete}
+const ContinuousDistribution{F<:VariateForm} = Distribution{F,Continuous}
+
+Base.@deprecate_binding DiscreteUnivariateDistribution     Distribution{Univariate,    Discrete}
+Base.@deprecate_binding ContinuousUnivariateDistribution   Distribution{Univariate,    Continuous}
+Base.@deprecate_binding DiscreteMultivariateDistribution   Distribution{Multivariate,  Discrete}
+Base.@deprecate_binding ContinuousMultivariateDistribution Distribution{Multivariate,  Continuous}
+Base.@deprecate_binding DiscreteMatrixDistribution         Distribution{Matrixvariate, Discrete}
+Base.@deprecate_binding ContinuousMatrixDistribution       Distribution{Matrixvariate, Continuous}

src/edgeworth.jl

@@ -4,7 +4,9 @@
 
 # Edgeworth approximation of the Z statistic
 # EdgeworthSum and EdgeworthMean are both defined in terms of this
-abstract type EdgeworthAbstract <: ContinuousUnivariateDistribution end
+abstract type EdgeworthAbstract <:
+    UnivariateDistribution{ContinuousSupport{Float64}}
+end
 
 skewness(d::EdgeworthAbstract) = skewness(d.dist) / sqrt(d.n)
 kurtosis(d::EdgeworthAbstract) = kurtosis(d.dist) / d.n

src/functionals.jl

@@ -5,17 +5,28 @@ function getEndpoints(distr::UnivariateDistribution, epsilon::Real)
     (leftEnd, rightEnd)
 end
 
-function expectation(distr::ContinuousUnivariateDistribution, g::Function, epsilon::Real)
+function expectation(distr::UnivariateDistribution{<:ContinuousSupport},
+                     g::Function, epsilon::Real) 
     f = x->pdf(distr,x)
     (leftEnd, rightEnd) = getEndpoints(distr, epsilon)
     integrate(x -> f(x)*g(x), leftEnd, rightEnd)
 end
 
-## Assuming that discrete distributions only take integer values.
-function expectation(distr::DiscreteUnivariateDistribution, g::Function, epsilon::Real)
-    f = x->pdf(distr,x)
+## Assuming that contiguous integer distributions don't have gaps in support
+function expectation(distr::UnivariateDistribution{<:ContiguousSupport},
+                     g::Function, epsilon::Real)
     (leftEnd, rightEnd) = getEndpoints(distr, epsilon)
-    sum(x -> f(x)*g(x), leftEnd:rightEnd)
+    sum(leftEnd:rightEnd) do x
+        pdf(distr,x) * g(x)
+    end
+end
+
+## Any countable distribution that is finite
+function expectation(distr::UnivariateDistribution{<:CountableSupport},
+                     g::Function, epsilon::Real)
+    sum(support(distr)) do x
+        pdf(distr,x) * g(x)
+    end
 end
 
 function expectation(distr::UnivariateDistribution, g::Function)
@@ -29,6 +40,7 @@ end
 #     expectation(distr, x -> -log(f(x)))
 # end
 
-function kldivergence(P::UnivariateDistribution, Q::UnivariateDistribution)
+function kldivergence(P::UnivariateDistribution{S},
+                      Q::UnivariateDistribution{S}) where {S <: Support}
     expectation(P, x -> let p = pdf(P,x); (p > 0)*log(p/pdf(Q,x)) end)
 end

src/matrix/inversewishart.jl

@@ -16,7 +16,8 @@ f(\\boldsymbol{\\Sigma}; \\nu,\\boldsymbol{\\Psi}) =
 
 ``\\mathbf{H}\\sim W_p(\\nu, \\mathbf{S})`` if and only if ``\\mathbf{H}^{-1}\\sim IW_p(\\nu, \\mathbf{S}^{-1})``.
 """
-struct InverseWishart{T<:Real, ST<:AbstractPDMat} <: ContinuousMatrixDistribution
+struct InverseWishart{T<:Real, ST<:AbstractPDMat} <:
+    MatrixDistribution{ContinuousSupport{T}}
     df::T     # degree of freedom
     Ψ::ST     # scale matrix
     c0::T     # log of normalizing constant

src/matrix/matrixbeta.jl

@@ -24,7 +24,8 @@ are independent, and we use ``\\mathcal{L}(\\cdot)`` to denote the lower Cholesk
 
 has ``\\mathbf{U}\\sim MB_p(n_1/2, n_2/2)``.
 """
-struct MatrixBeta{T <: Real, TW <: Wishart} <: ContinuousMatrixDistribution
+struct MatrixBeta{T <: Real, TW <: Wishart} <:
+    MatrixDistribution{ContinuousSupport{T}}
     W1::TW
     W2::TW
     logc0::T

src/matrix/matrixfdist.jl

@@ -29,7 +29,8 @@ is given by
 then the marginal distribution of ``\\boldsymbol{\\Sigma}`` is
 ``MF_{p}(n_1/2,n_2/2,\\mathbf{B})``.
 """
-struct MatrixFDist{T <: Real, TW <: Wishart} <: ContinuousMatrixDistribution
+struct MatrixFDist{T <: Real, TW <: Wishart} <:
+    MatrixDistribution{ContinuousSupport{T}}
     W::TW
     n2::T
     logc0::T

src/matrix/matrixnormal.jl

@@ -15,7 +15,8 @@ f(\\mathbf{X};\\mathbf{M}, \\mathbf{U}, \\mathbf{V}) = \\frac{\\exp\\left( -\\fr
 
 ``\\mathbf{X}\\sim MN_{n,p}(\\mathbf{M},\\mathbf{U},\\mathbf{V})`` if and only if ``\\text{vec}(\\mathbf{X})\\sim N(\\text{vec}(\\mathbf{M}),\\mathbf{V}\\otimes\\mathbf{U})``.
 """
-struct MatrixNormal{T <: Real, TM <: AbstractMatrix, ST <: AbstractPDMat} <: ContinuousMatrixDistribution
+struct MatrixNormal{T <: Real, TM <: AbstractMatrix, ST <: AbstractPDMat} <:
+    MatrixDistribution{ContinuousSupport{T}}
     M::TM
     U::ST
     V::ST