deup 0.1.1__py3-none-any.whl

deup/__init__.py

@@ -0,0 +1,19 @@
+"""deup: Direct Epistemic Uncertainty Prediction for any scikit-learn-style model.
+
+DEUP (Lahlou et al., 2023, TMLR) estimates *epistemic* uncertainty by training a
+secondary "error predictor" on a base model's out-of-sample errors, then (optionally)
+subtracting an estimate of aleatoric noise. This package provides a maintained,
+scikit-learn-compatible implementation with first-class support for time-series and
+cross-sectional workflows, where correct out-of-fold error construction (no leakage)
+is the difference between a valid and an invalid uncertainty estimate.
+
+This is the library implementation; the DEUP *method* is due to
+Lahlou, Jain, Nekoei, Butoi, Bertin, Rector-Brooks, Korablyov, and Bengio (2023).
+"""
+
+from __future__ import annotations
+
+from deup.estimators import DEUPRegressor
+
+__all__ = ["DEUPRegressor", "__version__"]
+__version__ = "0.1.1"

deup/core/__init__.py

@@ -0,0 +1,32 @@
+"""Core protocols, typed result containers, and the grouped/panel data model.
+
+These are the framework-agnostic foundations every estimator in ``deup`` is built
+on. Nothing here imports a heavy backend (no torch, lightgbm, or pandas); the only
+runtime dependency is numpy.
+"""
+
+from __future__ import annotations
+
+from deup.core.grouping import Grouping
+from deup.core.losses import (
+    TargetTransform,
+    apply_error_transform,
+    get_loss,
+    inverse_error_transform,
+)
+from deup.core.oof import OOFErrorCollector
+from deup.core.protocols import Predictor, ProbabilisticPredictor
+from deup.core.types import OOFResult, UncertaintyResult
+
+__all__ = [
+    "Grouping",
+    "OOFErrorCollector",
+    "OOFResult",
+    "Predictor",
+    "ProbabilisticPredictor",
+    "TargetTransform",
+    "UncertaintyResult",
+    "apply_error_transform",
+    "get_loss",
+    "inverse_error_transform",
+]

deup/core/grouping.py

@@ -0,0 +1,104 @@
+"""The grouped / panel data model.
+
+Many DEUP use cases are not i.i.d. row collections: a cross-sectional ranker scores
+many assets *per date*, where the loss (rank loss) and any rank-geometry
+residualization are defined *within* each date's cross-section. :class:`Grouping`
+makes that ``group_by`` concept first-class, while still handling the i.i.d. case
+(``group_by=None``) as a single trivial group.
+
+Pure numpy — no pandas dependency in the core.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+
+
+def _average_rank(values: npt.NDArray[Any]) -> npt.NDArray[Any]:
+    """Return 1-based ranks with ties resolved by averaging (scipy 'average').
+
+    Implemented from unique values + counts, so it is independent of input order
+    and matches ``pandas.Series.rank(method="average")``.
+    """
+    _, inverse, counts = np.unique(values, return_inverse=True, return_counts=True)
+    inverse = np.ravel(inverse)
+    end = np.cumsum(counts).astype(float)
+    start = end - counts + 1.0
+    average = (start + end) / 2.0
+    result: npt.NDArray[Any] = average[inverse]
+    return result
+
+
+@dataclass(frozen=True)
+class Grouping:
+    """Maps each row to a group and supports within-group operations.
+
+    Attributes
+    ----------
+    codes:
+        Integer group code per row, in ``[0, n_groups)``.
+    labels:
+        The unique group labels, indexed by code.
+    """
+
+    codes: npt.NDArray[Any]
+    labels: npt.NDArray[Any]
+
+    @classmethod
+    def from_labels(cls, group_labels: npt.ArrayLike | None, n: int) -> Grouping:
+        """Build a grouping from per-row labels.
+
+        Parameters
+        ----------
+        group_labels:
+            Per-row group labels (e.g. dates). If ``None``, all ``n`` rows form a
+            single trivial group (the i.i.d. case).
+        n:
+            Number of rows (used to size the trivial group and validate lengths).
+        """
+        if group_labels is None:
+            return cls(
+                codes=np.zeros(n, dtype=np.intp),
+                labels=np.zeros(1, dtype=np.intp),
+            )
+        arr = np.asarray(group_labels)
+        if arr.shape[0] != n:
+            raise ValueError(f"group_labels length {arr.shape[0]} != n {n}")
+        labels, codes = np.unique(arr, return_inverse=True)
+        return cls(codes=np.ravel(codes).astype(np.intp), labels=labels)
+
+    @property
+    def n_groups(self) -> int:
+        """Number of distinct groups."""
+        return int(self.labels.shape[0])
+
+    @property
+    def is_trivial(self) -> bool:
+        """True when there is a single group (the i.i.d. case)."""
+        return self.n_groups == 1
+
+    def indices(self) -> list[npt.NDArray[Any]]:
+        """Row indices for each group, ordered by group code."""
+        return [np.flatnonzero(self.codes == code) for code in range(self.n_groups)]
+
+    def rank_within(self, values: npt.ArrayLike, pct: bool = True) -> npt.NDArray[Any]:
+        """Rank ``values`` within each group.
+
+        Ties are averaged. With ``pct=True`` (default) ranks are divided by the
+        group size, matching ``pandas.Series.groupby(...).rank(pct=True)`` — the
+        convention used for cross-sectional rank features and rank losses.
+        """
+        vals = np.asarray(values, dtype=float)
+        if vals.shape[0] != self.codes.shape[0]:
+            raise ValueError(f"values length {vals.shape[0]} != n_rows {self.codes.shape[0]}")
+        out = np.empty(vals.shape[0], dtype=float)
+        for idx in self.indices():
+            ranks = _average_rank(vals[idx])
+            if pct:
+                ranks = ranks / ranks.shape[0]
+            out[idx] = ranks
+        return out

deup/core/losses.py

@@ -0,0 +1,213 @@
+"""Error-target losses for DEUP.
+
+In DEUP the *error target* for a row is the base model's pointwise loss
+``l(y, f(x))`` (Lahlou et al., 2023, Eq. 9 / Alg. 1). The secondary predictor ``g``
+then regresses these targets. This module provides the common choices behind a
+single ``get_loss`` factory, plus a ``callable`` escape hatch for custom losses.
+
+Each loss has the signature ``loss(y_true, y_pred, groups=None) -> ndarray`` and
+returns one non-negative error per row. ``groups`` is only used by group-aware losses
+such as :func:`rank_loss`.
+
+**Task pairing**
+
+- regression: ``squared``, ``absolute``, ``pinball``
+- classification: ``logloss``, ``brier``
+- ranking: ``rank`` (requires ``groups``)
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, Literal
+
+import numpy as np
+import numpy.typing as npt
+
+from deup.core.grouping import Grouping
+
+LossFn = Callable[..., npt.NDArray[Any]]
+TargetTransform = Literal["none", "log", "asinh"]
+
+
+def squared_error(
+    y_true: npt.ArrayLike, y_pred: npt.ArrayLike, groups: npt.ArrayLike | None = None
+) -> npt.NDArray[Any]:
+    """Squared residual ``(y - f(x))**2`` (regression)."""
+    yt = np.asarray(y_true, dtype=float)
+    yp = np.asarray(y_pred, dtype=float)
+    out: npt.NDArray[Any] = (yt - yp) ** 2
+    return out
+
+
+def absolute_error(
+    y_true: npt.ArrayLike, y_pred: npt.ArrayLike, groups: npt.ArrayLike | None = None
+) -> npt.NDArray[Any]:
+    """Absolute residual ``|y - f(x)|`` (regression)."""
+    yt = np.asarray(y_true, dtype=float)
+    yp = np.asarray(y_pred, dtype=float)
+    out: npt.NDArray[Any] = np.abs(yt - yp)
+    return out
+
+
+def log_loss(
+    y_true: npt.ArrayLike, y_pred: npt.ArrayLike, groups: npt.ArrayLike | None = None
+) -> npt.NDArray[Any]:
+    """Pointwise cross-entropy (classification).
+
+    ``y_pred`` may be a 1-D vector of positive-class probabilities (binary) or a 2-D
+    array of class probabilities (multiclass); ``y_true`` holds class indices
+    (or 0/1 for binary).
+    """
+    yt = np.asarray(y_true)
+    yp = np.asarray(y_pred, dtype=float)
+    eps = 1e-12
+    if yp.ndim == 2:
+        probs = np.clip(yp, eps, 1.0)
+        true_idx = yt.astype(int)
+        chosen = probs[np.arange(probs.shape[0]), true_idx]
+        multiclass: npt.NDArray[Any] = -np.log(chosen)
+        return multiclass
+    p = np.clip(yp, eps, 1.0 - eps)
+    yt_f = yt.astype(float)
+    binary: npt.NDArray[Any] = -(yt_f * np.log(p) + (1.0 - yt_f) * np.log(1.0 - p))
+    return binary
+
+
+def brier_loss(
+    y_true: npt.ArrayLike, y_pred: npt.ArrayLike, groups: npt.ArrayLike | None = None
+) -> npt.NDArray[Any]:
+    """Brier score (classification calibration loss).
+
+    Binary: ``(y - p)²`` with ``y ∈ {0,1}``. Multiclass: ``Σ_k (𝟙[y=k] - p_k)²``.
+    """
+    yt = np.asarray(y_true)
+    yp = np.asarray(y_pred, dtype=float)
+    if yp.ndim == 2:
+        n, k = yp.shape
+        one_hot = np.zeros((n, k), dtype=float)
+        one_hot[np.arange(n), yt.astype(int)] = 1.0
+        out: npt.NDArray[Any] = np.sum((one_hot - yp) ** 2, axis=1)
+        return out
+    yt_f = yt.astype(float)
+    out = (yt_f - yp) ** 2
+    return out
+
+
+def pinball_loss(
+    y_true: npt.ArrayLike,
+    y_pred: npt.ArrayLike,
+    groups: npt.ArrayLike | None = None,
+    *,
+    q: float = 0.5,
+) -> npt.NDArray[Any]:
+    """Pinball / quantile loss for quantile regression (``q ∈ (0, 1)``).
+
+    ``y_pred`` must be the predicted ``q``-quantile of ``y``.
+    """
+    if not 0.0 < q < 1.0:
+        raise ValueError(f"pinball quantile q must be in (0, 1), got {q}")
+    yt = np.asarray(y_true, dtype=float)
+    yp = np.asarray(y_pred, dtype=float)
+    diff = yt - yp
+    out: npt.NDArray[Any] = np.maximum(q * diff, (q - 1.0) * diff)
+    return out
+
+
+def rank_loss(
+    y_true: npt.ArrayLike, y_pred: npt.ArrayLike, groups: npt.ArrayLike | None = None
+) -> npt.NDArray[Any]:
+    """Per-group absolute rank displacement (cross-sectional ranking).
+
+    For each group (e.g. a date), ranks ``y_true`` and ``y_pred`` to percentiles and
+    returns ``|rank_pct(y_true) - rank_pct(y_pred)|``. Requires a group-coherent
+    splitter so that each group's full cross-section is scored together.
+    """
+    yt = np.asarray(y_true, dtype=float)
+    grouping = Grouping.from_labels(groups, n=yt.shape[0])
+    rank_true = grouping.rank_within(yt, pct=True)
+    rank_pred = grouping.rank_within(y_pred, pct=True)
+    out: npt.NDArray[Any] = np.abs(rank_true - rank_pred)
+    return out
+
+
+def apply_error_transform(
+    errors: npt.ArrayLike,
+    method: TargetTransform = "log",
+    *,
+    eps: float = 1e-6,
+) -> npt.NDArray[Any]:
+    """Stabilize heavy-tailed error targets before training ``g``.
+
+    - ``log``: ``log(error + eps)`` (default; used by :class:`~deup.estimators.DEUPRegressor`)
+    - ``asinh``: ``asinh(error / eps)`` — robust alternative for very heavy tails
+    - ``none``: identity
+    """
+    err = np.asarray(errors, dtype=float)
+    if method == "none":
+        return err
+    if method == "log":
+        out: npt.NDArray[Any] = np.log(err + eps)
+        return out
+    if method == "asinh":
+        out = np.arcsinh(err / eps)
+        return out
+    raise ValueError(f"Unknown target transform {method!r}. Choose from log, asinh, none.")
+
+
+def inverse_error_transform(
+    values: npt.ArrayLike,
+    method: TargetTransform = "log",
+    *,
+    eps: float = 1e-6,
+) -> npt.NDArray[Any]:
+    """Map ``g``'s prediction back to the error scale."""
+    vals = np.asarray(values, dtype=float)
+    if method == "none":
+        return vals
+    if method == "log":
+        out: npt.NDArray[Any] = np.exp(vals) - eps
+        return out
+    if method == "asinh":
+        out = np.sinh(vals) * eps
+        return out
+    raise ValueError(f"Unknown target transform {method!r}. Choose from log, asinh, none.")
+
+
+_REGISTRY: dict[str, LossFn] = {
+    "squared": squared_error,
+    "absolute": absolute_error,
+    "logloss": log_loss,
+    "brier": brier_loss,
+    "rank": rank_loss,
+}
+
+
+def get_loss(loss: str | LossFn, **kwargs: Any) -> LossFn:
+    """Resolve ``loss`` (a registry name or a callable) to a loss function.
+
+    For ``pinball``, pass ``q`` (default 0.5) or use the string ``"pinball:0.9"``.
+    """
+    if callable(loss):
+        return loss
+    if loss.startswith("pinball"):
+        q = float(kwargs.get("q", 0.5))
+        if ":" in loss:
+            q = float(loss.split(":", 1)[1])
+        q_val = q
+
+        def _pinball(
+            y_true: npt.ArrayLike,
+            y_pred: npt.ArrayLike,
+            groups: npt.ArrayLike | None = None,
+        ) -> npt.NDArray[Any]:
+            return pinball_loss(y_true, y_pred, groups, q=q_val)
+
+        return _pinball
+    try:
+        return _REGISTRY[loss]
+    except KeyError:
+        raise ValueError(
+            f"Unknown loss {loss!r}. Choose from {sorted(_REGISTRY)} "
+            f"(or pinball[:q]) or pass a callable."
+        ) from None

deup/core/oof.py

@@ -0,0 +1,183 @@
+"""Out-of-fold error collection -- the correctness heart of DEUP.
+
+This implements the paper's Algorithm 2 (K-fold pre-fill of the error dataset): for
+each fold, fit a *fresh* clone of the base model on the training rows and predict the
+held-out rows, so every row receives an **out-of-sample** prediction. The pointwise
+loss of those predictions is the training target for the secondary error predictor.
+
+Training the error predictor on in-sample errors instead (e.g. by predicting rows the
+base model was trained on) is the canonical DEUP failure mode -- it underestimates
+epistemic uncertainty (Lahlou et al., 2023, Sec. 3.2). The leakage test in the test
+suite is designed to fail if this collector ever regresses to in-sample behavior.
+
+Refit assumption
+----------------
+By default the collector also refits the base model ``f`` on *all* training data and
+exposes it as ``OOFResult.estimator`` for deployment. The error predictor ``g`` is
+therefore trained on the out-of-sample errors of fold models ``f_{-k}`` (each fit on
+a strict subset of the data), but deployed alongside the full-data ``f``. This is the
+standard DEUP / stacking assumption: ``g`` learns the error of a *slightly smaller*
+model than the one it is paired with at inference. In practice fold and full models
+are close for reasonable fold counts; for time-series the fold models are genuinely
+smaller (expanding window), which is the realistic operating regime and is handled
+explicitly by walk-forward splitters. Set ``refit_on_all=False`` to disable.
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+from sklearn.base import clone
+
+from deup.core.losses import LossFn, get_loss
+from deup.core.types import OOFResult
+
+
+def _safe_index(X: Any, idx: npt.NDArray[Any]) -> Any:
+    """Row-index ``X`` whether it is a numpy array or a pandas object."""
+    if hasattr(X, "iloc"):
+        return X.iloc[idx]
+    return np.asarray(X)[idx]
+
+
+class OOFErrorCollector:
+    """Collect a base model's out-of-fold predictions and pointwise errors.
+
+    Parameters
+    ----------
+    estimator:
+        The base model ``f`` (any scikit-learn-style ``fit``/``predict`` object).
+        It is cloned per fold; the passed instance is never fitted in place.
+    cv:
+        A splitter exposing ``split(X, y, groups)`` (e.g. ``KFold``,
+        ``TimeSeriesSplit``, or :class:`deup.splitters.PurgedWalkForward`). For
+        time-ordered data use a non-shuffling splitter; the collector itself never
+        shuffles.
+    loss:
+        Error-target loss: a registry name (``"squared"``, ``"absolute"``,
+        ``"logloss"``, ``"brier"``, ``"pinball"``, ``"rank"``) or a callable
+        ``loss(y_true, y_pred, groups)``.
+    proba:
+        If ``True``, use ``predict_proba`` instead of ``predict`` -- required for
+        classification log-loss / Brier targets. Binary probabilities are stored as
+        the positive-class column; multiclass probabilities are stored as a 2-D
+        array and passed through to the loss.
+    refit_on_all:
+        If ``True`` (default), also refit a clone of the base model on all data and
+        expose it as ``OOFResult.estimator``. See the module docstring for the
+        "g trained on errors of a slightly smaller f" assumption this entails.
+
+    Notes
+    -----
+    Rows never assigned to a test fold (e.g. the earliest rows under walk-forward)
+    are excluded from the returned :class:`~deup.core.types.OOFResult`. If a row is
+    assigned to more than one test fold (e.g. repeated CV), a warning is raised and
+    the last fold's prediction is kept, since averaging would break the
+    one-error-per-row contract that ``g`` is trained on.
+    """
+
+    def __init__(
+        self,
+        estimator: Any,
+        cv: Any,
+        loss: str | LossFn = "squared",
+        *,
+        proba: bool = False,
+        refit_on_all: bool = True,
+    ) -> None:
+        self.estimator = estimator
+        self.cv = cv
+        self.loss = loss
+        self.proba = proba
+        self.refit_on_all = refit_on_all
+
+    def _predict_fold(self, model: Any, X_test: Any) -> npt.NDArray[Any]:
+        """Return fold predictions: 1-D point preds, pos-class probs, or 2-D probs."""
+        if not self.proba:
+            return np.asarray(model.predict(X_test), dtype=float)
+        proba = np.asarray(model.predict_proba(X_test), dtype=float)
+        if proba.ndim == 2 and proba.shape[1] == 2:
+            return proba[:, 1]
+        return proba
+
+    def fit_collect(
+        self, X: Any, y: npt.ArrayLike, groups: npt.ArrayLike | None = None
+    ) -> OOFResult:
+        """Run the out-of-fold loop and return the collected errors.
+
+        Parameters
+        ----------
+        X, y:
+            Training features and targets.
+        groups:
+            Optional per-row group labels (e.g. dates). Passed to the splitter and to
+            group-aware losses such as ``"rank"``.
+        """
+        y_arr = np.asarray(y)
+        n = y_arr.shape[0]
+        groups_arr = None if groups is None else np.asarray(groups)
+        if groups_arr is not None and groups_arr.shape[0] != n:
+            raise ValueError(f"groups length {groups_arr.shape[0]} != n_rows {n}")
+
+        # Accumulate per-fold predictions so we can size the output array correctly
+        # for either point predictions (1-D) or multiclass probabilities (2-D).
+        fold_results: list[tuple[npt.NDArray[Any], npt.NDArray[Any]]] = []
+        pred_width: int | None = None  # None => 1-D output; int => 2-D output
+        for fold, (train_idx, test_idx) in enumerate(self.cv.split(X, y_arr, groups_arr)):
+            if len(test_idx) == 0:
+                continue  # degenerate fold: nothing held out
+            model = clone(self.estimator)
+            model.fit(_safe_index(X, train_idx), y_arr[train_idx])
+            pred = self._predict_fold(model, _safe_index(X, test_idx))
+            if pred.ndim == 2:
+                pred_width = pred.shape[1]
+            fold_results.append((np.asarray(test_idx), pred))
+            del fold  # fold index not needed beyond enumerate
+
+        if not fold_results:
+            raise ValueError("No out-of-fold predictions were produced by the splitter.")
+
+        if pred_width is None:
+            oof_pred: npt.NDArray[Any] = np.full(n, np.nan, dtype=float)
+        else:
+            oof_pred = np.full((n, pred_width), np.nan, dtype=float)
+        fold_ids = np.full(n, -1, dtype=np.intp)
+        hit_count = np.zeros(n, dtype=np.intp)
+
+        for fold, (test_idx, pred) in enumerate(fold_results):
+            oof_pred[test_idx] = pred
+            fold_ids[test_idx] = fold
+            hit_count[test_idx] += 1
+
+        if (hit_count > 1).any():
+            n_overlap = int((hit_count > 1).sum())
+            warnings.warn(
+                f"{n_overlap} row(s) were assigned to multiple test folds; "
+                "keeping the last prediction. Use a partitioning splitter for "
+                "honest one-error-per-row out-of-fold targets.",
+                stacklevel=2,
+            )
+
+        mask = fold_ids >= 0
+        loss_fn = get_loss(self.loss)
+        g_groups = None if groups_arr is None else groups_arr[mask]
+        errors = np.asarray(loss_fn(y_arr[mask], oof_pred[mask], g_groups), dtype=float)
+        if errors.shape[0] != int(mask.sum()):
+            raise ValueError(f"loss returned {errors.shape[0]} values for {int(mask.sum())} rows")
+
+        estimator_ = None
+        if self.refit_on_all:
+            estimator_ = clone(self.estimator)
+            estimator_.fit(X, y_arr)
+
+        return OOFResult(
+            predictions=oof_pred[mask],
+            errors=errors,
+            fold_ids=fold_ids[mask],
+            group_ids=g_groups,
+            indices=np.flatnonzero(mask),
+            estimator=estimator_,
+        )

deup/core/protocols.py

@@ -0,0 +1,41 @@
+"""Structural typing for the models ``deup`` wraps.
+
+DEUP is model-agnostic: it orchestrates a *base* predictor and a *secondary* error
+predictor that both follow the scikit-learn ``fit`` / ``predict`` convention. We
+express that requirement structurally (via :class:`typing.Protocol`) rather than by
+inheritance, so any duck-typed estimator — scikit-learn, LightGBM, XGBoost, a thin
+wrapper around a neural net — qualifies without importing scikit-learn here.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+import numpy.typing as npt
+
+
+@runtime_checkable
+class Predictor(Protocol):
+    """A minimal scikit-learn-style point predictor.
+
+    Any object exposing ``fit(X, y)`` and ``predict(X)`` satisfies this protocol.
+    The return type of ``fit`` is intentionally ``Any`` (scikit-learn returns
+    ``self``); only the *presence* of the methods is required.
+    """
+
+    def fit(self, X: npt.ArrayLike, y: npt.ArrayLike) -> Any:
+        """Fit the predictor on features ``X`` and targets ``y``."""
+        ...
+
+    def predict(self, X: npt.ArrayLike) -> npt.NDArray[Any]:
+        """Return point predictions for ``X``."""
+        ...
+
+
+@runtime_checkable
+class ProbabilisticPredictor(Predictor, Protocol):
+    """A classifier that additionally exposes ``predict_proba``."""
+
+    def predict_proba(self, X: npt.ArrayLike) -> npt.NDArray[Any]:
+        """Return class-probability estimates for ``X``."""
+        ...

deup/core/types.py

@@ -0,0 +1,124 @@
+"""Typed, immutable result containers passed between DEUP's layers.
+
+These dataclasses are the contract between the out-of-fold collector, the error
+estimator, and the calibration layer. They are frozen (their fields cannot be
+reassigned) and validate array-length consistency on construction, so a malformed
+result fails loudly at the boundary rather than silently downstream.
+
+``eq=False`` is deliberate: the fields are numpy arrays, whose element-wise ``==``
+does not yield a single boolean, so an auto-generated ``__eq__`` would be a footgun.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+
+
+@dataclass(frozen=True, eq=False)
+class OOFResult:
+    """Out-of-fold artifacts produced when collecting a base model's errors.
+
+    Attributes
+    ----------
+    predictions:
+        Out-of-fold predictions of the base model ``f``, one per row.
+    errors:
+        Per-row error targets that the secondary predictor ``g`` will learn from
+        (e.g. squared residuals or per-group rank losses).
+    fold_ids:
+        The fold in which each row was held out. Useful for diagnostics and for
+        walk-forward reporting.
+    group_ids:
+        Optional per-row group label (e.g. a date for cross-sectional ranking).
+        ``None`` for i.i.d. data.
+    indices:
+        Optional positions of these rows in the original input ``X`` (the rows that
+        received an out-of-fold prediction). ``None`` if not tracked.
+    estimator:
+        Optionally, the base model refit on all data for deployment. ``None`` if
+        the caller chose not to refit.
+    """
+
+    predictions: npt.NDArray[Any]
+    errors: npt.NDArray[Any]
+    fold_ids: npt.NDArray[Any]
+    group_ids: npt.NDArray[Any] | None = None
+    indices: npt.NDArray[Any] | None = None
+    estimator: Any = field(default=None)
+
+    def __post_init__(self) -> None:
+        preds = np.asarray(self.predictions)
+        errs = np.asarray(self.errors)
+        folds = np.asarray(self.fold_ids)
+        object.__setattr__(self, "predictions", preds)
+        object.__setattr__(self, "errors", errs)
+        object.__setattr__(self, "fold_ids", folds)
+
+        n = preds.shape[0]
+        if errs.shape[0] != n or folds.shape[0] != n:
+            raise ValueError(
+                "OOFResult arrays must share length: "
+                f"predictions={preds.shape[0]}, errors={errs.shape[0]}, "
+                f"fold_ids={folds.shape[0]}"
+            )
+        for name in ("group_ids", "indices"):
+            value = getattr(self, name)
+            if value is not None:
+                arr = np.asarray(value)
+                object.__setattr__(self, name, arr)
+                if arr.shape[0] != n:
+                    raise ValueError(f"{name} length {arr.shape[0]} != n_rows {n}")
+
+    @property
+    def n(self) -> int:
+        """Number of rows."""
+        return int(self.predictions.shape[0])
+
+
+@dataclass(frozen=True, eq=False)
+class UncertaintyResult:
+    """A prediction together with its uncertainty decomposition.
+
+    Attributes
+    ----------
+    prediction:
+        Point prediction of the base model.
+    epistemic:
+        Estimated epistemic uncertainty ``g(x)`` (optionally net of aleatoric).
+    aleatoric:
+        Optional estimated aleatoric (irreducible) uncertainty ``a(x)``.
+    lower, upper:
+        Optional calibrated prediction-interval bounds.
+    """
+
+    prediction: npt.NDArray[Any]
+    epistemic: npt.NDArray[Any]
+    aleatoric: npt.NDArray[Any] | None = None
+    lower: npt.NDArray[Any] | None = None
+    upper: npt.NDArray[Any] | None = None
+
+    def __post_init__(self) -> None:
+        pred = np.asarray(self.prediction)
+        epi = np.asarray(self.epistemic)
+        object.__setattr__(self, "prediction", pred)
+        object.__setattr__(self, "epistemic", epi)
+
+        n = pred.shape[0]
+        if epi.shape[0] != n:
+            raise ValueError(f"epistemic length {epi.shape[0]} != prediction length {n}")
+        for name in ("aleatoric", "lower", "upper"):
+            value = getattr(self, name)
+            if value is not None:
+                arr = np.asarray(value)
+                object.__setattr__(self, name, arr)
+                if arr.shape[0] != n:
+                    raise ValueError(f"{name} length {arr.shape[0]} != prediction length {n}")
+
+    @property
+    def n(self) -> int:
+        """Number of rows."""
+        return int(self.prediction.shape[0])

deup/estimators.py

@@ -0,0 +1,140 @@
+"""User-facing DEUP estimators.
+
+``DEUPRegressor`` is the ergonomic, scikit-learn-compatible entry point: wrap any
+regressor, fit, and get a point prediction plus an epistemic-uncertainty estimate.
+
+    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)
+
+Under the hood it composes the leakage-correct :class:`~deup.core.oof.OOFErrorCollector`
+(out-of-sample errors of the base model) with a secondary "error predictor" ``g`` that
+regresses those errors -- this is DEUP (Lahlou et al., 2023). In this minimal v0.1
+the aleatoric term is taken as zero, so the reported epistemic uncertainty is the
+predicted out-of-sample error ``g(x)`` (the paper's conservative proxy); the
+aleatoric decomposition and density/variance features are added in later versions.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+from sklearn.base import BaseEstimator, MetaEstimatorMixin, RegressorMixin, clone
+from sklearn.ensemble import HistGradientBoostingRegressor
+from sklearn.model_selection import KFold
+from sklearn.utils.validation import check_is_fitted
+
+from deup.core.losses import TargetTransform, apply_error_transform, inverse_error_transform
+from deup.core.oof import OOFErrorCollector, _safe_index
+
+
+class DEUPRegressor(RegressorMixin, MetaEstimatorMixin, BaseEstimator):
+    """Direct Epistemic Uncertainty Prediction for regression.
+
+    Parameters
+    ----------
+    base_model:
+        The regressor whose uncertainty we estimate. Defaults to
+        :class:`~sklearn.ensemble.HistGradientBoostingRegressor`.
+    error_model:
+        The secondary error predictor ``g``. Defaults to
+        :class:`~sklearn.ensemble.HistGradientBoostingRegressor` (no extra deps).
+    cv:
+        An int (number of ``KFold`` folds) or any splitter exposing ``split``
+        (e.g. :class:`deup.splitters.PurgedWalkForward` for time series).
+    loss:
+        Error-target loss passed to the collector (``"squared"`` by default).
+    target_transform:
+        Stabilization for ``g``'s regression target: ``"log"`` (default),
+        ``"asinh"``, or ``"none"``.
+    log_target:
+        Deprecated alias for ``target_transform="log"``. If ``False``, sets
+        ``target_transform="none"`` unless ``target_transform`` is explicitly given.
+    error_eps:
+        Stabilizer for ``log`` / ``asinh`` transforms.
+    random_state:
+        Seed used when ``cv`` is an int (a shuffled ``KFold``).
+
+    Attributes
+    ----------
+    base_model_ :
+        The base model refit on all training data (used for ``predict``).
+    error_model_ :
+        The fitted error predictor ``g``.
+    oof_ :
+        The :class:`~deup.core.types.OOFResult` used to train ``g``.
+    """
+
+    def __init__(
+        self,
+        base_model: Any = None,
+        error_model: Any = None,
+        cv: Any = 5,
+        loss: Any = "squared",
+        *,
+        target_transform: TargetTransform | None = None,
+        log_target: bool = True,
+        error_eps: float = 1e-6,
+        random_state: int | None = None,
+    ) -> None:
+        self.base_model = base_model
+        self.error_model = error_model
+        self.cv = cv
+        self.loss = loss
+        if target_transform is not None:
+            self.target_transform: TargetTransform = target_transform
+        else:
+            self.target_transform = "log" if log_target else "none"
+        self.log_target = log_target
+        self.error_eps = error_eps
+        self.random_state = random_state
+
+    def _resolve_cv(self) -> Any:
+        if isinstance(self.cv, int):
+            return KFold(n_splits=self.cv, shuffle=True, random_state=self.random_state)
+        return self.cv
+
+    def fit(self, X: Any, y: npt.ArrayLike, groups: npt.ArrayLike | None = None) -> DEUPRegressor:
+        """Fit the base model (out-of-fold) and the error predictor ``g``."""
+        base = self.base_model if self.base_model is not None else HistGradientBoostingRegressor()
+        err = self.error_model if self.error_model is not None else HistGradientBoostingRegressor()
+
+        collector = OOFErrorCollector(
+            base, cv=self._resolve_cv(), loss=self.loss, refit_on_all=True
+        )
+        oof = collector.fit_collect(X, y, groups=groups)
+
+        assert oof.indices is not None  # collector always records indices
+        g_X = _safe_index(X, oof.indices)
+        target = apply_error_transform(oof.errors, method=self.target_transform, eps=self.error_eps)
+
+        self.error_model_ = clone(err)
+        self.error_model_.fit(g_X, target)
+        self.base_model_ = oof.estimator
+        self.oof_ = oof
+        if hasattr(X, "shape"):
+            self.n_features_in_ = int(X.shape[1])
+        return self
+
+    def predict(
+        self, X: Any, return_uncertainty: bool = False
+    ) -> npt.NDArray[Any] | tuple[npt.NDArray[Any], npt.NDArray[Any]]:
+        """Predict, optionally returning ``(prediction, epistemic_uncertainty)``."""
+        check_is_fitted(self, "base_model_")
+        pred = np.asarray(self.base_model_.predict(X), dtype=float)
+        if not return_uncertainty:
+            return pred
+        return pred, self.predict_epistemic(X)
+
+    def predict_epistemic(self, X: Any) -> npt.NDArray[Any]:
+        """Return the estimated epistemic uncertainty ``g(x)`` (>= 0)."""
+        check_is_fitted(self, "error_model_")
+        raw = np.asarray(self.error_model_.predict(X), dtype=float)
+        unc = inverse_error_transform(raw, method=self.target_transform, eps=self.error_eps)
+        clipped: npt.NDArray[Any] = np.clip(unc, 0.0, None)
+        return clipped

deup/splitters.py

@@ -0,0 +1,117 @@
+"""Cross-validation splitters for collecting out-of-sample errors.
+
+DEUP's error predictor must be trained on *out-of-sample* errors of the base model
+(Lahlou et al., 2023, Algorithms 1-2). The splitter is therefore the leakage-control
+knob: choose ``KFold`` for i.i.d. data, ``TimeSeriesSplit`` for ordered data, and
+:class:`PurgedWalkForward` for time-series / cross-sectional data where an embargo is
+needed to prevent look-ahead between train and test.
+
+``KFold`` and ``TimeSeriesSplit`` are re-exported from scikit-learn so users have a
+single import surface.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+from sklearn.model_selection import KFold, TimeSeriesSplit
+
+__all__ = ["KFold", "PurgedWalkForward", "TimeSeriesSplit"]
+
+
+def _n_rows(X: Any) -> int:
+    if hasattr(X, "shape"):
+        return int(X.shape[0])
+    return len(X)
+
+
+class PurgedWalkForward:
+    """Expanding-window walk-forward splitter with an embargo (purge).
+
+    Time is measured in *units*. If ``groups`` is passed to :meth:`split`, each
+    unique group value (e.g. a date) is one time unit and the whole cross-section
+    of a unit always stays together in the same fold — which is required for
+    cross-sectional rank losses. If ``groups`` is ``None``, each row is its own unit.
+
+    For each of ``n_splits`` folds, the test block is a contiguous range of the most
+    recent units; the training set is all units strictly before it, minus an
+    ``embargo`` of units immediately preceding the test block (the purge). This
+    prevents the base model from being trained on data adjacent to (and potentially
+    leaking into) the evaluation block.
+
+    Parameters
+    ----------
+    n_splits:
+        Number of walk-forward test folds.
+    embargo:
+        Number of time units to drop between the train set and each test block.
+    min_train_size:
+        Minimum number of training units required to emit a fold; smaller folds are
+        skipped.
+    max_train_size:
+        If set, training uses at most this many of the most recent units (rolling
+        window). Otherwise the window expands from the start.
+    """
+
+    def __init__(
+        self,
+        n_splits: int = 5,
+        embargo: int = 0,
+        min_train_size: int = 1,
+        max_train_size: int | None = None,
+    ) -> None:
+        if n_splits < 1:
+            raise ValueError("n_splits must be >= 1")
+        if embargo < 0:
+            raise ValueError("embargo must be >= 0")
+        if min_train_size < 1:
+            raise ValueError("min_train_size must be >= 1")
+        self.n_splits = n_splits
+        self.embargo = embargo
+        self.min_train_size = min_train_size
+        self.max_train_size = max_train_size
+
+    def get_n_splits(self, X: Any = None, y: Any = None, groups: Any = None) -> int:
+        return self.n_splits
+
+    def split(
+        self, X: Any, y: Any = None, groups: npt.ArrayLike | None = None
+    ) -> Iterator[tuple[npt.NDArray[Any], npt.NDArray[Any]]]:
+        """Yield ``(train_idx, test_idx)`` row-index arrays for each fold."""
+        n = _n_rows(X)
+        if groups is None:
+            row_units = np.arange(n)
+            n_units = n
+        else:
+            groups_arr = np.asarray(groups)
+            if groups_arr.shape[0] != n:
+                raise ValueError(f"groups length {groups_arr.shape[0]} != n_rows {n}")
+            _, row_units = np.unique(groups_arr, return_inverse=True)
+            row_units = np.ravel(row_units)
+            n_units = int(row_units.max()) + 1 if n > 0 else 0
+
+        test_size = n_units // (self.n_splits + 1)
+        if test_size < 1:
+            raise ValueError(f"Not enough time units ({n_units}) for n_splits={self.n_splits}")
+
+        indices = np.arange(n)
+        for i in range(self.n_splits):
+            test_start = n_units - (self.n_splits - i) * test_size
+            test_end = test_start + test_size
+            train_end = test_start - self.embargo
+            if train_end < self.min_train_size:
+                continue
+            train_start = 0
+            if self.max_train_size is not None:
+                train_start = max(0, train_end - self.max_train_size)
+
+            train_mask = (row_units >= train_start) & (row_units < train_end)
+            test_mask = (row_units >= test_start) & (row_units < test_end)
+            train_idx = indices[train_mask]
+            test_idx = indices[test_mask]
+            if train_idx.shape[0] == 0 or test_idx.shape[0] == 0:
+                continue
+            yield train_idx, test_idx

deup-0.1.1.dist-info/METADATA

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

deup-0.1.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+deup/__init__.py,sha256=mJsLpzdlIfMHkyyLb9-IxpxMcy5wbtOJzJJWpTXwDEs,867
+deup/estimators.py,sha256=R-xcC_9a6yXWSjz4UhHvWhO9fiOtbf3jQdSIRDIcQQQ,5753
+deup/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+deup/splitters.py,sha256=szyzCbc0tDd50NwzQRjfiPgvNAWxtxleSoxK59VGgIA,4599
+deup/core/__init__.py,sha256=a-G0rq_pZClZEqfHi4GHgMrEXYpKxQhwbRrvwLS6lbI,889
+deup/core/grouping.py,sha256=eUNvNFzKQsiHS9dqae5Ps8VzmEFV-L2-vmJ4mcsIV3o,3723
+deup/core/losses.py,sha256=iIioMIlCZ1vlRwUVJdbnvbm_kVws_eML5XpJKzJK8r0,6910
+deup/core/oof.py,sha256=m_A1KI0JfLZv4cNFNznX485XX0HqMd00ZB0jiwP0kH8,7835
+deup/core/protocols.py,sha256=S88ZvWh7WTSRZELW0Fs8wi2ajRRPT1j6H1J_NWB9pFo,1467
+deup/core/types.py,sha256=JAlrrQxbLglhgAG_qokLxEcWUcybr4aU2niNEkcWzLo,4476
+deup-0.1.1.dist-info/METADATA,sha256=Wee1uZjBxZuoAnlNKozrWnjb7knQCE5AZw0-HdvGj9s,4463
+deup-0.1.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+deup-0.1.1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+deup-0.1.1.dist-info/RECORD,,

deup-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

deup-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.