Merge branch 'master' into dw/product

.github/workflows/CI.yml

@@ -24,7 +24,7 @@ jobs:
       fail-fast: false
       matrix:
         version:
-          - '1.0'
+          - '1.3'
           - '1'
           - 'nightly'
         os:

Project.toml

@@ -1,7 +1,7 @@
 name = "Distributions"
 uuid = "31c24e10-a181-5473-b8eb-7969acd0382f"
 authors = ["JuliaStats"]
-version = "0.25.34"
+version = "0.25.62"
 
 [deps]
 ChainRulesCore = "d360d2e6-b24c-11e9-a2a3-2a2ae2dbcce4"
@@ -22,13 +22,13 @@ Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 [compat]
 ChainRulesCore = "1"
 DensityInterface = "0.4"
-FillArrays = "0.9, 0.10, 0.11, 0.12"
+FillArrays = "0.9, 0.10, 0.11, 0.12, 0.13"
 PDMats = "0.10, 0.11"
 QuadGK = "2"
-SpecialFunctions = "0.8, 0.9, 0.10, 1.0"
+SpecialFunctions = "1.2, 2"
 StatsBase = "0.32, 0.33"
-StatsFuns = "0.8, 0.9"
-julia = "1"
+StatsFuns = "0.9.15, 1"
+julia = "1.3"
 
 [extras]
 Calculus = "49dc2e85-a5d0-5ad3-a950-438e2897f1b9"
@@ -37,9 +37,10 @@ Distributed = "8ba89e20-285c-5b6f-9357-94700520ee1b"
 FiniteDifferences = "26cc04aa-876d-5657-8c51-4c34ba976000"
 ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210"
 JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
+OffsetArrays = "6fe1bfb0-de20-5000-8ca7-80f57d26f881"
 StableRNGs = "860ef19b-820b-49d6-a774-d7a799459cd3"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["StableRNGs", "Calculus", "ChainRulesTestUtils", "Distributed", "FiniteDifferences", "ForwardDiff", "JSON", "StaticArrays", "Test"]
+test = ["StableRNGs", "Calculus", "ChainRulesTestUtils", "Distributed", "FiniteDifferences", "ForwardDiff", "JSON", "StaticArrays", "Test", "OffsetArrays"]

docs/Project.toml

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

docs/make.jl

@@ -4,18 +4,20 @@ import Random: AbstractRNG, rand!
 makedocs(
     sitename = "Distributions.jl",
     modules  = [Distributions],
-    doctest  = false,
+    format   = Documenter.HTML(; prettyurls = get(ENV, "CI", nothing) == "true"),
     pages    = [
         "index.md",
         "starting.md",
         "types.md",
         "univariate.md",
         "truncate.md",
+        "censored.md",
         "multivariate.md",
         "matrix.md",
         "reshape.md",
         "cholesky.md",
         "mixture.md",
+        "convolution.md",
         "fit.md",
         "extends.md",
         "density_interface.md",

docs/src/censored.md

@@ -0,0 +1,53 @@
+# Censored Distributions
+
+In *censoring* of data, values exceeding an upper limit (right censoring) or falling below a lower limit (left censoring), or both (interval censoring) are replaced by the corresponding limit itself.
+The package provides the `censored` function, which creates the most appropriate distribution to represent a censored version of a given distribution.
+
+A censored distribution can be constructed using the following signature:
+
+```@docs
+censored
+```
+
+In the general case, this will create a `Distributions.Censored{typeof(d0)}` structure, defined as follows:
+
+```@docs
+Distributions.Censored
+```
+
+In general, `censored` should be called instead of the constructor of `Censored`, which is not exported.
+
+Many functions, including those for the evaluation of pdf and sampling, are defined for all censored univariate distributions:
+
+- [`maximum(::UnivariateDistribution)`](@ref)
+- [`minimum(::UnivariateDistribution)`](@ref)
+- [`insupport(::UnivariateDistribution, x::Any)`](@ref)
+- [`pdf(::UnivariateDistribution, ::Real)`](@ref)
+- [`logpdf(::UnivariateDistribution, ::Real)`](@ref)
+- [`cdf(::UnivariateDistribution, ::Real)`](@ref)
+- [`logcdf(::UnivariateDistribution, ::Real)`](@ref)
+- [`logdiffcdf(::UnivariateDistribution, ::T, ::T) where {T <: Real}`](@ref)
+- [`ccdf(::UnivariateDistribution, ::Real)`](@ref)
+- [`logccdf(::UnivariateDistribution, ::Real)`](@ref)
+- [`quantile(::UnivariateDistribution, ::Real)`](@ref)
+- [`cquantile(::UnivariateDistribution, ::Real)`](@ref)
+- [`invlogcdf(::UnivariateDistribution, ::Real)`](@ref)
+- [`invlogccdf(::UnivariateDistribution, ::Real)`](@ref)
+- [`median(::UnivariateDistribution)`](@ref)
+- [`rand(::UnivariateDistribution)`](@ref)
+- [`rand!(::UnivariateDistribution, ::AbstractArray)`](@ref)
+
+Some functions to compute statistics are available for the censored distribution if they are also available for its truncation:
+- [`mean(::UnivariateDistribution)`](@ref)
+- [`var(::UnivariateDistribution)`](@ref)
+- [`std(::UnivariateDistribution)`](@ref)
+- [`entropy(::UnivariateDistribution)`](@ref)
+
+For example, these functions are available for the following uncensored distributions:
+- `DiscreteUniform`
+- `Exponential`
+- `LogUniform`
+- `Normal`
+- `Uniform`
+
+[`mode`](@ref) is not implemented for censored distributions.

docs/src/convolution.md

@@ -0,0 +1,11 @@
+# Convolutions
+
+A [convolution of two probability distributions](https://en.wikipedia.org/wiki/List_of_convolutions_of_probability_distributions)
+is the probability distribution of the sum of two independent random variables that are
+distributed according to these distributions.
+
+The convolution of two distributions can be constructed with [`convolve`](@ref).
+
+```@docs
+convolve
+```

docs/src/index.md

@@ -7,4 +7,4 @@ The [*Distributions*](https://github.com/JuliaStats/Distributions.jl) package pr
 * Probability density/mass functions (pdf) and their logarithm (logpdf)
 * Moment-generating functions and characteristic functions
 * Maximum likelihood estimation
-* Distribution composition (Cartesian product of distributions, truncated distributions)
+* Distribution composition and derived distributions (Cartesian product of distributions, truncated distributions, censored distributions)

docs/src/starting.md

@@ -58,7 +58,7 @@ Each type splits further into `Discrete` and `Continuous`.
 For instance, you can define the following distributions (among many others):
 
 ```julia
-julia> Binomial(p) # Discrete univariate
+julia> Binomial(n, p) # Discrete univariate
 julia> Cauchy(u, b)  # Continuous univariate
 julia> Multinomial(n, p) # Discrete multivariate
 julia> Wishart(nu, S) # Continuous matrix-variate

docs/src/truncate.md

@@ -41,8 +41,4 @@ are defined for all truncated univariate distributions:
 
 Functions to compute statistics, such as `mean`, `mode`, `var`, `std`, and `entropy`, are not available for generic truncated distributions.
 Generally, there are no easy ways to compute such quantities due to the complications incurred by truncation.
-However, these methods are supported for truncated normal distributions `Truncated{<:Normal}`.
-
-```@docs
-TruncatedNormal
-```
+However, these methods are supported for truncated normal distributions `Truncated{<:Normal}` which can be constructed with `truncated(::Normal, ...)`.

docs/src/types.md

@@ -92,4 +92,4 @@ const DiscreteMatrixDistribution         = Distribution{Matrixvariate, Discrete}
 const ContinuousMatrixDistribution       = Distribution{Matrixvariate, Continuous}
 ```
 
-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).
+All methods applicable to `Sampleable` also apply 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).

docs/src/univariate.md

@@ -297,15 +297,6 @@ Levy
 plotdensity((0, 20), Levy, (0, 1)) # hide
 ```
 
-```@docs
-LocationScale
-```
-```@example plotdensity
-plotdensity(
-    (-2, 5), LocationScale(2, 1, Normal(0, 1)); title="LocationScale(2, 1, Normal(0, 1))",
-) # hide
-```
-
 ```@docs
 Logistic
 ```

src/Distributions.jl

@@ -182,6 +182,7 @@ export
     canonform,          # get canonical form of a distribution
     ccdf,               # complementary cdf, i.e. 1 - cdf
     cdf,                # cumulative distribution function
+    censored,           # censor a distribution with a lower and upper bound
     cf,                 # characteristic function
     cquantile,          # complementary quantile (i.e. using prob in right hand tail)
     component,          # get the k-th component of a mixture model
@@ -296,6 +297,7 @@ include("samplers.jl")
 include("product.jl")
 include("reshaped.jl")
 include("truncate.jl")
+include("censored.jl")
 include("conversion.jl")
 include("convolution.jl")
 include("qq.jl")
@@ -335,7 +337,7 @@ information.
 Supported distributions:
 
     Arcsine, Bernoulli, Beta, BetaBinomial, BetaPrime, Binomial, Biweight,
-    Categorical, Cauchy, Chi, Chisq, Cosine, DiagNormal, DiagNormalCanon,
+    Categorical, Cauchy, Censored, Chi, Chisq, Cosine, DiagNormal, DiagNormalCanon,
     Dirichlet, DiscreteUniform, DoubleExponential, EdgeworthMean,
     EdgeworthSum, EdgeworthZ, Erlang,
     Epanechnikov, Exponential, FDist, FisherNoncentralHypergeometric,