Skip to content

Commit

Permalink
Replace hasdensity by DensityKind (#9)
Browse files Browse the repository at this point in the history
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]>
  • Loading branch information
3 people authored Nov 16, 2021
1 parent ccade11 commit e71eb2d
Show file tree
Hide file tree
Showing 10 changed files with 318 additions and 124 deletions.
2 changes: 1 addition & 1 deletion Project.toml
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 3 additions & 2 deletions docs/make.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
9 changes: 7 additions & 2 deletions docs/src/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
31 changes: 16 additions & 15 deletions docs/src/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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`.
3 changes: 2 additions & 1 deletion src/DensityInterface.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Loading

2 comments on commit e71eb2d

@oschulz
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@JuliaRegistrator
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Registration pull request created: JuliaRegistries/General/48881

After the above pull request is merged, it is recommended that a tag is created on this repository for the registered package version.

This will be done automatically if the Julia TagBot GitHub Action is installed, or can be done manually through the github interface, or via:

git tag -a v0.4.0 -m "<description of version>" e71eb2ded6f3320d66a6d7efc615e3e60dddb58f
git push origin v0.4.0

Please sign in to comment.