naereen / kullbackleibler.jl

💫 Fast Julia implementation of various Kullback-Leibler divergences for 1D parametric distributions. 🏋 Also provides optimized code for kl-UCB indexes

Julia implementation of Kullback-Leibler divergences and kl-UCB indexes

This repository contains a small, simple and efficient module, implementing various Kullback-Leibler divergences for parametric 1D continuous or discrete distributions.

References

• Garivier & Cappé & Kaufmann, 2012, for the pymaBandits project on which this implementation is based,
• Besson, 2018, SMPyBandits project for improvements on the initial implementation,
• Filippi & Cappé & Garivier, 2011,
• Garivier & Cappé, 2011,
• Kullback & Leibler, 1951 for the first article introducing the so-called Kullback & Leibler divergences.

Examples

Simple usage

If the KullbackLeibler.jl file is accessible in your PATH or in Python's path:

julia> using KullbackLeibler
julia> KullbackLeibler.klBern(0.5, 0.5)
0.0
julia> KullbackLeibler.klBern(0.1, 0.9)
1.757779...
julia> KullbackLeibler.klBern(0.9, 0.1)  # And this KL is symmetric
1.757779...
julia> KullbackLeibler.klBern(0.4, 0.5)
0.020135...
julia> KullbackLeibler.klBern(0.01, 0.99)
4.503217...

You can also use the common function that supports different distributions using the Distributions module.

julia> using Distributions
julia> Bern1 = Distributions.Bernoulli(0.33)
Distributions.Bernoulli{Float64}(p=0.33)
julia> Bern2 = Distributions.Bernoulli(0.42)
Distributions.Bernoulli{Float64}(p=0.42)
julia> ex_kl_1 = KL( Bern1, Bern2 )  # Calc KL divergence for Bernoulli R.V
0.017063...
julia> klBern(0.33, 0.42)  # same!
0.017063...

Vectorized version?

All functions are not vectorized, and assume only one value for each argument. If you want vectorized function, please ask and we will try to add them.

Documentation

See this file.

---

Install and build

Manually ?

Easy! Download the KullbackLeibler.jl and copy it to your working folder.

I will add this package to METADATA.jl as soon as possible, and then it will be possible to install it using:

julia> Pkg.add("KullbackLeibler")

---

Python implementation ?

This module was initially a Python module, see here on GitHub.

---

About

Language and dependencies

Julia, v0.6+.

Dependencies

• Distributions, v0.15+.

📜 License ?

MIT Licensed (file LICENSE). © Lilian Besson, 2018.

kullbackleibler.jl's Issues

Create a method KL() to give a common interface

The current implementation needs to call klXYZ for each of the distribution XYZ. It will be great if you can provide a common interface to call KL divergence and dispatch depending on the type of the argument you get.
Ex:

using Distributions
# Example
KL( X1::Distributions.Bernoulli, X2::Distributions.Bernoulli ) = klBern( X1.p, X2.p )
KL( X1::Distributions.Exponential, X2::Distributions.Exponential ) = klExp( X1.θ, X2.θ )
# Use case
X = Bernoulli(0.33)
Y = Bernoulli(0.42)
d1 = KL( X, Y ) # Calc KL divergence for Bernoullli R.V
X = Exponential( 0.33 )
Y = Exponential( 0.42 )
d2 = KL( X, Y) # Calc KL div for Exponential R.V

I think this way, the users don't have to remember all the klXYZ function.

Test of an issue I want to move to https://github.com/Naereen/KullbackLeibler.jl/issues

Finish publishing this

• Publish it
• Host doc on naereen.github.io
• Publish it to METADATA.jl ?