Metadata-Version: 2.4
Name: yemale
Version: 0.1.0a2
Summary: Multivariate conformal prediction and predictive distributions via optimal transport
Author-email: Eugene Ndiaye <yemaledev@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://yemale.github.io/
Project-URL: Repository, https://github.com/yemale/yemale
Keywords: conformal prediction,vector-valued scores,predictive distributions,optimal transport
Classifier: Development Status :: 3 - Alpha
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: numba<0.68,>=0.61
Provides-Extra: docs
Requires-Dist: sphinx<9,>=8.2; extra == "docs"
Requires-Dist: myst-parser<5,>=4; extra == "docs"
Requires-Dist: sphinx-book-theme<2,>=1.1; extra == "docs"
Dynamic: license-file

# yemale

**Build prediction regions. Generate possible outcomes. Evaluate their consequences.**

yemale builds multivariate conformal predictive distributions from predictions
and observed outcomes. Use them to construct prediction regions, draw samples,
assign probabilities to events, and compute expectations—for example, the
expected cost of a decision.

The conformal construction provides finite-sample calibration without assuming
a particular data distribution.

It uses optimal transport to handle scalar and vector-valued scores, without
first reducing vectors to a scalar summary. The transport engine also works
independently.

## Install

```bash
python -m pip install yemale==0.1.0a2
```

Alpha release.

## With your model

Start with a fitted model and held-out data `X_cal, y_cal` that were not used
to train it. These data are used to calibrate the prediction regions.

```python
from yemale import extend

model = extend(model)
model.conformalize(X_cal, y_cal)

cpd = model.predict_distribution(X_new)
region = cpd.region(0.9, rng=0)
region.contains(y_new)  # One Boolean per new outcome.
```

`model.predict(X_new)` still returns the original point predictions.

Already have predictions? Use `yemale.conformalize(predictions, outcomes)`.

## Sampling and summaries

Use the model's prediction as the fixed candidate for sampling:

```python
candidate = model.predict(X_new[:1])[0]
cpd = model.predict_distribution(X_new[:1], candidate=candidate)
cpd.sample(1000, rng=0)
cpd.mean()
cpd.cov()
```

## Explore

- [Conformal prediction](https://yemale.github.io/conformal.html): use a model or prediction
  arrays, test outcomes, and select candidates.
- [Optimal transport](https://yemale.github.io/ot.html): fit point clouds, construct regions,
  and work with reference and predictive distributions.
- [Mathematical guide](https://yemale.github.io/usage.html): the construction and its connection to the API.
- [Changelog](https://github.com/yemale/yemale/blob/main/CHANGELOG.md).

## License

Apache-2.0.
