imbcal 0.3.0__py3-none-any.whl

imbcal/__init__.py

@@ -0,0 +1,21 @@
+"""imbcal: calibrated probability estimation under class imbalance.
+
+Main entry point: :class:`ImbalanceCalibratedClassifier`. The safe default is to fit at the natural prevalence and
+recalibrate (``strategy="none"``); prevalence-preserving augmentation (``strategy="augment"``) can use any synthetic
+data generator and is selected by cross-validation of the recalibrated loss, with no augmentation always available.
+:func:`rebalancing_cost` predicts, before any model is fitted, the calibration slope, AUC and log-loss of
+maximum likelihood and of rebalanced logistic regressions in the proportional regime.
+"""
+from .calibration import IsotonicCalibrator, PlattCalibrator, crossfit_calibrated
+from .diagnostics import majority_exposure
+from .estimator import Candidate, ImbalanceCalibratedClassifier
+from .generators import BaseGenerator, CallableGenerator, GaussianGenerator, SMOTEGenerator
+from .metrics import (calibration_slope_intercept, expected_calibration_error, paired_comparison,
+                      probability_report)
+from .planning import print_rebalancing_cost, rebalancing_cost
+
+__version__ = "0.3.0"
+__all__ = ["ImbalanceCalibratedClassifier", "Candidate", "BaseGenerator", "SMOTEGenerator", "GaussianGenerator",
+           "CallableGenerator", "PlattCalibrator", "IsotonicCalibrator", "crossfit_calibrated",
+           "calibration_slope_intercept", "expected_calibration_error", "probability_report", "paired_comparison",
+           "majority_exposure", "rebalancing_cost", "print_rebalancing_cost"]

imbcal/_cgmt_copies.py

@@ -0,0 +1,85 @@
+"""Problema límite exacto (vía CGMT, derivación heurística) para copias contraídas: cada unidad minoritaria
+aporta x_i y r − 1 copias de x̄₁ + √γ (x_i − x̄₁). Se separa z_i = z̄ + e_i (Σ e_i = 0): w = α μ/s + τ z̄/‖z̄‖ + θ u.
+Ecuaciones (λ_r ≥ 0; F(e) = ℓ(A+e) + (r−1)ℓ(A+√γ e), A = αs + τ√(κ/π) + b, ‖w‖² = α² + τ² + θ²):
+  e = prox_{λp F}(‖w‖Z − λp ν),  c = prox_{λp ℓ}(αs − b + ‖w‖Z₀)
+  (b)  π E[F_A] = (1−π) E[ℓ'(c)]                     F_A = ℓ'(A+e) + (r−1)ℓ'(A+√γ e)
+  (α)  α(Γ̄ + λ_r) = −s[π E F_A + (1−π) E ℓ'(c)]
+  (τ)  τ(Γ̄ + λ_r) = −√(κπ) E F_A
+  (θ)  Γ̄ + λ_r = κ/λp
+  (ν)  E F'(e) = −ν                                      (media cero de la holgura minoritaria)
+  (q)  λp² [π E(F'(e)+ν)² + (1−π) E ℓ'(c)²] = κ θ²
+con Γ̄ = π E[F''/(1+λp F'')] + (1−π) E[ℓ''/(1+λp ℓ'')]. Con γ = 1 se recupera la logística con peso c = r."""
+import sys, json, warnings, numpy as np
+from scipy.optimize import root
+from scipy.special import expit
+from ._cgmt_weights import gh_x as gh_x_hermite, gh_w as gh_w_hermite
+# Cuadratura: Gauss–Legendre con 1500 nodos en [−14, 14] contra la densidad normal. Cerca de la separabilidad
+# (κ = 0,1) la norma de ŵ es grande y Gauss–Hermite con 160 nodos no basta (escala 6,242 en vez de 6,233).
+from numpy.polynomial.legendre import leggauss as _lg
+_x, _w = _lg(1500); gh_x = 14.0 * _x; gh_w = _w * 14.0 * np.exp(-gh_x**2 / 2); gh_w = gh_w / gh_w.sum()
+l1 = lambda t: -expit(-t)                 # ℓ'
+l2 = lambda t: expit(t) * expit(-t)       # ℓ''
+
+def prox_F(v, lp, A, r, g):
+    sg = np.sqrt(g); lo, hi = v - 1e-12, v + lp * (1 + (r - 1) * sg) + 1e-12
+    for _ in range(80):
+        e = 0.5 * (lo + hi); f = e + lp * (l1(A + e) + (r - 1) * sg * l1(A + sg * e)) - v
+        lo = np.where(f < 0, e, lo); hi = np.where(f < 0, hi, e)
+    return 0.5 * (lo + hi)
+
+def prox_l(v, lp):
+    lo, hi = v - 1e-12, v + lp + 1e-12
+    for _ in range(80):
+        c = 0.5 * (lo + hi); f = c + lp * l1(c) - v
+        lo = np.where(f < 0, c, lo); hi = np.where(f < 0, hi, c)
+    return 0.5 * (lo + hi)
+
+def residuals(x, s, pi, kappa, r, g, lr):
+    a, lt, lth, b, llp, nu = x
+    tau, th, lp = lt, np.exp(lth), np.exp(llp)
+    nw = np.sqrt(a * a + tau * tau + th * th); sg = np.sqrt(g)
+    A = a * s + tau * np.sqrt(kappa / pi) + b
+    e = prox_F(nw * gh_x - lp * nu, lp, A, r, g)
+    FA = l1(A + e) + (r - 1) * l1(A + sg * e)
+    Fp = l1(A + e) + (r - 1) * sg * l1(A + sg * e)
+    Fpp = l2(A + e) + (r - 1) * g * l2(A + sg * e)
+    c = prox_l(a * s - b + nw * gh_x, lp)
+    EFA, ElpC = np.sum(gh_w * FA), np.sum(gh_w * l1(c))
+    Gam = pi * np.sum(gh_w * Fpp / (1 + lp * Fpp)) + (1 - pi) * np.sum(gh_w * l2(c) / (1 + lp * l2(c)))
+    EFp = np.sum(gh_w * Fp)
+    q = lp**2 * (pi * np.sum(gh_w * (Fp + nu) ** 2) + (1 - pi) * np.sum(gh_w * l1(c) ** 2))
+    return [pi * EFA - (1 - pi) * ElpC,
+            a * (Gam + lr) + s * (pi * EFA + (1 - pi) * ElpC),
+            tau * (Gam + lr) + np.sqrt(kappa * pi) * EFA,
+            (Gam + lr) - kappa / lp,
+            EFp + nu,
+            (q - kappa * th**2) / max(kappa * th**2, 1e-12)]
+
+def solve(s, pi, kappa, r, g, lr=0.0, x0=None):
+    if x0 is None: x0 = np.array([2 * s, 0.1, np.log(0.3), -2.0, np.log(kappa / (pi * (1 - pi))), 0.0])
+    best = None
+    for method in ["hybr", "lm"]:
+        rr = root(residuals, x0, args=(s, pi, kappa, r, g, lr), method=method, options={"xtol": 1e-13} if method == "hybr" else {"xtol": 1e-14, "ftol": 1e-14})
+        res = float(np.max(np.abs(rr.fun)))
+        if best is None or res < best[1]: best = (rr.x, res)
+    x, res = best; a, tau, th = x[0], x[1], np.exp(x[2]); nw = np.sqrt(a * a + tau * tau + th * th)
+    return dict(alpha=a, tau=tau, theta=th, b=x[3], lp=np.exp(x[4]), nu=x[5], scale=nw / (2 * s), cos=a / nw, res=res), x
+
+def init_from_weights(s, pi, kappa, r):
+    """Solución de pesos c = r (γ = 1) expresada en las variables de este sistema."""
+    from . import _cgmt_weights as CP
+    E = CP.path(s, pi, kappa, [r])[r]
+    a, sig, lam, b = E["alpha"], E["sigma"], E["lam"], E["b"]
+    nw = np.hypot(a, sig); t = CP.prox(a * s + b + nw * gh_x, lam * r); Epsi = np.sum(gh_w * r * expit(-t))
+    tau = lam * Epsi * np.sqrt(pi / kappa); th = np.sqrt(max(sig**2 - tau**2, 1e-8))
+    return np.array([a, tau, np.log(th), b, np.log(lam), Epsi])
+
+def path(s, pi, kappa, r, g, lr=0.0, steps=20):
+    """continuación en γ desde 1 (pesos c = r) hasta g, a κ fijo"""
+    x = init_from_weights(s, pi, kappa, r)
+    for gg in np.linspace(1.0, g, steps):
+        rr = root(residuals, x, args=(s, pi, kappa, r, gg, lr), method="hybr", options={"xtol": 1e-13}); x = rr.x
+    a, tau, th = x[0], x[1], np.exp(x[2]); nw = np.sqrt(a * a + tau * tau + th * th)
+    return dict(alpha=a, tau=tau, theta=th, b=x[3], lp=np.exp(x[4]), nu=x[5], scale=nw / (2 * s), cos=a / nw,
+                res=float(np.max(np.abs(rr.fun))))
+

imbcal/_cgmt_weights.py

@@ -0,0 +1,116 @@
+"""Internal solver (ported from the replication package of de la Cruz, Paper A).
+
+Sistema de punto fijo (CGMT / leave-one-out) para la logística SIN regularizar con pesos de clase
+en el 2-GMM, régimen proporcional d/n → κ, por debajo del umbral de separabilidad.
+
+Modelo: y = ±1 con P(y = 1) = π; x = yμ + z, z ~ N(0, I_d), ‖μ‖ = s.
+Estimador: min_{w,b} Σ_i c(y_i) ℓ(y_i(⟨w, x_i⟩ + b)), ℓ(t) = log(1 + e^{−t}), c(+1) = c, c(−1) = 1.
+Descomposición: w = α μ/s + σ u, u ⊥ μ unitario. Margen de entrenamiento (con corrección LOO):
+    t = prox_{λ c(y) ℓ}(v),   v = α(s + H) + σ G + y b,   H, G ~ N(0, 1) independientes,
+    ψ = c(y) σ(−t) = (t − v)/λ ≥ 0.
+Ecuaciones (incógnitas α, σ, λ, b):
+    (E1) E[y ψ] = 0                        (intercepto)
+    (E2) E[ψ (s + H)] = 0                  (estacionariedad en la dirección de μ)
+    (E3) λ² E[ψ²] = κ σ²                   (norma de la parte ortogonal)
+    (E4) E[1 / (1 + λ c(y) ℓ''(t))] = 1 − κ  (grados de libertad)
+Predicción para x nuevo: logit η̂ = α(y s + h) + σ g + b − log c. Verdad: 2(y s² + s h) + logit π.
+Con c = 1/π·(1−π) se obtiene "pesos balanceados". κ → 0 recupera α = 2s, σ = 0, b = logit π + log c.
+"""
+import numpy as np
+from scipy.optimize import fsolve
+from scipy.special import expit, logit
+
+NODES = 160
+gh_x, gh_w = np.polynomial.hermite_e.hermegauss(NODES)
+gh_w = gh_w / gh_w.sum()
+# Reducción a una dimensión: v = α s + y b + τ Z con τ² = α² + σ², y por Stein
+# E[ψ H] = α E[dψ/dv], dψ/dv = −c ℓ''(t) / (1 + λ c ℓ''(t)).
+
+def prox(v, lam_c, it=8):
+    """t = v + λc σ(−t): raíz única en [v, v + λc]; bisección y luego Newton."""
+    lo, hi = v.copy(), v + lam_c
+    for _ in range(45):
+        mid = 0.5 * (lo + hi)
+        f = mid - v - lam_c * expit(-mid)
+        lo = np.where(f < 0, mid, lo); hi = np.where(f < 0, hi, mid)
+    t = 0.5 * (lo + hi)
+    for _ in range(it):
+        t = t - (t - v - lam_c * expit(-t)) / (1 + lam_c * expit(t) * expit(-t))
+    return t
+
+def residuals(par, s, pi, kappa, c):
+    a, ls, ll, b = par
+    sig, lam = np.exp(ls), np.exp(ll)
+    tau = np.hypot(a, sig)
+    e1 = e2 = e3 = e4 = 0.0
+    for y, py, cy in [(1, pi, c), (-1, 1 - pi, 1.0)]:
+        v = a * s + y * b + tau * gh_x
+        t = prox(v, lam * cy)
+        psi = cy * expit(-t)
+        l2 = cy * expit(t) * expit(-t)
+        dpsi = -l2 / (1 + lam * l2)
+        e1 += py * np.sum(gh_w * y * psi)
+        e2 += py * np.sum(gh_w * (s * psi + a * dpsi))
+        e3 += py * np.sum(gh_w * psi**2)
+        e4 += py * np.sum(gh_w / (1 + lam * l2))
+    return [e1, e2, lam**2 * e3 - kappa * sig**2, e4 - (1 - kappa)]
+
+def solve(s, pi, kappa, c, x0=None):
+    from scipy.optimize import root
+    if x0 is None:
+        lam = kappa / (pi * (1 - pi))
+        x0 = [2 * s, np.log(np.sqrt(20 * kappa)), np.log(lam), logit(pi) + np.log(c)]
+    r = root(residuals, x0, args=(s, pi, kappa, c), method="hybr", options={"xtol": 1e-12})
+    a, ls, ll, b = r.x
+    return dict(alpha=a, sigma=np.exp(ls), lam=np.exp(ll), b=b, ok=bool(r.success),
+                res=float(np.max(np.abs(r.fun)))), r.x
+
+def metrics(sol, s, pi, c, nmc=400000, seed=0):
+    a, sig, b = sol["alpha"], sol["sigma"], sol["b"]
+    rng = np.random.default_rng(seed)
+    y = np.where(rng.random(nmc) < pi, 1, -1); h = rng.normal(size=nmc); g = rng.normal(size=nmc)
+    zt = 2 * (y * s**2 + s * h) + logit(pi)
+    zh = a * (y * s + h) + sig * g + b - np.log(c)
+    eta, p = expit(zt), expit(zh)
+    yy = (y == 1).astype(float)
+    from sklearn.linear_model import LogisticRegression
+    th = [0, LogisticRegression(C=np.inf, max_iter=5000).fit(zh.reshape(-1, 1), yy).coef_[0, 0]]
+    roi = eta >= 0.05
+    err = np.abs(p - eta)
+    nb = 2 * s; nrm = np.hypot(a, sig)
+    return dict(coseno=a / nrm, norma_rel=nrm / nb, proy=a / nb, ortog=sig / nb, slope=th[1],
+                mae_eta=err.mean(), mae_eta_roi=err[roi].mean(),
+                logloss=-np.mean(yy * np.log(p) + (1 - yy) * np.log(1 - p)))
+
+def _solve_robust(s, pi, kappa, c, x0):
+    from scipy.optimize import root
+    sol, x = solve(s, pi, kappa, c, x0)
+    if not sol["ok"] or sol["res"] > 1e-9:
+        r = root(residuals, x0, args=(s, pi, kappa, c), method="lm", options={"xtol": 1e-14, "ftol": 1e-14})
+        a, ls, ll, b = r.x
+        res = float(np.max(np.abs(r.fun)))
+        if res < sol["res"]:
+            sol, x = dict(alpha=a, sigma=np.exp(ls), lam=np.exp(ll), b=b, ok=res < 1e-9, res=res), r.x
+    return sol, x
+
+def path(s, pi, kappa, cs, steps_per_unit=30):
+    """Continuación fina: en κ desde 0.005 con c = 1, luego en log c hacia arriba y hacia abajo."""
+    x0 = None
+    for k in np.linspace(min(0.005, kappa), kappa, 60):
+        _, x0 = _solve_robust(s, pi, k, 1.0, x0) if x0 is not None else solve(s, pi, k, 1.0, None)
+    out = {1.0: solve(s, pi, kappa, 1.0, x0)[0]}
+    for direction in (+1, -1):
+        targets = sorted([c for c in cs if (c > 1 if direction > 0 else c < 1)], key=lambda c: abs(np.log(c)))
+        if not targets: continue
+        lmax = abs(np.log(targets[-1]))
+        grid = np.linspace(0, lmax, max(2, int(lmax * steps_per_unit)))
+        grid = np.unique(np.r_[grid, [abs(np.log(c)) for c in targets]])
+        x = x0.copy()
+        for lg in grid[1:]:
+            c = float(np.exp(direction * lg))
+            sol, x = _solve_robust(s, pi, kappa, c, x)
+            for ct in targets:
+                if abs(abs(np.log(ct)) - lg) < 1e-12:
+                    out[ct] = sol
+    return out
+

imbcal/calibration.py

@@ -0,0 +1,63 @@
+"""Recalibration maps fitted on out-of-fold scores."""
+from __future__ import annotations
+
+import numpy as np
+from scipy.special import expit, logit
+from sklearn.isotonic import IsotonicRegression
+from sklearn.linear_model import LogisticRegression
+
+EPS = 1e-4
+
+
+def to_logit(p: np.ndarray, eps: float = EPS) -> np.ndarray:
+    return logit(np.clip(np.asarray(p, float), eps, 1 - eps))
+
+
+class PlattCalibrator:
+    """Logistic recalibration ``expit(a + b * logit(p))`` (Platt scaling on the logit scale)."""
+
+    def fit(self, p, y):
+        self.model_ = LogisticRegression(C=1e6).fit(to_logit(p).reshape(-1, 1), y)
+        self.intercept_ = float(self.model_.intercept_[0])
+        self.slope_ = float(self.model_.coef_[0, 0])
+        return self
+
+    def predict(self, p):
+        return expit(self.intercept_ + self.slope_ * to_logit(p))
+
+
+class IsotonicCalibrator:
+    """Isotonic recalibration (needs many events; unstable with fewer than a few hundred)."""
+
+    def fit(self, p, y):
+        self.model_ = IsotonicRegression(out_of_bounds="clip", y_min=1e-6, y_max=1 - 1e-6).fit(p, y)
+        return self
+
+    def predict(self, p):
+        return self.model_.predict(p)
+
+
+class IdentityCalibrator:
+    def fit(self, p, y):
+        return self
+
+    def predict(self, p):
+        return np.asarray(p, float)
+
+
+def make_calibrator(name):
+    if name in (None, "none"):
+        return IdentityCalibrator()
+    if name == "platt":
+        return PlattCalibrator()
+    if name == "isotonic":
+        return IsotonicCalibrator()
+    raise ValueError(f"unknown calibration {name!r}")
+
+
+def crossfit_calibrated(p_oof: np.ndarray, y: np.ndarray, folds, calibration: str) -> np.ndarray:
+    """Recalibrate out-of-fold scores without optimism: the map for fold j is fitted on the other folds."""
+    out = np.empty(len(y))
+    for tr, va in folds:
+        out[va] = make_calibrator(calibration).fit(p_oof[tr], y[tr]).predict(p_oof[va])
+    return out

imbcal/diagnostics.py

@@ -0,0 +1,17 @@
+"""Diagnostics for synthetic minority data."""
+from __future__ import annotations
+
+import numpy as np
+
+
+def majority_exposure(prob_fn, X_min, X_syn) -> dict:
+    """Shift in estimated risk between synthetic and real minority points.
+
+    ``delta = mean(prob_fn(X_syn)) - mean(prob_fn(X_min))``. With the true risk function this is the signed term of
+    the weighted-bias identity ∫(1-η)(q-f1) = -delta: negative values mean that the generator moves minority mass
+    towards regions dominated by the majority class, where the bias costs most. It is a descriptive heuristic: a
+    positive value does not rule out local displacement that cancels on average.
+    ``prob_fn`` maps an array of features to probabilities (e.g. a fitted model's ``predict_proba(X)[:, 1]``).
+    """
+    r = np.asarray(prob_fn(X_min), float); s = np.asarray(prob_fn(X_syn), float)
+    return dict(delta=float(s.mean() - r.mean()), mean_real=float(r.mean()), mean_synthetic=float(s.mean()))

imbcal/estimator.py

@@ -0,0 +1,280 @@
+"""Probability estimation under class imbalance with a scikit-learn compatible estimator."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import itertools
+
+import numpy as np
+from sklearn.base import BaseEstimator, ClassifierMixin, clone
+from sklearn.metrics import brier_score_loss, log_loss
+from sklearn.model_selection import KFold, StratifiedKFold
+from sklearn.utils.multiclass import type_of_target
+from sklearn.utils.validation import check_is_fitted, check_X_y, check_array, validate_data
+
+from .calibration import crossfit_calibrated, make_calibrator
+from .generators import GaussianGenerator, SMOTEGenerator
+
+
+@dataclass(frozen=True)
+class Candidate:
+    """A training scheme: no correction (generator None, chi 1) or prevalence-preserving augmentation."""
+    generator: object
+    chi: float
+
+    def label(self) -> str:
+        if self.generator is None:
+            return "none"
+        if self.generator == "weights":
+            return "weights"
+        return f"{self.generator!r}|chi={self.chi:g}"
+
+
+def _loss(name, y, p):
+    p = np.clip(p, 1e-12, 1 - 1e-12)
+    if name == "log_loss":
+        return -(y * np.log(p) + (1 - y) * np.log(1 - p))
+    if name == "brier":
+        return (p - y) ** 2
+    raise ValueError(f"unknown criterion {name!r}")
+
+
+class ImbalanceCalibratedClassifier(ClassifierMixin, BaseEstimator):
+    """Wrap any probabilistic classifier for calibrated probabilities at the natural prevalence.
+
+    Parameters
+    ----------
+    estimator : scikit-learn classifier with ``sample_weight`` support in ``fit`` and ``predict_proba``.
+    strategy : {"none", "weights", "augment"}
+        ``"none"``: fit at the natural prevalence (recommended default).
+        ``"weights"``: balanced class weights with recalibration (provided for comparison; it usually hurts).
+        ``"augment"``: prevalence-preserving augmentation. Real minority points get weight ``chi`` and ``m``
+        synthetic points from a generator get weight ``(1 - chi) n_min / m``, so the training prevalence is the
+        natural one. ``(generator, chi)`` is chosen by cross-validation of the *recalibrated* loss, with
+        ``chi = 1`` (no augmentation) always among the candidates.
+    generators : list of generators for ``"augment"``. Default: Gaussian smoothed bootstrap with h in {0.25, 0.5}
+        and SMOTE with k = 5 and k = sqrt(n_min). Features should be on a common scale.
+    chi_grid : weights of the real minority points for ``"augment"`` (1 is always added).
+    calibration : {"platt", "isotonic", None}. Fitted on out-of-fold scores of the selected scheme.
+    criterion : {"log_loss", "brier"} used for selection.
+    selection : {"best", "1se", "safe"}. ``"1se"`` keeps ``chi = 1`` unless the best candidate improves on it by more
+        than one standard error of the per-observation loss difference. ``"safe"`` augments only if some candidate
+        improves on ``chi = 1`` with simultaneous significance at level ``alpha``: paired cross-validated loss
+        differences, within-fold variance (Bayle, Bayle, Janson and Mackey, 2020) and a max-T critical value from the
+        estimated correlation between candidates; among the candidates that pass, the one with the smallest criterion.
+        Asymptotically, the probability of selecting a candidate that is not better than ``chi = 1`` is at most
+        ``alpha``.
+    alpha : level of the ``"safe"`` selection (accepted risk of selecting a candidate that does not improve).
+    variance_floor : for ``"safe"``, each candidate's standard deviation is replaced by
+        ``max(sd, variance_floor * sd(loss of chi = 1))``; this makes the guarantee hold without fixing in advance which
+        candidates are non-degenerate (a floor can only make the test more conservative).
+    n_synthetic : number of synthetic points; default ``n_majority - n_minority``.
+    cv : number of stratified folds.
+    nested : {"aligned", "crossfit"}
+        How the recalibration enters the selection criterion. ``"aligned"`` (default) is strictly nested: the
+        candidate evaluated on fold v, including its recalibration map, is built from the other folds only; the map of
+        fold v is fitted on scores of fold u != v from models trained without folds u and v, so each candidate costs
+        ``cv + cv(cv-1)/2`` fits. ``"crossfit"`` (v0.1 behaviour) fits the map of fold v on the out-of-fold scores of
+        the other folds, whose models saw fold v; cheaper (``cv`` fits) but not covered by the oracle inequality.
+    output : {"ensemble", "refit"}
+        ``"ensemble"`` (default) predicts with the average of the ``cv`` recalibrated fold predictors of the selected
+        candidate, which inherits the guarantee of the selection by convexity of the loss and needs no extra fit.
+        ``"refit"`` refits the selected candidate on all data and recalibrates it with the map fitted on the
+        out-of-fold scores. With high-variance base learners (for example unpenalized logistic regression with few
+        events per variable) the ensemble can be underconfident, with calibration slope above one: each fold map
+        corrects the overfitting of a single fold model, but the average of the fold models already overfits less.
+        ``"refit"`` is then usually better calibrated; with stable learners the ensemble is usually as good or better.
+        Compare both on the problem at hand when calibration slope matters.
+    stratify : bool
+        Stratified folds (default, more stable with few events). The oracle inequality assumes folds independent of
+        the data, i.e. ``stratify=False``.
+    random_state : int or None.
+
+    Attributes
+    ----------
+    selected_ : Candidate chosen.
+    cv_results_ : dict label -> cross-validated recalibrated loss.
+    candidate_distance_ : root mean squared difference between the out-of-fold probabilities of the selected
+        scheme and those of ``chi = 1`` (controls the worst-case loss of the selection, Prop. 4 of the paper).
+    calibrator_ : fitted recalibration map (``output="refit"``).
+    estimators_, calibrators_ : fold predictors and their maps (``output="ensemble"``).
+    """
+
+    def __init__(self, estimator, strategy="none", generators=None, chi_grid=(0.0, 0.1, 0.25, 0.5, 0.75),
+                 calibration="platt", criterion="log_loss", selection="best", n_synthetic=None, cv=5,
+                 nested="aligned", output="ensemble", stratify=True, alpha=0.2, variance_floor=0.05,
+                 random_state=None):
+        self.estimator = estimator
+        self.strategy = strategy
+        self.generators = generators
+        self.chi_grid = chi_grid
+        self.calibration = calibration
+        self.criterion = criterion
+        self.selection = selection
+        self.n_synthetic = n_synthetic
+        self.cv = cv
+        self.nested = nested
+        self.output = output
+        self.stratify = stratify
+        self.alpha = alpha
+        self.variance_floor = variance_floor
+        self.random_state = random_state
+
+    # ------------------------------------------------------------------ internals
+    def _candidates(self):
+        if self.strategy == "none":
+            return [Candidate(None, 1.0)]
+        if self.strategy == "weights":
+            return [Candidate("weights", 1.0)]
+        if self.strategy != "augment":
+            raise ValueError(f"unknown strategy {self.strategy!r}")
+        gens = self.generators if self.generators is not None else [
+            GaussianGenerator(0.25), GaussianGenerator(0.5), SMOTEGenerator(5), SMOTEGenerator("sqrt")]
+        return [Candidate(None, 1.0)] + [Candidate(g, float(c)) for g in gens for c in self.chi_grid if c < 1]
+
+    def _fit_predict(self, X, y, Xt, cand, rng, synth_cache=None):
+        est = clone(self.estimator)
+        if cand.generator is None:
+            est.fit(X, y)
+        elif cand.generator == "weights":
+            n1 = y.sum(); r = (len(y) - n1) / n1
+            est.fit(X, y, sample_weight=np.where(y == 1, r, 1.0))
+        else:
+            n1 = int(y.sum()); n0 = len(y) - n1
+            m = int(self.n_synthetic) if self.n_synthetic else max(n0 - n1, n1)
+            key = id(cand.generator)
+            if synth_cache is not None and key in synth_cache:
+                S = synth_cache[key]
+            else:
+                S = cand.generator.sample(X[y == 1], m, rng)
+                if synth_cache is not None:
+                    synth_cache[key] = S
+            XX = np.vstack([X, S]); YY = np.r_[y, np.ones(len(S), int)]
+            W = np.r_[np.where(y == 1, cand.chi, 1.0), np.full(len(S), (1 - cand.chi) * n1 / len(S))]
+            est.fit(XX, YY, sample_weight=W)
+        return est, np.clip(est.predict_proba(Xt)[:, 1], 1e-6, 1 - 1e-6)
+
+    # ------------------------------------------------------------------ API
+    def __sklearn_tags__(self):
+        tags = super().__sklearn_tags__()
+        tags.classifier_tags.multi_class = False
+        return tags
+
+    def fit(self, X, y):
+        X, y = validate_data(self, X, y)
+        y_type = type_of_target(y, input_name="y", raise_unknown=True)
+        if y_type not in ("binary",):
+            if y_type in ("continuous", "continuous-multioutput"):
+                raise ValueError(f"Unknown label type: {y_type!r}")
+            raise ValueError(f"Only binary classification is supported; got target type {y_type!r}")
+        self.classes_ = np.unique(y)
+        if len(self.classes_) < 2:
+            raise ValueError("The data contains only one class; this classifier needs samples of 2 classes.")
+        if self.nested not in ("aligned", "crossfit"):
+            raise ValueError(f"unknown nested {self.nested!r}")
+        if self.output not in ("ensemble", "refit"):
+            raise ValueError(f"unknown output {self.output!r}")
+        if self.selection not in ("best", "1se", "safe"):
+            raise ValueError(f"unknown selection {self.selection!r}")
+        y = (y == self.classes_[1]).astype(int)
+        rng = np.random.default_rng(self.random_state)
+        V = self.cv
+        splitter = StratifiedKFold if self.stratify else KFold
+        folds = list(splitter(V, shuffle=True, random_state=int(rng.integers(2**31 - 1))).split(X, y))
+        fid = np.empty(len(y), int)
+        for v, (_, va) in enumerate(folds):
+            fid[va] = v
+        cands = self._candidates()
+        oof = {c: np.empty(len(y)) for c in cands}
+        fold_est = {c: [None] * V for c in cands}
+        for v, (tr, va) in enumerate(folds):
+            cache = {}
+            for c in cands:
+                fold_est[c][v], oof[c][va] = self._fit_predict(X[tr], y[tr], X[va], c, rng, cache)
+        maps = {c: [None] * V for c in cands}
+        pred = {c: np.empty(len(y)) for c in cands}
+        if self.nested == "aligned":
+            pair = {c: {} for c in cands}
+            for u, v in itertools.combinations(range(V), 2):
+                idx = np.where((fid != u) & (fid != v))[0]
+                iu, iv = folds[u][1], folds[v][1]
+                cache = {}
+                for c in cands:
+                    _, s = self._fit_predict(X[idx], y[idx], np.vstack([X[iu], X[iv]]), c, rng, cache)
+                    pair[c][(u, v)] = s[:len(iu)]
+                    pair[c][(v, u)] = s[len(iu):]
+            for c in cands:
+                for v, (_, va) in enumerate(folds):
+                    others = [u for u in range(V) if u != v]
+                    s = np.concatenate([pair[c][(u, v)] for u in others])
+                    yy = np.concatenate([y[folds[u][1]] for u in others])
+                    maps[c][v] = make_calibrator(self.calibration).fit(s, yy)
+                    pred[c][va] = maps[c][v].predict(oof[c][va])
+        else:
+            for c in cands:
+                for v, (tr, va) in enumerate(folds):
+                    maps[c][v] = make_calibrator(self.calibration).fit(oof[c][tr], y[tr])
+                    pred[c][va] = maps[c][v].predict(oof[c][va])
+        crit_obs = {c: _loss(self.criterion, y, pred[c]) for c in cands}
+        crit = {c: float(v.mean()) for c, v in crit_obs.items()}
+        best = min(cands, key=crit.get)
+        base = cands[0]
+        if self.selection == "1se" and best != base:
+            d = crit_obs[best] - crit_obs[base]
+            if not d.mean() < -d.std(ddof=1) / np.sqrt(len(d)):
+                best = base
+        elif self.selection == "safe":
+            best, self.safe_z_, self.safe_critical_value_ = self._safe_select(cands, crit, crit_obs, fid, rng)
+        self.selected_ = best
+        self.cv_results_ = {c.label(): crit[c] for c in cands}
+        self.candidate_distance_ = float(np.sqrt(np.mean((oof[best] - oof[base]) ** 2)))
+        if self.output == "ensemble":
+            self.estimators_ = fold_est[best]
+            self.calibrators_ = maps[best]
+            self.fold_weights_ = np.array([len(va) for _, va in folds], float) / len(y)
+        else:
+            self.calibrator_ = make_calibrator(self.calibration).fit(oof[best], y)
+            self.estimator_, _ = self._fit_predict(X, y, X[:1], best, rng)
+        self.n_features_in_ = X.shape[1]
+        return self
+
+    def _safe_select(self, cands, crit, crit_obs, fid, rng):
+        base = cands[0]
+        others = [c for c in cands[1:]]
+        n = len(fid)
+        D = np.array([crit_obs[c] - crit_obs[base] for c in others])
+        Dc = D.copy()
+        var = np.zeros(len(others))
+        for v in np.unique(fid):
+            idx = fid == v
+            var += idx.sum() / n * D[:, idx].var(1, ddof=1)
+            Dc[:, idx] -= Dc[:, idx].mean(1, keepdims=True)
+        tau = self.variance_floor * crit_obs[base].std()
+        active = np.flatnonzero(np.maximum(var, tau ** 2) > 0)
+        z = np.zeros(len(others))
+        z[active] = D[active].mean(1) / np.sqrt(np.maximum(var[active], tau ** 2) / n)
+        zdict = {c.label(): float(z[j]) for j, c in enumerate(others)}
+        if len(active) == 0:
+            return base, zdict, np.inf
+        R = np.atleast_2d(np.nan_to_num(np.corrcoef(Dc[active]))) + 1e-9 * np.eye(len(active))
+        W = rng.multivariate_normal(np.zeros(len(active)), R, size=20000, method="eigh")
+        c_alpha = float(-np.quantile(W.min(1), self.alpha))
+        passed = [others[j] for j in active if z[j] < -c_alpha]
+        if not passed:
+            return base, zdict, c_alpha
+        return min(passed, key=crit.get), zdict, c_alpha
+
+    def predict_proba(self, X):
+        check_is_fitted(self, "selected_")
+        X = validate_data(self, X, reset=False)
+        if self.output == "ensemble":
+            p1 = np.average([m.predict(np.clip(e.predict_proba(X)[:, 1], 1e-6, 1 - 1e-6))
+                             for e, m in zip(self.estimators_, self.calibrators_)], axis=0,
+                            weights=self.fold_weights_)
+        else:
+            p1 = self.calibrator_.predict(np.clip(self.estimator_.predict_proba(X)[:, 1], 1e-6, 1 - 1e-6))
+        return np.c_[1 - p1, p1]
+
+    def predict(self, X, threshold: float = 0.5):
+        check_is_fitted(self, "selected_")
+        return self.classes_[(self.predict_proba(X)[:, 1] >= threshold).astype(int)]

imbcal/generators.py

@@ -0,0 +1,73 @@
+"""Synthetic minority generators.
+
+A generator draws ``m`` synthetic minority points from the observed minority sample. Any object with a
+``sample(X_min, m, rng)`` method can be used, so deep generators (CTGAN, TVAE, diffusion models) plug in through a
+thin wrapper.
+"""
+from __future__ import annotations
+
+import numpy as np
+from sklearn.neighbors import NearestNeighbors
+
+
+class BaseGenerator:
+    """Interface: ``sample(X_min, m, rng) -> ndarray of shape (m, n_features)``."""
+
+    def sample(self, X_min: np.ndarray, m: int, rng: np.random.Generator) -> np.ndarray:  # pragma: no cover
+        raise NotImplementedError
+
+    def __repr__(self) -> str:
+        args = ", ".join(f"{k}={v!r}" for k, v in vars(self).items())
+        return f"{type(self).__name__}({args})"
+
+
+class SMOTEGenerator(BaseGenerator):
+    """SMOTE interpolation towards one of the ``k`` nearest minority neighbours.
+
+    ``k="sqrt"`` uses ``ceil(sqrt(n_min))`` neighbours, a wider kernel than the usual ``k=5``.
+    """
+
+    def __init__(self, k: int | str = 5):
+        self.k = k
+
+    def sample(self, X_min, m, rng):
+        n1 = len(X_min)
+        if n1 < 2:
+            raise ValueError("SMOTE needs at least two minority points")
+        k = int(np.ceil(np.sqrt(n1))) if self.k == "sqrt" else int(self.k)
+        k = max(1, min(k, n1 - 1))
+        nb = NearestNeighbors(n_neighbors=k + 1).fit(X_min).kneighbors(X_min, return_distance=False)[:, 1:]
+        i = rng.integers(0, n1, m)
+        j = nb[i, rng.integers(0, k, m)]
+        return X_min[i] + rng.random((m, 1)) * (X_min[j] - X_min[i])
+
+
+class GaussianGenerator(BaseGenerator):
+    """Smoothed bootstrap: a resampled minority point plus ``N(0, h^2 I)`` noise.
+
+    ``h`` is in the units of the features passed to ``fit`` (standardize first for a scale-free ``h``). With a
+    Gaussian-kernel learner this is exactly a wider bandwidth for the minority class.
+    """
+
+    def __init__(self, h: float = 0.25):
+        self.h = h
+
+    def sample(self, X_min, m, rng):
+        return X_min[rng.integers(0, len(X_min), m)] + self.h * rng.normal(size=(m, X_min.shape[1]))
+
+
+class CallableGenerator(BaseGenerator):
+    """Wrap a function ``f(X_min, m, rng) -> ndarray``."""
+
+    def __init__(self, func, name: str = "callable"):
+        self.func = func
+        self.name = name
+
+    def sample(self, X_min, m, rng):
+        out = np.asarray(self.func(X_min, m, rng), dtype=float)
+        if out.shape != (m, X_min.shape[1]):
+            raise ValueError(f"generator returned shape {out.shape}, expected {(m, X_min.shape[1])}")
+        return out
+
+    def __repr__(self) -> str:
+        return f"CallableGenerator({self.name})"

imbcal/metrics.py

@@ -0,0 +1,70 @@
+"""Metrics for probability estimation and paired comparisons over repeated splits."""
+from __future__ import annotations
+
+import numpy as np
+from scipy.special import logit
+from sklearn.linear_model import LogisticRegression
+from sklearn.metrics import brier_score_loss, log_loss, roc_auc_score
+
+
+def calibration_slope_intercept(y, p, eps: float = 1e-6):
+    """Logistic recalibration of ``logit(p)``: returns (slope, intercept). Ideal values: 1 and 0."""
+    z = logit(np.clip(np.asarray(p, float), eps, 1 - eps)).reshape(-1, 1)
+    m = LogisticRegression(C=1e6).fit(z, y)
+    return float(m.coef_[0, 0]), float(m.intercept_[0])
+
+
+def expected_calibration_error(y, p, n_bins: int = 10, strategy: str = "quantile"):
+    """ECE with equal-frequency (default) or equal-width bins. A secondary, binning-dependent summary."""
+    y = np.asarray(y, float); p = np.asarray(p, float)
+    if strategy == "quantile":
+        edges = np.unique(np.quantile(p, np.linspace(0, 1, n_bins + 1)))
+    else:
+        edges = np.linspace(0, 1, n_bins + 1)
+    idx = np.clip(np.searchsorted(edges, p, side="right") - 1, 0, len(edges) - 2)
+    ece = 0.0
+    for b in range(len(edges) - 1):
+        sel = idx == b
+        if sel.any():
+            ece += sel.mean() * abs(y[sel].mean() - p[sel].mean())
+    return float(ece)
+
+
+def probability_report(y, p) -> dict:
+    """Log-loss, Brier score, AUC, calibration slope and intercept, ECE and mean predicted probability."""
+    p = np.clip(np.asarray(p, float), 1e-12, 1 - 1e-12)
+    slope, intercept = calibration_slope_intercept(y, p)
+    return dict(log_loss=float(log_loss(y, p, labels=[0, 1])), brier=float(brier_score_loss(y, p)),
+                auc=float(roc_auc_score(y, p)) if 0 < np.sum(y) < len(y) else float("nan"),
+                calibration_slope=slope, calibration_intercept=intercept,
+                ece=expected_calibration_error(y, p), mean_prediction=float(p.mean()), prevalence=float(np.mean(y)))
+
+
+def paired_comparison(scores_a, scores_b, n_train: int, n_test: int) -> dict:
+    """Compare two methods evaluated on the same B repeated splits (lower score = better).
+
+    Returns the mean difference ``a - b``, the naive and the Nadeau--Bengio corrected standard errors,
+    sd(D) * sqrt(1/B + n_test/n_train), the corrected z statistic, the number of splits in which ``a`` is
+    better (``wins_a``) and the two-sided exact sign-test p-value.
+
+    The correction was derived for random train/test splits of one data set with n_test < n_train. When the
+    training sets are small relative to the test sets the factor n_test/n_train makes it very conservative
+    (it does not vanish as B grows), and a warning is issued; the sign test is then a useful complement.
+    """
+    import warnings
+    from scipy.stats import binomtest
+    d = np.asarray(scores_a, float) - np.asarray(scores_b, float)
+    B = len(d)
+    if B < 2:
+        raise ValueError("need at least two splits")
+    if n_test > n_train:
+        warnings.warn("n_test > n_train: the Nadeau-Bengio correction is very conservative in this design",
+                      UserWarning, stacklevel=2)
+    sd = d.std(ddof=1)
+    se_naive = sd / np.sqrt(B)
+    se_nb = sd * np.sqrt(1 / B + n_test / n_train)
+    wins = int(np.sum(d < 0)); ties = int(np.sum(d == 0))
+    p_sign = float(binomtest(wins, B - ties, 0.5).pvalue) if B - ties > 0 else 1.0
+    return dict(mean_difference=float(d.mean()), se_naive=float(se_naive), se_corrected=float(se_nb),
+                z_corrected=float(d.mean() / se_nb) if se_nb > 0 else 0.0, wins_a=wins, sign_test_p=p_sign,
+                n_splits=B)

imbcal/planning.py

@@ -0,0 +1,91 @@
+"""rebalancing_cost: what will rebalancing cost before you fit the model?
+
+Asymptotic prediction (proportional regime, two-class Gaussian mixture; Theorems 2 and 5 of the paper, the latter
+solved at zero penalty) of the validation calibration slope, AUC and log-loss of an unpenalized logistic regression fitted
+  - by maximum likelihood ("mle"),
+  - with balanced class weights followed by the intercept correction ("weights"),
+  - after random undersampling to balance, with the intercept correction ("undersampling"),
+  - after balanced SMOTE, with the intercept correction ("smote"; contracted-copies model),
+together with the van Houwelingen shrinkage factor used in sample-size criteria (Riley et al., 2019).
+
+Inputs are quantities that can be specified before data collection: the number of model parameters p, the
+outcome prevalence, either the development sample size n or the events per variable (EPV), and the anticipated
+AUC of a well-fitted model. The predictions hold in the Gaussian-mixture model. In the two applications of the paper
+the observed damage was at least as large, more so with many rare binary predictors and at low EPV; this is an
+empirical observation, not a guarantee.
+
+Usage:
+  >>> from imbcal.planning import rebalancing_cost, print_rebalancing_cost
+  >>> print_rebalancing_cost(rebalancing_cost(p=71, prevalence=0.092, epv=2.5, auc=0.81))
+"""
+import warnings
+import numpy as np
+from scipy.stats import norm
+from scipy.special import expit, logit
+from scipy.optimize import brentq
+from . import _cgmt_weights as CP
+from . import _cgmt_copies as CC
+
+GH_X, GH_W = CP.gh_x, CP.gh_w
+
+def _weights_solution(s, pi, kappa, c):
+    """Unpenalized class-weighted logistic regression (Theorem 2): returns (m, q, b) with continuation in kappa and c."""
+    sol = CP.path(s, pi, kappa, [c])
+    S = sol[c] if c != 1 else sol[1.0]
+    a, sig = S["alpha"], S["sigma"]
+    return a * s, a * a + sig * sig, S["b"], bool(S["ok"])
+
+def _evaluate(m, q, b_eff, s, pi):
+    """Score T | y ~ N(y m, q); predicted log-odds T + b_eff; returns slope, AUC, log-loss (exact under the mixture)."""
+    rho = m / (s * np.sqrt(q))
+    ll = 0.0
+    for y, py in [(1, pi), (-1, 1 - pi)]:
+        z = y * m + np.sqrt(q) * GH_X + b_eff
+        ll += py * np.sum(GH_W * (np.logaddexp(0, -z) if y == 1 else np.logaddexp(0, z)))
+    return dict(calibration_slope=2 * m / q, auc=float(norm.cdf(np.sqrt(2) * s * rho)), log_loss=float(ll))
+
+def rebalancing_cost(p, prevalence, auc, n=None, epv=None, smote_contraction=2 / 3):
+    """Predicted validation metrics for each method. Give n (development sample size) or epv (events per parameter).
+    auc: anticipated AUC of a well-fitted model, used to set the separation s = Phi^{-1}(auc)/sqrt(2).
+    smote_contraction: squared-distance contraction of SMOTE points toward the minority mean (2/3 in high dimension,
+    Lemma 2; larger, e.g. 0.8-0.9, with many binary predictors)."""
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+        return _rebalancing_cost(p, prevalence, auc, n=n, epv=epv, smote_contraction=smote_contraction)
+
+
+def _rebalancing_cost(p, prevalence, auc, n=None, epv=None, smote_contraction=2 / 3):
+    if (n is None) == (epv is None):
+        raise ValueError("give exactly one of n or epv")
+    pi = float(prevalence)
+    n = float(n) if n is not None else epv * p / pi
+    kappa = p / n
+    s = norm.ppf(auc) / np.sqrt(2)
+    r = (1 - pi) / pi
+    out = {}
+    m, q, b, ok = _weights_solution(s, pi, kappa, 1.0); out["mle"] = _evaluate(m, q, b, s, pi)
+    m, q, b, ok = _weights_solution(s, pi, kappa, r); out["weights"] = _evaluate(m, q, b - np.log(r), s, pi)
+    m, q, b, ok = _weights_solution(s, 0.5, kappa / (2 * pi), 1.0); out["undersampling"] = _evaluate(m, q, b - np.log(r), s, pi)
+    sol = CC.path(s, pi, kappa, r, smote_contraction)
+    nw2 = sol["alpha"] ** 2 + sol["tau"] ** 2 + sol["theta"] ** 2
+    A = sol["alpha"] * s                                           # m = <w, mu>
+    out["smote"] = _evaluate(A, nw2, sol["b"] - np.log(r), s, pi)
+    # van Houwelingen shrinkage factor with R2_CS of the Bayes model
+    H = -(pi * np.log(pi) + (1 - pi) * np.log(1 - pi))
+    Lb = _evaluate(2 * s * s, 4 * s * s, logit(pi), s, pi)["log_loss"]
+    R2 = 1 - np.exp(-2 * (H - Lb))
+    vh = brentq(lambda S: (S - 1) * np.log(1 - R2 / S) - kappa, R2 + 1e-9, 1 - 1e-12)
+    return dict(inputs=dict(p=p, prevalence=pi, n=n, epv=pi * n / p, kappa=kappa, auc=auc, separation=s,
+                            smote_contraction=smote_contraction),
+                methods=out, van_houwelingen_shrinkage=vh)
+
+def print_rebalancing_cost(res):
+    i = res["inputs"]
+    print(f"p={i['p']}  prevalence={i['prevalence']:.3f}  n={i['n']:.0f}  EPV={i['epv']:.2f}  kappa=p/n={i['kappa']:.4f}  "
+          f"anticipated AUC={i['auc']:.3f}")
+    print(f"{'method':<15}{'cal. slope':>11}{'AUC':>8}{'log-loss':>10}")
+    for k, v in res["methods"].items():
+        print(f"{k:<15}{v['calibration_slope']:>11.3f}{v['auc']:>8.3f}{v['log_loss']:>10.4f}")
+    print(f"van Houwelingen shrinkage factor (maximum likelihood): {res['van_houwelingen_shrinkage']:.3f}")
+    print("Asymptotic Gaussian-mixture predictions; in the paper's two applications the observed damage was at least this large (empirical, not a guarantee).")
+

imbcal-0.3.0.dist-info/METADATA

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: imbcal
+Version: 0.3.0
+Summary: Calibrated probability estimation under class imbalance: safe pipelines, prevalence-preserving augmentation and diagnostics
+Author-email: Rolando de la Cruz <rolando.delacruz@uai.cl>
+License-Expression: MIT
+Keywords: calibration,class imbalance,SMOTE,synthetic data,recalibration,scikit-learn,risk prediction
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+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: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: scikit-learn>=1.6
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# imbcal
+
+**Calibrated probability estimation under class imbalance.**
+
+```
+pip install imbcal
+```
+
+Rebalancing (class weights, undersampling, SMOTE) is the default answer to class imbalance, but it targets classification and damages the probabilities that risk prediction needs, even after recalibration. `imbcal` wraps any scikit-learn classifier with pipelines that estimate probabilities at the natural prevalence:
+
+- **`strategy="none"`** (recommended default): fit at the natural prevalence, then recalibrate (Platt or isotonic) on out-of-fold scores.
+- **`strategy="augment"`**: *prevalence-preserving augmentation*. Synthetic minority points from any generator receive weights that keep the training prevalence unchanged. Real minority points get weight `chi`, and the `m` synthetic points get `(1 - chi) n_min / m`. The generator and `chi` are chosen by cross-validation of the **recalibrated** loss, and `chi = 1` (no augmentation) is always a candidate, so the selection can fall back to the natural fit.
+- **`strategy="weights"`**: balanced weights with recalibration, for comparison.
+- **`selection="safe"`**: augment only if some candidate beats no augmentation with simultaneous significance (cross-validation with confidence and a max-T critical value), which controls the probability of choosing a harmful augmentation.
+
+It also provides metrics (log-loss, Brier score, calibration slope and intercept, ECE), paired comparisons over repeated splits (Nadeau–Bengio corrected standard errors and a sign test), diagnostics for synthetic data, and a planning tool:
+
+```python
+from imbcal import rebalancing_cost, print_rebalancing_cost
+# predicted calibration slope, AUC and log-loss of maximum likelihood and of rebalanced
+# logistic regressions, before any data are collected
+print_rebalancing_cost(rebalancing_cost(p=36, prevalence=0.092, auc=0.81, epv=2.5))
+```
+
+## Example
+
+```python
+from sklearn.ensemble import RandomForestClassifier
+from imbcal import ImbalanceCalibratedClassifier, GaussianGenerator, SMOTEGenerator, probability_report
+
+model = ImbalanceCalibratedClassifier(
+    RandomForestClassifier(min_samples_leaf=10),
+    strategy="augment",
+    generators=[GaussianGenerator(0.25), SMOTEGenerator(k="sqrt")],
+    calibration="platt", selection="1se", random_state=0,
+).fit(X_train, y_train)
+
+print(model.selected_.label(), model.candidate_distance_)
+print(probability_report(y_test, model.predict_proba(X_test)[:, 1]))
+```
+
+Any object with a `sample(X_min, m, rng)` method can be used as a generator, including wrappers around deep tabular generators.
+
+## Status
+
+Alpha (0.3.0). Binary outcomes only; requires scikit-learn >= 1.6. The API may change before 1.0. Planned additions:
+- generators for mixed (continuous and categorical) features;
+- group-wise calibration diagnostics;
+- wrappers for deep tabular generators;
+- multiclass outcomes.
+
+## License
+
+MIT.

imbcal-0.3.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+imbcal/__init__.py,sha256=uu0tzQAYxbDINBeJJthLeckGXHAohSTuJa_WlSvwo3g,1522
+imbcal/_cgmt_copies.py,sha256=lgBPoa1FihXGNLfk7e-p_DWQfY6vjvxZTHoM4K4WBU4,4998
+imbcal/_cgmt_weights.py,sha256=UAqDbvr9Vtpq-2d3ifL-htz_jEI_K1nQQJMmg6VBtfo,5546
+imbcal/calibration.py,sha256=A1HGy6Oa41EmIPXxFhxkhk6SPJVVGHzcd5VyBr8PJW4,1945
+imbcal/diagnostics.py,sha256=4QutKPOfMCWQd5xZfGv-HFn8aofiSXKxddq3DyeOizI,970
+imbcal/estimator.py,sha256=Wdwz-t3wKWF8AQnoW6m7DNRpMqeAcsf8Pw3lOXdB5XI,15108
+imbcal/generators.py,sha256=ZG52DdVRMMb1dzVhC3gAU9zvwhigghP6qJMvIa65g_M,2662
+imbcal/metrics.py,sha256=HDWyG3R7aIcKwoypVSnMwlg0Yrn1HEQWtJ660NwF3hU,3595
+imbcal/planning.py,sha256=WgomwCgf8ZhFqBgQd7lk6ntkfvPlN2AMQyt3xnDQ3Zc,5302
+imbcal-0.3.0.dist-info/licenses/LICENSE,sha256=Dm0S1bb57ViulhZc6fylUMG01s1sCxMcB7HPNxoHJ7I,1075
+imbcal-0.3.0.dist-info/METADATA,sha256=9p3UycwJn9snIstfjSzhPMIXrglmAb6krXpnsiBMJ-c,4044
+imbcal-0.3.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+imbcal-0.3.0.dist-info/top_level.txt,sha256=Y137XCijEDPuPw32x_iB5ICllkTqO-j83zJNwbPGcfY,7
+imbcal-0.3.0.dist-info/RECORD,,

imbcal-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

imbcal-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rolando de la Cruz
+
+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.

imbcal-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+imbcal