Replace hasdensity by DensityKind (#9)

Also changes behavior of `logfuncdensity` to always return a density and
adds `funcdensity`,

Co-authored-by: Philipp Gabler <[email protected]>
Co-authored-by: David Widmann <[email protected]>

Author: 3 people

Project.toml

@@ -1,6 +1,6 @@
 name = "DensityInterface"
 uuid = "b429d917-457f-4dbc-8f4c-0cc954292b1d"
-version = "0.3.3"
+version = "0.4.0"
 
 [deps]
 InverseFunctions = "3587e190-3f89-42d0-90ee-14403ec27112"

README.md

@@ -6,7 +6,7 @@
 [![Build Status](https://github.com/JuliaMath/DensityInterface.jl/workflows/CI/badge.svg?branch=master)](https://github.com/JuliaMath/DensityInterface.jl/actions?query=workflow%3ACI)
 [![Codecov](https://codecov.io/gh/JuliaMath/DensityInterface.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/JuliaMath/DensityInterface.jl)
 
-This package defines an interface for mathematical/statistical densities in Julia. See the documentation for details.
+This package defines an interface for mathematical/statistical densities and objects associated with a density in Julia. See the documentation for details.
 
 
 ## Documentation

docs/make.jl

@@ -13,8 +13,9 @@ DocMeta.setdocmeta!(
     :DocTestSetup,
     quote
         using DensityInterface
-        d = logfuncdensity(x -> x^2)
-        log_f = logdensityof(d)
+        object = logfuncdensity(x -> -x^2)
+        log_f = logdensityof(object)
+        f = densityof(object)
         x = 4
     end;
     recursive=true,

docs/src/api.md

@@ -3,19 +3,24 @@
 ## Interface
 
 ```@docs
-hasdensity
 logdensityof
 logdensityof(::Any)
 logfuncdensity
+funcdensity
 densityof
 densityof(::Any)
 ```
 
-
 ## Types
 
 ```@docs
+IsDensity
+HasDensity
+IsOrHasDensity
+NoDensity
+DensityKind
 DensityInterface.LogFuncDensity
+DensityInterface.FuncDensity
 ```
 
 ## Test utility

docs/src/index.md

@@ -12,49 +12,51 @@ end
 DensityInterface
 ```
 
-This package defines an interface for mathematical/statistical densities and objects associated with a density in Julia. The interface comprises the functions [`hasdensity`](@ref),  [`logdensityof`](@ref)/[`densityof`](@ref)[^1] and [`logfuncdensity`](@ref).
+This package defines an interface for mathematical/statistical densities and objects associated with a density in Julia. The interface comprises the type [`DensityKind`](@ref) and the functions [`logdensityof`](@ref)/[`densityof`](@ref)[^1] and [`logfuncdensity`](@ref)/[`funcdensity`](@ref).
 
 The following methods must be provided to make a type (e.g. `SomeDensity`) compatible with the interface:
 
 ```jldoctest a
 import DensityInterface
 
-DensityInterface.hasdensity(::SomeDensity) = true
-DensityInterface.logdensityof(d::SomeDensity, x) = log_of_d_at(x)
+@inline DensityInterface.DensityKind(::SomeDensity) = IsDensity()
+DensityInterface.logdensityof(object::SomeDensity, x) = log_of_d_at(x)
 
-DensityInterface.logdensityof(SomeDensity(), x) isa Real
+object = SomeDensity()
+DensityInterface.logdensityof(object, x) isa Real
 
 # output
 
 true
 ```
 
-The object `d` may be a density itself or something that can be said to have a density. If `d` is a distribution, the density is its probability density function. In the measure theoretical sense, the density function is the Radon–Nikodym derivative of `d` with respect to an implicit base measure. In statistical inference applications, for example, `d` might be a likelihood, prior or posterior[^2].
+`object` may be/represent a density itself (`DensityKind(object) === IsDensity()`) or it may be something that can be said to have a density (`DensityKind(object) === HasDensity()`)[^2].
 
-DensityInterface automatically provides `logdensityof(d)`, equivalent to `x -> logdensityof(d, x)`. This constitutes a convenient way of passing a (log-)density function to algorithms like optimizers, samplers, etc.:
+In statistical inference applications, for example, `object` might be a likelihood, prior or posterior.
+
+DensityInterface automatically provides `logdensityof(object)`, equivalent to `x -> logdensityof(object, x)`. This constitutes a convenient way of passing a (log-)density function to algorithms like optimizers, samplers, etc.:
 
 ```jldoctest a
 using DensityInterface
 
-d = SomeDensity()
-log_f = logdensityof(d)
-log_f(x) == logdensityof(d, x)
+object = SomeDensity()
+log_f = logdensityof(object)
+log_f(x) == logdensityof(object, x)
 
 # output
 
 true
 ```
 
 ```julia
-SomeOptimizerPackage.maximize(logdensityof(d), x_init)
+SomeOptimizerPackage.maximize(logdensityof(object), x_init)
 ```
 
 Reversely, a given log-density function `log_f` can be converted to a DensityInterface-compatible density object using [`logfuncdensity`](@ref):
 
 ```julia
-d = logfuncdensity(log_f)
-hasdensity(d) == true
-logdensityof(d, x) == log_f(x)
+object = logfuncdensity(log_f)
+DensityKind(object) === IsDensity() && logdensityof(object, x) == log_f(x)
 
 # output
 
@@ -64,5 +66,4 @@ true
 
 [^1]: The function names `logdensityof` and `densityof` were chosen to convey that the target object may either *be* a density or something that can be said to *have* a density. They also have less naming conflict potential than `logdensity` and esp. `density` (the latter already being exported by Plots.jl).
 
-[^2]: The package [`MeasureTheory`](https://github.com/cscherrer/MeasureTheory.jl) provides tools to work with densities and measures that go beyond the density in 
-respect to an implied base measure.
+[^2]: The package [`Distributions`](https://github.com/JuliaStats/Distributions.jl) supports `DensityInterface` for `Distributions.Distribution`.

src/DensityInterface.jl

@@ -3,7 +3,8 @@
 """
     DensityInterface
 
-Trait-based interface for mathematical/statistical densities
+Trait-based interface for mathematical/statistical densities and objects
+associated with a density.
 """
 module DensityInterface