uxplain 0.3.0__py3-none-any.whl

uxplain/__init__.py

@@ -0,0 +1,82 @@
+"""uxplain: explainability for conformal prediction uncertainty."""
+
+__version__ = "0.3.0"
+
+from uxplain.conformal.cqr_predictor import CQRConformalPredictor
+from uxplain.conformal.crepes_classifier import (
+    ClassificationConformalMethod,
+    CrepesConformalClassifier,
+)
+from uxplain.conformal.crepes_predictor import (
+    ConformalMethod,
+    CrepesConformalPredictor,
+)
+from uxplain.explainability.lime_explainer import (
+    LIMEExplanation,
+    LimeUncertaintyExplainer,
+)
+from uxplain.explainability.pdp_explainer import (
+    PDPExplanation,
+    PDPUncertaintyExplainer,
+)
+from uxplain.explainability.shap_explainer import ShapUncertaintyExplainer
+from uxplain.plotting import (
+    STYLE,
+    ice_curves,
+    lime_local,
+    pdp_curve,
+    pdp_importance,
+    pdp_interaction,
+    pdp_with_ice,
+    shap_bar,
+    shap_beeswarm,
+    shap_waterfall,
+)
+from uxplain.protocols import (
+    ConformalClassifierProtocol,
+    ConformalPredictorProtocol,
+    UncertaintyExplainerProtocol,
+)
+from uxplain.uncertainty.metrics import (
+    ClassificationMetric,
+    RegressionMetric,
+    UncertaintyMetric,
+)
+from uxplain.uq_explainer import (
+    ClassificationExplanationResult,
+    ExplanationResult,
+    UncertaintyExplanationPipeline,
+)
+
+__all__ = [
+    "STYLE",
+    "CQRConformalPredictor",
+    "ClassificationConformalMethod",
+    "ClassificationExplanationResult",
+    "ClassificationMetric",
+    "ConformalClassifierProtocol",
+    "ConformalMethod",
+    "ConformalPredictorProtocol",
+    "CrepesConformalClassifier",
+    "CrepesConformalPredictor",
+    "ExplanationResult",
+    "LIMEExplanation",
+    "LimeUncertaintyExplainer",
+    "PDPExplanation",
+    "PDPUncertaintyExplainer",
+    "RegressionMetric",
+    "ShapUncertaintyExplainer",
+    "UncertaintyExplainerProtocol",
+    "UncertaintyExplanationPipeline",
+    "UncertaintyMetric",
+    "__version__",
+    "ice_curves",
+    "lime_local",
+    "pdp_curve",
+    "pdp_importance",
+    "pdp_interaction",
+    "pdp_with_ice",
+    "shap_bar",
+    "shap_beeswarm",
+    "shap_waterfall",
+]

uxplain/conformal/__init__.py

@@ -0,0 +1,19 @@
+from uxplain.conformal.cqr_predictor import (
+    CQRConformalPredictor,
+)
+from uxplain.conformal.crepes_classifier import (
+    ClassificationConformalMethod,
+    CrepesConformalClassifier,
+)
+from uxplain.conformal.crepes_predictor import (
+    ConformalMethod,
+    CrepesConformalPredictor,
+)
+
+__all__ = [
+    "CQRConformalPredictor",
+    "ClassificationConformalMethod",
+    "ConformalMethod",
+    "CrepesConformalClassifier",
+    "CrepesConformalPredictor",
+]

uxplain/conformal/_validation.py

@@ -0,0 +1,34 @@
+"""Shared validation for the single-output conformal backends."""
+
+from numbers import Real
+
+import numpy as np
+
+
+def check_confidence(confidence):
+    if not isinstance(confidence, Real) or not 0 < confidence < 1:
+        raise ValueError(
+            f"confidence must be in (0, 1), got {confidence}. Pass the "
+            "coverage level as a fraction, e.g. 0.9 for 90%."
+        )
+
+
+def check_fit_data(X_train, y_train, X_calib, y_calib):
+    """Prevent broadcasting of column targets and mismatched calibration data."""
+    arrays = []
+    for X, y, name in (
+        (X_train, y_train, "train"), (X_calib, y_calib, "calib")
+    ):
+        X, y = np.asarray(X), np.asarray(y)
+        if X.ndim != 2 or min(X.shape) == 0:
+            raise ValueError(f"X_{name} must be a non-empty 2D array.")
+        if y.ndim == 2 and y.shape[1] == 1:
+            y = y[:, 0]
+        if y.ndim != 1:
+            raise ValueError(f"y_{name} must be one-dimensional (single output).")
+        if len(X) != len(y):
+            raise ValueError(f"X_{name} and y_{name} must have the same length.")
+        arrays.extend((X, y))
+    if arrays[0].shape[1] != arrays[2].shape[1]:
+        raise ValueError("X_train and X_calib must have the same number of features.")
+    return tuple(arrays)

uxplain/conformal/cqr_predictor.py

@@ -0,0 +1,145 @@
+"""
+Conformalized Quantile Regression predictor.
+
+Implements CQR (Romano, Patterson & Candès, 2019).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ._validation import check_confidence, check_fit_data
+
+
+class CQRConformalPredictor:
+    """
+    Conformalized Quantile Regression (CQR) predictor.
+
+    Fits two quantile regressors — one for the lower bound and one
+    for the upper bound — then calibrates them using nonconformity
+    scores on a held-out calibration set.
+
+    Parameters
+    ----------
+    lower_model
+        Quantile regressor trained at quantile level ``alpha / 2``.
+        Must expose a sklearn-compatible ``fit(X, y)`` / ``predict(X)``
+        interface.  Example::
+
+            GradientBoostingRegressor(loss="quantile", alpha=0.05)
+
+    upper_model
+        Quantile regressor trained at quantile level ``1 - alpha / 2``.
+        Example::
+
+            GradientBoostingRegressor(loss="quantile", alpha=0.95)
+
+    Notes
+    -----
+    The quantile levels baked into the models should match the
+    ``confidence`` value used at predict time (e.g. models at 0.05 / 0.95
+    pair with ``confidence=0.90``).  Changing ``confidence`` at predict
+    time still gives valid coverage via the calibration correction, but
+    intervals may be wider or narrower than optimal if the mismatch is
+    large.
+
+    CQR may return an empty prediction set (``lower > upper``), for example
+    after a negative calibration correction or quantile crossing. Endpoints
+    are preserved, so ``upper - lower`` is a signed span in that case, not
+    the nonnegative length of the empty set.
+    """
+
+    def __init__(self, lower_model, upper_model):
+        self.lower_model = lower_model
+        self.upper_model = upper_model
+
+        self._scores: np.ndarray | None = None
+        self._n_calib: int | None = None
+
+    def fit(
+        self,
+        X_train: np.ndarray,
+        y_train: np.ndarray,
+        X_calib: np.ndarray,
+        y_calib: np.ndarray,
+    ) -> None:
+        """
+        Fit quantile models and calibrate nonconformity scores.
+
+        Parameters
+        ----------
+        X_train, y_train
+            Training data.
+        X_calib, y_calib
+            Calibration data used to compute nonconformity scores.
+        """
+
+        self._scores = None
+        self._n_calib = None
+        X_train, y_train, X_calib, y_calib = check_fit_data(
+            X_train, y_train, X_calib, y_calib,
+        )
+        y_calib = np.asarray(y_calib, dtype=float)
+        if not np.all(np.isfinite(y_calib)):
+            raise ValueError("y_calib must contain only finite values.")
+
+        self.lower_model.fit(X_train, y_train)
+        self.upper_model.fit(X_train, y_train)
+
+        q_low = self._predict_quantile(self.lower_model, X_calib)
+        q_high = self._predict_quantile(self.upper_model, X_calib)
+
+        # CQR nonconformity score: max(q_low - y, y - q_high)
+        self._scores = np.maximum(q_low - y_calib, y_calib - q_high)
+        self._n_calib = len(y_calib)
+
+    def predict(
+        self,
+        X: np.ndarray,
+        confidence: float = 0.9,
+    ) -> tuple[np.ndarray, np.ndarray]:
+        """
+        Generate calibrated prediction intervals.
+
+        Parameters
+        ----------
+        X : np.ndarray
+        confidence : float
+            Desired marginal coverage level.
+
+        Returns
+        -------
+        lower : np.ndarray
+        upper : np.ndarray
+        """
+
+        if self._scores is None:
+            raise RuntimeError("CQRConformalPredictor not fitted. Call fit() first.")
+
+        check_confidence(confidence)
+        X = np.asarray(X)
+
+        # Conformal quantile (Romano et al., 2019): the ceil((n + 1) * confidence)-th
+        # smallest score. When that rank exceeds n, no finite adjustment
+        # guarantees coverage, so the interval is unbounded. Do not subtract
+        # a tolerance: that can lower the rank below the requested coverage.
+        n = self._n_calib
+        k = int(np.ceil((n + 1) * confidence))
+        if k > n:
+            adjustment = np.inf
+        else:
+            adjustment = float(np.sort(self._scores)[k - 1])
+
+        lower = self._predict_quantile(self.lower_model, X) - adjustment
+        upper = self._predict_quantile(self.upper_model, X) + adjustment
+
+        return lower, upper
+
+    @staticmethod
+    def _predict_quantile(model, X):
+        values = np.asarray(model.predict(X), dtype=float)
+        if values.shape != (len(X),):
+            raise ValueError("Quantile models must predict one value per sample.")
+        if not np.all(np.isfinite(values)):
+            raise ValueError("Quantile model predictions must contain only finite values.")
+        return values

uxplain/conformal/crepes_classifier.py

@@ -0,0 +1,186 @@
+"""
+Conformal classification module.
+
+Wrapper around crepes.WrapClassifier for prediction sets.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from crepes import WrapClassifier
+import numpy as np
+
+from ._validation import check_confidence, check_fit_data
+
+ClassificationConformalMethod = Literal[
+    "standard",
+    "class_cond",
+    "mondrian",
+]
+
+
+class CrepesConformalClassifier:
+    """
+    Wrapper for conformal classification using crepes.
+
+    Parameters
+    ----------
+    model : object
+        Any sklearn-compatible classifier exposing
+        ``fit``, ``predict``, and ``predict_proba``.
+    method : ClassificationConformalMethod
+        Conformal classification method:
+
+        - ``"standard"``    : basic (marginal) conformal classifier
+        - ``"class_cond"``  : class-conditional Mondrian (per-class coverage)
+        - ``"mondrian"``    : Mondrian categorizer based on predicted class
+    random_state : int, optional
+        Seed for the tie-breaking draws of smoothed p-values. Ignored when
+        ``smoothing=False``.
+    smoothing : bool, default=False
+        Use randomized tie-breaking for prediction. Even with a fixed seed,
+        smoothed p-values can depend on row order and batch size, so built-in
+        explainers require ``smoothing=False``. Non-smoothed p-values are
+        deterministic for a fixed deterministic model and conservative under
+        the conformal assumptions; smoothing does not repair invalid sampling.
+
+    Notes
+    -----
+    Coverage requires calibration and future scores to be exchangeable after
+    training, within the selected groups for conditional methods. The fitted
+    model's classes must contain the full target label space. Unknown calibration
+    labels raise an error; future labels absent from ``classes_`` cannot be
+    covered. Do not select a split or tune the model on calibration outcomes.
+
+    Examples
+    --------
+    >>> from sklearn.ensemble import RandomForestClassifier
+    >>> cp = CrepesConformalClassifier(RandomForestClassifier(), method="class_cond")
+    >>> cp.fit(X_train, y_train, X_calib, y_calib)
+    >>> pred_set = cp.predict_set(X_test, confidence=0.9)   # (n, n_classes) bool
+    >>> p_values = cp.predict_p(X_test)                     # (n, n_classes)
+    """
+
+    def __init__(
+        self,
+        model,
+        method: ClassificationConformalMethod = "standard",
+        random_state: int | None = None,
+        smoothing: bool = False,
+    ):
+        if method not in ("standard", "class_cond", "mondrian"):
+            raise ValueError(f"Unknown conformal classification method '{method}'.")
+        self.model = model
+        self.method = method
+        self.random_state = random_state
+        self.smoothing = smoothing
+        self.wrapper = None
+        self.classes_ = None
+
+    def fit(
+        self,
+        X_train: np.ndarray,
+        y_train: np.ndarray,
+        X_calib: np.ndarray,
+        y_calib: np.ndarray,
+        **kwargs,
+    ) -> None:
+        """
+        Fit conformal classifier.
+
+        Steps:
+        1. Fit underlying model
+        2. Optionally fit Mondrian categorizer
+        3. Calibrate conformal classifier
+        """
+
+        self.wrapper = None
+        self.classes_ = None
+        X_train, y_train, X_calib, y_calib = check_fit_data(
+            X_train, y_train, X_calib, y_calib,
+        )
+
+        # Train
+        self.model.fit(X_train, y_train)
+        self.classes_ = np.asarray(self.model.classes_)
+        if not np.all(np.isin(y_calib, self.classes_)):
+            raise ValueError("y_calib contains classes absent from the fitted model.")
+
+        self.wrapper = WrapClassifier(self.model)
+
+        # Build calibration kwargs based on method
+        calibrate_kwargs = {}
+
+        if self.method == "class_cond":
+            calibrate_kwargs["class_cond"] = True
+        elif self.method == "mondrian":
+            calibrate_kwargs["mc"] = self.model.predict
+
+        # Calibrate
+        self.wrapper.calibrate(
+            X_calib,
+            y_calib,
+            **calibrate_kwargs,
+        )
+
+    def predict_set(
+        self,
+        X: np.ndarray,
+        confidence: float = 0.9,
+    ) -> np.ndarray:
+        """
+        Generate prediction sets.
+
+        Parameters
+        ----------
+        X : np.ndarray
+        confidence : float
+
+        Returns
+        -------
+        prediction_set : np.ndarray of shape (n_samples, n_classes), dtype=bool
+            ``True`` at position ``[i, k]`` means class ``k`` is included in
+            the prediction set for sample ``i``.
+        """
+
+        if self.wrapper is None:
+            raise RuntimeError("CrepesConformalClassifier not fitted.")
+
+        check_confidence(confidence)
+        X = np.asarray(X)
+        # labels=False keeps the binary-array output; since crepes 0.9.1
+        # the default (labels=True) returns a list of lists of labels.
+        return self.wrapper.predict_set(
+            X, confidence=confidence, smoothing=self.smoothing,
+            seed=self.random_state, labels=False,
+        ).astype(bool)
+
+    def predict_p(
+        self,
+        X: np.ndarray,
+    ) -> np.ndarray:
+        """
+        Compute conformal p-values for each class.
+
+        Returns
+        -------
+        p_values : np.ndarray of shape (n_samples, n_classes)
+        """
+
+        if self.wrapper is None:
+            raise RuntimeError("CrepesConformalClassifier not fitted.")
+
+        X = np.asarray(X)
+        return self.wrapper.predict_p(
+            X, smoothing=self.smoothing, seed=self.random_state,
+        )
+
+    def predict_proba(
+        self,
+        X: np.ndarray,
+    ) -> np.ndarray:
+        """Underlying model probabilities."""
+
+        return self.model.predict_proba(np.asarray(X))
+

uxplain/conformal/crepes_predictor.py

@@ -0,0 +1,180 @@
+"""
+Conformal prediction module.
+
+Wrapper around crepes.WrapRegressor
+for interval prediction.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from crepes import WrapRegressor
+from crepes.extras import (
+    DifficultyEstimator,
+    MondrianCategorizer,
+)
+import numpy as np
+
+from ._validation import check_confidence, check_fit_data
+
+ConformalMethod = Literal[
+    "standard",
+    "normalized",
+    "mondrian",
+    "normalized_mondrian",
+]
+
+
+class _DeterministicMondrianCategorizer(MondrianCategorizer):
+    """Fit and apply empirical bin thresholds without random tie jitter."""
+
+    def fit(self, X=None, f=None, de=None, no_bins=10):
+        self.f = f
+        self.de = de
+        scores = f(X) if f is not None else de.apply(X)
+        boundaries = np.unique(np.quantile(scores, np.linspace(0, 1, no_bins + 1)))
+        # Merge tied quantile boundaries. Constant scores form a single bin.
+        self.bin_thresholds = np.concatenate(([-np.inf], boundaries[1:-1], [np.inf]))
+        self.fitted = True
+        self.fitted_ = True
+        return self
+
+    def apply(self, X):
+        scores = self.f(X) if self.f is not None else self.de.apply(X)
+        # Equivalent to right-closed bins; tied scores always share a category.
+        return np.searchsorted(self.bin_thresholds[1:-1], scores, side="left")
+
+
+class CrepesConformalPredictor:
+    """
+    Wrapper for conformal regression using crepes.
+
+    Parameters
+    ----------
+    model : object
+        Any sklearn-compatible regressor.
+    method : ConformalMethod
+        Conformal prediction method to use:
+        - "standard": basic conformal prediction
+        - "normalized": uses a DifficultyEstimator for
+          adaptive interval widths
+        - "mondrian": uses a MondrianCategorizer for
+          group-conditional coverage
+        - "normalized_mondrian": combines both
+    """
+
+    def __init__(
+        self,
+        model,
+        method: ConformalMethod = "normalized",
+    ):
+        if method not in ("standard", "normalized", "mondrian", "normalized_mondrian"):
+            raise ValueError(f"Unknown conformal regression method '{method}'.")
+        self.model = model
+        self.method = method
+        self.wrapper = None
+        self.difficulty_estimator = None
+        self.mondrian_categorizer = None
+        self._calibration_bins = None
+
+    def fit(
+        self,
+        X_train: np.ndarray,
+        y_train: np.ndarray,
+        X_calib: np.ndarray,
+        y_calib: np.ndarray,
+        **kwargs,
+    ) -> None:
+        """
+        Fit conformal predictor.
+
+        Steps:
+        1. Fit model
+        2. Fit difficulty estimator and/or Mondrian categorizer
+        3. Calibrate conformal predictor
+        """
+
+        self.wrapper = None
+        self.difficulty_estimator = None
+        self.mondrian_categorizer = None
+        self._calibration_bins = None
+        X_train, y_train, X_calib, y_calib = check_fit_data(
+            X_train, y_train, X_calib, y_calib,
+        )
+
+        # Train
+        self.model.fit(
+            X_train,
+            y_train,
+        )
+
+        # Build calibration kwargs based on method
+        calibrate_kwargs = {}
+
+        if self.method in ("normalized", "normalized_mondrian"):
+            self.difficulty_estimator = DifficultyEstimator()
+            self.difficulty_estimator.fit(X_train, y=y_train)
+            calibrate_kwargs["de"] = self.difficulty_estimator
+
+        if self.method in ("mondrian", "normalized_mondrian"):
+            self.mondrian_categorizer = _DeterministicMondrianCategorizer()
+            mc_kwargs = {"de": self.difficulty_estimator} if self.method == "normalized_mondrian" else {"f": self.model.predict}
+            self.mondrian_categorizer.fit(X_train, **mc_kwargs)
+            calibrate_kwargs["mc"] = self.mondrian_categorizer
+            self._calibration_bins = np.unique(self.mondrian_categorizer.apply(X_calib))
+
+        self.wrapper = WrapRegressor(
+            self.model
+        )
+
+        # Calibrate
+        self.wrapper.calibrate(
+            X_calib,
+            y_calib,
+            **calibrate_kwargs,
+        )
+
+    def predict(
+        self,
+        X: np.ndarray,
+        confidence: float = 0.9,
+    ) -> tuple[np.ndarray, np.ndarray]:
+        """
+        Generate prediction intervals.
+
+        Parameters
+        ----------
+        X : np.ndarray
+
+        confidence : float
+
+        Returns
+        -------
+        lower : np.ndarray
+        upper : np.ndarray
+        """
+
+        if self.wrapper is None:
+            raise RuntimeError("CrepesConformalPredictor not fitted.")
+
+        check_confidence(confidence)
+        X = np.asarray(X)
+
+        intervals = self.wrapper.predict_int(
+            X,
+            confidence=confidence,
+        )
+
+        if self.mondrian_categorizer is not None:
+            bins = self.mondrian_categorizer.apply(X)
+            uncalibrated = ~np.isin(bins, self._calibration_bins)
+            # No finite group quantile exists without calibration observations.
+            # Some crepes versions otherwise leave these intervals at [0, 0].
+            intervals[uncalibrated, 0] = -np.inf
+            intervals[uncalibrated, 1] = np.inf
+
+        lower = intervals[:, 0]
+        upper = intervals[:, 1]
+
+        return lower, upper