Metadata-Version: 2.4
Name: uxplain
Version: 0.3.0
Summary: Explainability for conformal prediction uncertainty — regression and classification.
Keywords: conformal prediction,uncertainty quantification,explainability,xai,shap,lime,pdp,machine learning,interpretable ml
Author: Tomas Rodriguez Taborda, Veronica Seguro Varela, Rafael Izbicki, Johnatan Cardona Jimenez
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
License-File: LICENSE
Requires-Dist: numpy>=1.26
Requires-Dist: scikit-learn>=1.4
Requires-Dist: shap>=0.45
Requires-Dist: crepes>=0.9.1
Requires-Dist: lime>=0.2
Requires-Dist: matplotlib>=3.8
Requires-Dist: pandas>=1.5
Requires-Dist: pytest>=8.0 ; extra == "dev"
Requires-Dist: pytest-cov>=5.0 ; extra == "dev"
Requires-Dist: ruff>=0.4 ; extra == "dev"
Requires-Dist: mkdocs>=1.6 ; extra == "docs"
Requires-Dist: build>=1.2 ; extra == "release"
Requires-Dist: twine>=6.1 ; extra == "release"
Project-URL: Bug Tracker, https://github.com/torodriguezt/uxplain/issues
Project-URL: Documentation, https://github.com/torodriguezt/uxplain/tree/main/docs/docs
Project-URL: Homepage, https://github.com/torodriguezt/uxplain
Project-URL: Repository, https://github.com/torodriguezt/uxplain
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: release

# uxplain

`uxplain` explains which features make a model more or less uncertain. It wraps
scikit-learn compatible models with conformal prediction and uses SHAP, PDP/ICE
or LIME to explain summaries of their prediction intervals or sets.

The package supports **regression**, through crepes and conformalized quantile
regression (CQR), and **classification**, through crepes. A single pipeline handles
model fitting, calibration and explanation.

## Installation

Requires Python 3.10 or later.

```bash
pip install uxplain
```

## Regression

Explain prediction interval width with SHAP. `fit()` automatically reserves a
separate calibration sample.

```python
from sklearn.datasets import make_regression
from sklearn.ensemble import RandomForestRegressor
from sklearn.model_selection import train_test_split
from uxplain import UncertaintyExplanationPipeline

X, y = make_regression(n_samples=300, n_features=4, noise=15, random_state=42)
X_train, X_test, y_train, y_test = train_test_split(X, y, random_state=42)

pipe = UncertaintyExplanationPipeline(
    model=RandomForestRegressor(n_estimators=50, random_state=42),
    confidence=0.9,
    xai_method="shap",
    uncertainty_metric="width",
    random_state=42,
)
pipe.fit(X_train, y_train)
result = pipe.explain(X_test[:5], show_plots=False)

print(result.interval_width)
print(result.explanation_values)
```

## Classification

Use a classifier and `set_size` to explain how many labels enter the prediction set.

```python
from sklearn.datasets import load_iris
from sklearn.ensemble import RandomForestClassifier

X, y = load_iris(return_X_y=True)
X_train, X_test, y_train, y_test = train_test_split(X, y, random_state=42)

pipe = UncertaintyExplanationPipeline(
    model=RandomForestClassifier(n_estimators=50, random_state=42),
    uncertainty_metric="set_size",
    random_state=42,
)
pipe.fit(X_train, y_train)
result = pipe.explain(X_test[:5], show_plots=False)

print(result.prediction_set)
print(result.explanation_values)
```

## Learn more

The [getting-started guide](https://github.com/torodriguezt/uxplain/blob/main/docs/docs/getting-started.md)
covers calibration, other uncertainty summaries and explainer options. See the
[notebooks](https://github.com/torodriguezt/uxplain/tree/main/notebooks) for more examples
and the [release guide](https://github.com/torodriguezt/uxplain/blob/main/docs/docs/getting-started.md#releasing)
for development and publishing.

Coverage guarantees depend on the conformal method's
[statistical assumptions](https://github.com/torodriguezt/uxplain/blob/main/docs/docs/getting-started.md#statistical-scope-and-limitations);
they do not extend to the explanations themselves.

## Authors

- **Tomas Rodriguez Taborda** — Universidad Nacional de Colombia, Medellín
- **Veronica Seguro Varela** — Universidad Nacional de Colombia, Medellín
- **Rafael Izbicki** — Federal University of São Carlos
- **Johnatan Cardona Jimenez** — Universidad Nacional de Colombia, Medellín

## License

[MIT](https://github.com/torodriguezt/uxplain/blob/main/LICENSE).

