Add Censored distribution (#1470)

* Implement Censored * Export Censored and censored * Apply suggestions from code review Co-authored-by: David Widmann <devmotion@users.noreply.github.com> * Reorganize code * Move check to constructor * Make newline optional * Reformat * Improve show method * Add checks for finiteness * Implement expectations * Satisfy required params behavior * Overload truncated for DiscreteUniform * Don't re-censor * Handle case where censored to single point * Reformat * Add censored docs page * Update censored.md * Document censored * Add truncated DiscreteUniform tests * Add un-called truncated_uniform test suite * Skip check for DiscreteUniform * Add loglikelihood Useful to avoid redundant computation of bound probabilities when performing censored regression * Include bounds in support * Update src/truncated/discrete_uniform.jl Co-authored-by: David Widmann <devmotion@users.noreply.github.com> * Remove unnecessary checks for finiteness * Swap order of checks * Update censored.jl * Support using missing to specify unbounded * Apply suggestions from code review Co-authored-by: David Widmann <devmotion@users.noreply.github.com> * Improve docstrings * Reformat * Rewrap signature * Use ismissing everywhere * Reformat * Fix maximum * Fix support check * Support fields that are equivalent This allows equality checking for distributions with fields for which `==` or `isapprox` is not defined but `===` is * Add basic censored tests * Apply suggestions from code review Co-authored-by: Moritz Schauer <moritzschauer@web.de> * Resolve ambiguity * Resolve ambiguity * Use equivalence check for missing everywhere * Fix ccdf and logccdf * Better construct mixture equivalent * Implement mixture model for continuous censored dists * Add uniform tests * Enhance discrete uniform tests * Add Poisson tests * Fix implementation of entropy * Test mean/std of censored Poisson * Add normal tests * Remove unused methods * Test bounds check * Add log-likelihood test * Add test for censorship to empty interval * Support censorship to empty intervals * Add comments about expectations * Add more checks for inferrability * Test explicit expectations for DiscreteUniform * Rewrite censored docstring * Indicate interval censoring * Update docs/src/index.md Co-authored-by: Moritz Schauer <moritzschauer@web.de> * Apply suggestions from code review Co-authored-by: David Widmann <devmotion@users.noreply.github.com> * Don't use now-deleted function * Fix tes for new params definition * Make loglikelihood type-stable * Add comment about equivalence check * Unabbreviate name * Remove inlines * Add plaintext mimetype * Add more truncated DiscreteUniform tests * Add xexpx * Compute probabilities on log scale * Clarify variable names * Eliminate deprecation warnings * Fix inferrability error * Reformat * Add check_args keyword * Promote each xi * Fix checking of args * Use bounds also to set types * Use check_args macro * Check for ArgumentError * Use eps to detect empty truncation * Use more accurate variable name * Use oneunit * Improve type-stability everywhere * Exhaustively test for type-inferribility * Remove now-unneeded test * Revert "Improve type-stability everywhere" This reverts commit f024f45. * Add convenient types * Use convenient types * Add missing check for in support of uncensored * Avoid promoting inputs based on bounds * Avoid promoting inputs based on bounds * Separate expectations to own methods * Check in interval first * Don't promote input types * Apply suggestions from code review Co-authored-by: David Widmann <devmotion@users.noreply.github.com> * Remove lingering reference to udnefined type * Docstring fixes * Consistently use d0 for uncensored * Use nothing instead of missing * Reorganize * Add keyword constructor * Document and promote keyword constructors * Use keyword arguments in show * Don't use isnothing in tests * Don't print nothing Fails on old Julia versions * Export Censored * Once sentence per line * Docstring improvements * Fix variable rendering * Add missing comma * Revert "Export Censored" This reverts commit ccef571. * Prepend with module so docs build * Document with module prepended * Use function ... end syntax * Apply suggestions from code review Co-authored-by: David Widmann <devmotion@users.noreply.github.com> * LeftCensored ⇌ RightCensored * Apply suggestions from code review Co-authored-by: David Widmann <devmotion@users.noreply.github.com> * Introduce xexpy * Remove test for no-longer-supported case * Simplify implementations * Rearrange left before right * Increment version number * Use information theory notation for entropy * Use d0 notation * Add header * Test infinite bounds just in case * Apply suggestions from code review Co-authored-by: Moritz Schauer <moritzschauer@web.de> * Add and test partially truncated overloads for discrete uniform * Update src/censored.jl Co-authored-by: David Widmann <devmotion@users.noreply.github.com> Co-authored-by: David Widmann <devmotion@users.noreply.github.com> Co-authored-by: Moritz Schauer <moritzschauer@web.de>
JuliaStats · Jan 31, 2022 · 6f74846 · 6f74846 · devmotion · Jan 31, 2022
1 parent cbbc1a5
commit 6f74846
Show file tree

Hide file tree

Showing 14 changed files with 951 additions and 7 deletions.
diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "Distributions"
 uuid = "31c24e10-a181-5473-b8eb-7969acd0382f"
 authors = ["JuliaStats"]
-version = "0.25.44"
+version = "0.25.45"
 
 [deps]
 ChainRulesCore = "d360d2e6-b24c-11e9-a2a3-2a2ae2dbcce4"

diff --git a/docs/make.jl b/docs/make.jl
@@ -11,6 +11,7 @@ makedocs(
         "types.md",
         "univariate.md",
         "truncate.md",
+        "censored.md",
         "multivariate.md",
         "matrix.md",
         "reshape.md",

diff --git a/docs/src/censored.md b/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.
diff --git a/docs/src/index.md b/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)
diff --git a/src/Distributions.jl b/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,