Metadata-Version: 2.4
Name: epkde
Version: 0.1.1
Summary: Bayesian bandwidth selection for multivariate KDE via Expectation Propagation
Author-email: Maurizio Filippone <maurizio.filippone@kaust.edu.sa>
License: GPL-3.0
Project-URL: Homepage, https://github.com/mauriziofilippone/epkde-python
Project-URL: Repository, https://github.com/mauriziofilippone/epkde-python
Project-URL: Bug Tracker, https://github.com/mauriziofilippone/epkde-python/issues
Keywords: multivariate,kernel density estimation,bandwidth selection,Bayesian inference,expectation propagation,machine learning
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.22
Requires-Dist: scipy>=1.8
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: matplotlib; extra == "dev"

# epkde

**Bayesian Bandwidth Selection for Multivariate KDE via Expectation Propagation**

`epkde` implements the approximate Bayesian method for bandwidth selection in
multivariate kernel density estimation (KDE) from Filippone & Sanguinetti
(2011). The method uses the Expectation Propagation (EP) algorithm to
approximate the posterior distribution of the kernel precision matrix under a
leave-one-out cross-validated likelihood.

Three covariance structures are supported:

- **Isotropic** — scalar precision (fastest)
- **Diagonal** — per-dimension precisions
- **Full** — unconstrained precision matrix

An online variant is also provided for the isotropic case, allowing incremental
updates as new data arrive.

## Installation

```bash
pip install epkde
```

## Quick start

```python
import numpy as np
from epkde import ep_kde_isotropic, ep_kde_diagonal, kde_predict, model_evidence

rng = np.random.default_rng(1)
x = rng.standard_normal((200, 2))   # 200 bivariate observations

# Fit isotropic EP bandwidth
fit = ep_kde_isotropic(x, prior_shape=1.0, prior_rate=1.0)
print("Posterior mean precision:", fit.post_shape / fit.post_rate)
print("Log model evidence:", fit.log_evidence)

# Evaluate the KDE at test points
x_test = np.array([[0.0, 0.0], [1.0, 1.0]])
lam = fit.post_shape / fit.post_rate * np.eye(2)
p_hat = kde_predict(x_test, x, lam)

# Compare models via Bayes factors
fit_diag = ep_kde_diagonal(x, prior_shape=np.ones(2), prior_rate=np.ones(2))
print("Log BF (diagonal vs isotropic):",
      model_evidence(fit_diag) - model_evidence(fit))
```

## Functions

| Function | Description |
|---|---|
| `ep_kde_isotropic()` | EP for scalar (isotropic) precision |
| `ep_kde_diagonal()` | EP for diagonal precision matrix |
| `ep_kde_full()` | EP for full precision matrix |
| `ep_kde_online()` | Online EP update for isotropic precision |
| `kde_predict()` | Evaluate the KDE at test points |
| `model_evidence()` | Extract log model evidence for model comparison |

## Reference

Filippone, M. & Sanguinetti, G. (2011). Approximate inference of the bandwidth
in multivariate kernel density estimation. *Computational Statistics & Data
Analysis*, 55(12), 3104–3122. <https://doi.org/10.1016/j.csda.2011.05.023>

## License

GPL-3 © Maurizio Filippone
