Metadata-Version: 2.4
Name: deup
Version: 0.1.1
Summary: Direct Epistemic Uncertainty Prediction (DEUP) for any scikit-learn model, with first-class time-series support.
Project-URL: Homepage, https://github.com/ursinasanderink/deup
Project-URL: Repository, https://github.com/ursinasanderink/deup
Project-URL: Issues, https://github.com/ursinasanderink/deup/issues
Author: Ursina Sanderink
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: conformal-prediction,deup,epistemic-uncertainty,machine-learning,scikit-learn,time-series,uncertainty
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: numpy>=1.23
Requires-Dist: scikit-learn>=1.3
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pre-commit>=3.5; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
Provides-Extra: finance
Requires-Dist: pandas>=2.0; extra == 'finance'
Provides-Extra: gbm
Requires-Dist: lightgbm>=4.0; extra == 'gbm'
Provides-Extra: torch
Requires-Dist: gpytorch>=1.11; extra == 'torch'
Requires-Dist: torch>=2.0; extra == 'torch'
Description-Content-Type: text/markdown

# deup

**Direct Epistemic Uncertainty Prediction (DEUP) for any scikit-learn model — with first-class, leakage-correct time-series support.**

[![PyPI](https://img.shields.io/pypi/v/deup)](https://pypi.org/project/deup/)
[![CI](https://github.com/ursinasanderink/deup/actions/workflows/ci.yml/badge.svg)](https://github.com/ursinasanderink/deup/actions/workflows/ci.yml)
[![Docs](https://img.shields.io/badge/docs-mkdocs-blue)](https://ursinasanderink.github.io/deup/)

DEUP estimates *epistemic* uncertainty by training a secondary **error predictor** on
your model's **out-of-sample** errors — no ensembles, no Bayesian retraining, works
with the model you already use. The method is due to
[Lahlou et al., 2023 (TMLR)](https://openreview.net/forum?id=eGLdVRvvfQ); this package
is a maintained, installable, scikit-learn-compatible implementation of it.

Repository: <https://github.com/ursinasanderink/deup> · Docs: <https://ursinasanderink.github.io/deup/>

## Quickstart

```python
from sklearn.ensemble import RandomForestRegressor
from deup import DEUPRegressor

model = DEUPRegressor(base_model=RandomForestRegressor())
model.fit(X_train, y_train)

pred, unc = model.predict(X_test, return_uncertainty=True)
```

For time-series / cross-sectional data, pass a leakage-safe splitter:

```python
from deup.splitters import PurgedWalkForward

model = DEUPRegressor(base_model=my_model, cv=PurgedWalkForward(embargo=5))
```

## Install

```bash
pip install deup            # core (numpy + scikit-learn)
pip install "deup[gbm]"     # + LightGBM error predictor
pip install "deup[docs]"    # + MkDocs site locally
```

## Why this exists

The only public DEUP code is a 3-year-old research repo of notebooks; no maintained
`pip`-installable package existed until now. Major UQ libraries
(`torch-uncertainty`, `uncertainty-toolbox`, `MAPIE`) don't implement DEUP. `deup`
fills that gap with **correct out-of-fold error construction** for time-series /
cross-sectional data.

On California housing (v0.1 benchmark), DEUP uncertainty ranks test errors better
than ensemble disagreement or a conformal residual baseline — see [BENCHMARKS.md](BENCHMARKS.md).

## Status / roadmap

**v0.1 (released):** `DEUPRegressor`, OOF collector, splitters, full loss registry
(squared / Brier / pinball / rank), target transforms (log / asinh), benchmark, docs.

**v0.2:** `DEUPClassifier` / `DEUPRanker`, conformal intervals, aleatoric decomposition,
density/GP features, aggregation-reliability diagnostics.

## Citing

If you use `deup`, please cite both this software (see [`CITATION.cff`](CITATION.cff))
and the original DEUP paper (Lahlou et al., 2023).

## License

Apache-2.0. See [`LICENSE`](LICENSE).
