Merge branch 'master' into dw/logpdf_negbinomial

Project.toml

@@ -1,7 +1,7 @@
 name = "Distributions"
 uuid = "31c24e10-a181-5473-b8eb-7969acd0382f"
 authors = ["JuliaStats"]
-version = "0.25.65"
+version = "0.25.67"
 
 [deps]
 ChainRulesCore = "d360d2e6-b24c-11e9-a2a3-2a2ae2dbcce4"

docs/Project.toml

@@ -4,4 +4,4 @@ GR = "28b8d3ca-fb5f-59d9-8090-bfdbd6d07a71"
 
 [compat]
 Documenter = "0.26, 0.27"
-GR = "0.61, 0.62, 0.63, 0.64"
+GR = "0.61, 0.62, 0.63, 0.64, 0.65, 0.66"

docs/src/types.md

@@ -33,16 +33,21 @@ The `VariateForm` sub-types defined in `Distributions.jl` are:
 
 ### ValueSupport
 
-```@doc
+```@docs
 Distributions.ValueSupport
 ```
 
 The `ValueSupport` sub-types defined in `Distributions.jl` are:
 
-**Type** | **Element type** | **Descriptions**
---- | --- | ---
-`Discrete` | `Int` | Samples take discrete values
-`Continuous` | `Float64` | Samples take continuous real values
+```@docs
+Distributions.Discrete
+Distributions.Continuous
+```
+
+**Type** | **Default element type** | **Description** | **Examples**
+--- | --- | --- | ---
+`Discrete` | `Int` | Samples take countably many values | $\{0,1,2,3\}$, $\mathbb{N}$
+`Continuous` | `Float64` | Samples take uncountably many values | $[0, 1]$, $\mathbb{R}$
 
 Multiple samples are often organized into an array, depending on the variate form.
 

src/Distributions.jl

@@ -145,7 +145,7 @@ export
     Pareto,
     PGeneralizedGaussian,
     SkewedExponentialPower,
-    Product,
+    Product, # deprecated
     Poisson,
     PoissonBinomial,
     QQPair,
@@ -293,6 +293,7 @@ include("cholesky/lkjcholesky.jl")
 include("samplers.jl")
 
 # others
+include("product.jl")
 include("reshaped.jl")
 include("truncate.jl")
 include("censored.jl")

src/common.jl

@@ -23,13 +23,42 @@ const Matrixvariate = ArrayLikeVariate{2}
 abstract type CholeskyVariate <: VariateForm end
 
 """
-`S <: ValueSupport` specifies the support of sample elements,
-either discrete or continuous.
+    ValueSupport
+
+Abstract type that specifies the support of elements of samples.
+
+It is either [`Discrete`](@ref) or [`Continuous`](@ref).
 """
 abstract type ValueSupport end
+
+"""
+    Discrete <: ValueSupport
+
+This type represents the support of a discrete random variable.
+
+It is countable. For instance, it can be a finite set or a countably infinite set such as
+the natural numbers.
+
+See also: [`Continuous`](@ref), [`ValueSupport`](@ref)
+"""
 struct Discrete   <: ValueSupport end
+
+"""
+    Continuous <: ValueSupport
+
+This types represents the support of a continuous random variable.
+
+It is uncountably infinite. For instance, it can be an interval on the real line.
+
+See also: [`Discrete`](@ref), [`ValueSupport`](@ref)
+"""
 struct Continuous <: ValueSupport end
 
+# promotions (e.g., in product distribution):
+# combination of discrete support (countable) and continuous support (uncountable) yields
+# continuous support (uncountable)
+Base.promote_rule(::Type{Continuous}, ::Type{Discrete}) = Continuous
+
 ## Sampleable
 
 """
@@ -42,7 +71,6 @@ Any `Sampleable` implements the `Base.rand` method.
 """
 abstract type Sampleable{F<:VariateForm,S<:ValueSupport} end
 
-
 variate_form(::Type{<:Sampleable{VF}}) where {VF} = VF
 value_support(::Type{<:Sampleable{<:VariateForm,VS}}) where {VS} = VS
 
@@ -142,10 +170,6 @@ const ContinuousMultivariateDistribution = Distribution{Multivariate,  Continuou
 const DiscreteMatrixDistribution         = Distribution{Matrixvariate, Discrete}
 const ContinuousMatrixDistribution       = Distribution{Matrixvariate, Continuous}
 
-variate_form(::Type{<:Distribution{VF}}) where {VF} = VF
-
-value_support(::Type{<:Distribution{VF,VS}}) where {VF,VS} = VS
-
 # allow broadcasting over distribution objects
 # to be decided: how to handle multivariate/matrixvariate distributions?
 Broadcast.broadcastable(d::UnivariateDistribution) = Ref(d)

src/multivariate/product.jl

@@ -1,4 +1,5 @@
-import Statistics: mean, var, cov
+# Deprecated product distribution
+# TODO: Remove in next breaking release
 
 """
     Product <: MultivariateDistribution
@@ -16,14 +17,19 @@ struct Product{
     V<:AbstractVector{T},
 } <: MultivariateDistribution{S}
     v::V
-    function Product(v::V) where
-        V<:AbstractVector{T} where
-        T<:UnivariateDistribution{S} where
-        S<:ValueSupport
-        return new{S, T, V}(v)
+    function Product{S,T,V}(v::V) where {S<:ValueSupport,T<:UnivariateDistribution{S},V<:AbstractVector{T}}
+        return new{S,T,V}(v)
     end
 end
 
+function Product(v::V) where {S<:ValueSupport,T<:UnivariateDistribution{S},V<:AbstractVector{T}}
+    Base.depwarn(
+        "`Product(v)` is deprecated, please use `product_distribution(v)`",
+        :Product,
+    )
+    return Product{S, T, V}(v)
+end
+
 length(d::Product) = length(d.v)
 function Base.eltype(::Type{<:Product{S,T}}) where {S<:ValueSupport,
                                                     T<:UnivariateDistribution{S}}
@@ -43,26 +49,9 @@ insupport(d::Product, x::AbstractVector) = all(insupport.(d.v, x))
 minimum(d::Product) = map(minimum, d.v)
 maximum(d::Product) = map(maximum, d.v)
 
-"""
-    product_distribution(dists::AbstractVector{<:UnivariateDistribution})
-
-Creates a multivariate product distribution `P` from a vector of univariate distributions.
-Fallback is the `Product constructor`, but specialized methods can be defined
-for distributions with a special multivariate product.
-"""
-function product_distribution(dists::AbstractVector{<:UnivariateDistribution})
-    return Product(dists)
-end
-
-"""
-    product_distribution(dists::AbstractVector{<:Normal})
-
-Computes the multivariate Normal distribution obtained by stacking the univariate
-normal distributions. The result is a multivariate Gaussian with a diagonal
-covariance matrix.
-"""
-function product_distribution(dists::AbstractVector{<:Normal})
-    µ = mean.(dists)
-    σ2 = var.(dists)
-    return MvNormal(µ, Diagonal(σ2))
+# will be removed when `Product` is removed
+# it will return a `ProductDistribution` then which is already the default for
+# higher-dimensional arrays and distributions
+function product_distribution(dists::V) where {S<:ValueSupport,T<:UnivariateDistribution{S},V<:AbstractVector{T}}
+    return Product{S,T,V}(dists)
 end

src/multivariates.jl

@@ -116,7 +116,7 @@ for fname in ["dirichlet.jl",
               "mvnormalcanon.jl",
               "mvlognormal.jl",
               "mvtdist.jl",
-              "product.jl",
+              "product.jl", # deprecated
               "vonmisesfisher.jl"]
     include(joinpath("multivariate", fname))
 end