uxplain 0.3.0__tar.gz

uxplain-0.3.0/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+All notable changes to **uxplain** are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/),
+and the project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.3.0] - Unreleased
+
+### Added
+- PNAD Continua and GEIH dataset loaders, without bundling survey microdata.
+- Exact TreeSHAP for supported affine summaries of built-in conformal predictors,
+  with generic SHAP as the fallback.
+- Python 3.13 CI coverage and Linux/Windows distribution checks that install the
+  wheel and run the tests included in the source archive outside the checkout.
+- Runnable getting-started examples and release-validation instructions.
+
+### Fixed
+- Use label-independent automatic calibration splits for classification, matching
+  the usual split-conformal exchangeability argument; no class-based retries.
+- Reject smoothed classification targets in explainers, including with fixed
+  seeds, while retaining smoothed prediction as an opt-in.
+- Validate conformal methods, task names, coverage levels and calibration arrays;
+  accept single-column targets without broadcasting CQR calibration scores.
+- Return unbounded regression intervals for Mondrian groups absent from calibration.
+- Keep Mondrian assignments deterministic when scores tie and seed permutation
+  SHAP without changing the caller's NumPy random state.
+- Restrict the TreeSHAP shortcut to supported algebraic decompositions instead of
+  inferring global affinity from agreement on a finite sample.
+- Prevent target leakage for alternative dataset targets and reject ambiguous
+  joins of GEIH modules; preserve missing occupation and informality values.
+- Preserve DataFrame feature order and reset pipeline state on refitting.
+- Reject non-finite explanation targets explicitly, while allowing unbounded
+  conformal prediction intervals.
+- Plot single-observation SHAP slices and PDP interactions with constant features;
+  require an explicit baseline for SHAP waterfall plots.
+
+### Changed
+- Document coverage assumptions, signed CQR spans and pending real-microdata
+  revalidation of dataset loaders; label width plots as signed spans.
+- Use SPDX license metadata and include tests in the source distribution.
+- The manuscript's replication results must be regenerated with this version
+  before submission; this entry describes a local release candidate.
+
+## [0.2.3]
+
+### Added
+- **PDP-based global feature importance.** `PDPExplanation` now carries an
+  `importance` field — the standard deviation of each feature's averaged
+  partial-dependence curve (Greenwell et al., 2018). Render it with the new
+  `plot_kind="importance"` for the PDP backend.
+- Runnable demo notebooks (`notebooks/01_regression.ipynb`,
+  `notebooks/02_classification.ipynb`) covering conformal outputs, all SHAP
+  plot kinds via `generate_shap_plots`, PDP / ICE / PDP+ICE / 2D PDP /
+  importance, CQR with quantile regressors, and the classification metrics.
+
+### Fixed
+- README: the PDP importance plot kind is documented as `"importance"`
+  (was inconsistently shown as `"bar"`, which collided with the SHAP bar plot),
+  and the PDP default plot kinds now reflect the actual default (`["pdp"]`).
+
+## [0.2.0]
+
+### Added
+- Classification support: prediction sets, conformal classifiers
+  (`CrepesConformalClassifier`), and classification uncertainty metrics
+  (`set_size`, `credibility`, `confidence`).
+- Package renamed to `uxplain` and prepared for PyPI.
+
+## [0.1.0]
+
+### Added
+- Initial release: regression conformal predictors (`CrepesConformalPredictor`,
+  `CQRConformalPredictor`) with SHAP, PDP, and LIME explainability of
+  interval-derived uncertainty metrics.

uxplain-0.3.0/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+Copyright (c) 2025-2026, Tomas Rodriguez Taborda, Veronica Seguro Varela, Rafael Izbicki, Johnatan Cardona Jimenez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

uxplain-0.3.0/PKG-INFO

@@ -0,0 +1,134 @@
+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).
+

uxplain-0.3.0/README.md

@@ -0,0 +1,91 @@
+# 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).

uxplain-0.3.0/pyproject.toml

@@ -0,0 +1,109 @@
+[build-system]
+requires = ["flit_core >=3.12,<4"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name = "uxplain"
+dynamic = ["version"]
+description = "Explainability for conformal prediction uncertainty — regression and classification."
+authors = [
+  { name = "Tomas Rodriguez Taborda" },
+  { name = "Veronica Seguro Varela" },
+  { name = "Rafael Izbicki" },
+  { name = "Johnatan Cardona Jimenez" },
+]
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+keywords = [
+    "conformal prediction",
+    "uncertainty quantification",
+    "explainability",
+    "xai",
+    "shap",
+    "lime",
+    "pdp",
+    "machine learning",
+    "interpretable ml",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "numpy>=1.26",
+    "scikit-learn>=1.4",
+    "shap>=0.45",
+    "crepes>=0.9.1",
+    "lime>=0.2",
+    "matplotlib>=3.8",
+    "pandas>=1.5",
+]
+
+[project.urls]
+Homepage = "https://github.com/torodriguezt/uxplain"
+Repository = "https://github.com/torodriguezt/uxplain"
+Documentation = "https://github.com/torodriguezt/uxplain/tree/main/docs/docs"
+"Bug Tracker" = "https://github.com/torodriguezt/uxplain/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.4",
+]
+release = [
+    "build>=1.2",
+    "twine>=6.1",
+]
+docs = ["mkdocs>=1.6"]
+
+[tool.flit.sdist]
+include = ["LICENSE", "README.md", "CHANGELOG.md", "pyproject.toml", "tests/"]
+exclude = [
+    "docs/",
+    "notebooks/",
+    "models/",
+    "reports/",
+    "references/",
+    "replication/",
+    "figures/",
+    "uxplain-main/",
+    "*.tex",
+    "*.bib",
+    "*.pdf",
+    "*.zip",
+    "SUBMISSION_CHECKLIST.md",
+    "demo.ipynb",
+    "Makefile",
+    "requirements.txt",
+    ".github/",
+    "**/__pycache__/",
+    "**/*.pyc",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 99
+src = ["uxplain"]
+include = ["pyproject.toml", "uxplain/**/*.py"]
+extend-exclude = ["uxplain-main"]
+
+[tool.ruff.lint]
+extend-select = ["I"]  # Add import sorting
+
+[tool.ruff.lint.isort]
+known-first-party = ["uxplain"]
+force-sort-within-sections = true

uxplain-0.3.0/tests/conftest.py

@@ -0,0 +1,76 @@
+import numpy as np
+import pytest
+from sklearn.datasets import make_classification
+from sklearn.ensemble import GradientBoostingRegressor, RandomForestClassifier
+from sklearn.linear_model import Ridge
+from sklearn.model_selection import train_test_split
+
+
+@pytest.fixture(scope="module")
+def data():
+    rng = np.random.default_rng(0)
+    n = 200
+    X = rng.standard_normal((n, 4))
+    y = X @ np.array([1.5, -2.0, 0.5, 1.0]) + rng.standard_normal(n) * 0.5
+    X_tr, X_te, y_tr, y_te = train_test_split(X, y, test_size=0.25, random_state=0)
+    X_tr, X_cal, y_tr, y_cal = train_test_split(X_tr, y_tr, test_size=0.25, random_state=0)
+    return {
+        "X_train": X_tr,
+        "X_calib": X_cal,
+        "X_test": X_te,
+        "y_train": y_tr,
+        "y_calib": y_cal,
+        "y_test": y_te,
+    }
+
+
+@pytest.fixture
+def ridge():
+    return Ridge()
+
+
+@pytest.fixture
+def quantile_lower():
+    return GradientBoostingRegressor(
+        loss="quantile", alpha=0.05, n_estimators=30, random_state=0
+    )
+
+
+@pytest.fixture
+def quantile_upper():
+    return GradientBoostingRegressor(
+        loss="quantile", alpha=0.95, n_estimators=30, random_state=0
+    )
+
+
+@pytest.fixture(scope="module")
+def classification_data():
+    X, y = make_classification(
+        n_samples=400,
+        n_features=4,
+        n_informative=3,
+        n_redundant=0,
+        n_classes=3,
+        n_clusters_per_class=1,
+        random_state=0,
+    )
+    X_tr, X_te, y_tr, y_te = train_test_split(
+        X, y, test_size=0.25, random_state=0,
+    )
+    X_tr, X_cal, y_tr, y_cal = train_test_split(
+        X_tr, y_tr, test_size=0.25, random_state=0,
+    )
+    return {
+        "X_train": X_tr,
+        "X_calib": X_cal,
+        "X_test": X_te,
+        "y_train": y_tr,
+        "y_calib": y_cal,
+        "y_test": y_te,
+        "n_classes": 3,
+    }
+
+
+@pytest.fixture
+def classifier():
+    return RandomForestClassifier(n_estimators=20, random_state=0)