Add Censored distribution

Project.toml

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

docs/make.jl

@@ -11,6 +11,7 @@ makedocs(
         "types.md",
         "univariate.md",
         "truncate.md",
+        "censored.md",
         "multivariate.md",
         "matrix.md",
         "reshape.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/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)

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
@@ -295,6 +296,7 @@ include("samplers.jl")
 # others
 include("reshaped.jl")
 include("truncate.jl")
+include("censored.jl")
 include("conversion.jl")
 include("convolution.jl")
 include("qq.jl")
@@ -334,7 +336,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,