fairscope 0.3.0__py3-none-any.whl

fairscope/__init__.py

@@ -0,0 +1,55 @@
+"""fairscope: subgroup-stratified, calibration-aware fairness auditing for ML models.
+
+A peer-reviewed-method-backed Python library that fills documented gaps in mainstream
+fairness toolkits (AIF360, Fairlearn): per-subgroup DeLong confidence intervals,
+per-subgroup Expected Calibration Error, calibration-aware fairness, a five-axis
+Cross-Platform Fairness Evaluation (CPFE) protocol, and per-node federated audits.
+
+See ``docs/DESIGN.md`` for the methods, API design, and roadmap.
+"""
+
+__version__ = "0.3.0"
+
+__all__ = ["FairnessAudit", "__version__"]
+
+
+def FairnessAudit(model, domain, **kwargs):
+    """Route to a domain-specific fairness audit.
+
+    Parameters
+    ----------
+    model : the fitted classifier (or ``None`` with precomputed scores via the domain API).
+    domain : str
+        The audit domain. Implemented: ``"healthcare"`` (uses ``model``), ``"nlp"``
+        (the CPFE protocol; operates on precomputed ``platform_data``, ``model`` ignored),
+        ``"federated"`` (cross-node audit of precomputed ``node_data``, ``model``
+        ignored), and ``"lending"`` (annual approval-gap + subgroup CATE, ``model``
+        ignored).
+    **kwargs : passed through to the domain audit class.
+
+    Examples
+    --------
+    >>> import fairscope
+    >>> callable(fairscope.FairnessAudit)
+    True
+    """
+    if domain == "healthcare":
+        from .healthcare import HealthcareFairnessAudit
+
+        return HealthcareFairnessAudit(model, **kwargs)
+    if domain == "nlp":
+        from .nlp import CPFEProtocol
+
+        return CPFEProtocol(**kwargs)
+    if domain == "federated":
+        from .federated import FederatedFairnessAudit
+
+        return FederatedFairnessAudit(**kwargs)
+    if domain == "lending":
+        from .lending import LendingFairnessAudit
+
+        return LendingFairnessAudit(**kwargs)
+    raise ValueError(
+        f"unknown or unimplemented domain: {domain!r}; "
+        "available domains: 'healthcare', 'nlp', 'federated', 'lending'"
+    )

fairscope/core/__init__.py

@@ -0,0 +1,48 @@
+"""Core statistical primitives for fairscope.
+
+Public API for subgroup-stratified, calibration-aware fairness auditing:
+DeLong AUC confidence intervals and tests, a stratified bootstrap AUC test, calibration
+error and recalibration, multiple-comparison corrections, and subgroup fairness metrics.
+"""
+
+from .bootstrap import bootstrap_auc_test
+from .calibration import (
+    ece_by_group,
+    expected_calibration_error,
+    isotonic_recalibrate,
+    maximum_calibration_error,
+    reliability_diagram,
+    temperature_scale,
+)
+from .correction import benjamini_hochberg, bonferroni
+from .delong import (
+    delong_auc_ci,
+    delong_by_group,
+    delong_paired_test,
+    delong_unpaired_test,
+)
+from .metrics import disparate_impact, equalized_odds_difference, subgroup_metrics
+
+__all__ = [
+    # AUC confidence intervals and tests (delong)
+    "delong_auc_ci",
+    "delong_paired_test",
+    "delong_unpaired_test",
+    "delong_by_group",
+    # AUC significance via stratified bootstrap
+    "bootstrap_auc_test",
+    # calibration error and recalibration
+    "expected_calibration_error",
+    "maximum_calibration_error",
+    "ece_by_group",
+    "reliability_diagram",
+    "temperature_scale",
+    "isotonic_recalibrate",
+    # multiple-comparison correction
+    "bonferroni",
+    "benjamini_hochberg",
+    # subgroup fairness metrics
+    "disparate_impact",
+    "equalized_odds_difference",
+    "subgroup_metrics",
+]

fairscope/core/_utils.py

@@ -0,0 +1,44 @@
+"""Shared input validation. Fail loudly and early; never fail silently."""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def _as_1d_arrays(*arrays):
+    """Coerce inputs to 1-D numpy arrays of equal length; raise otherwise."""
+    out = [np.asarray(a) for a in arrays]
+    n = len(out[0])
+    for a in out:
+        if a.ndim != 1:
+            raise ValueError("inputs must be 1-D arrays")
+        if len(a) != n:
+            raise ValueError("inputs must all have the same length")
+    return out
+
+
+def _check_binary_values(y):
+    """Validate labels are binary 0/1 with no NaN. Single-class is allowed."""
+    y = np.asarray(y)
+    if np.any(np.isnan(y.astype(float))):
+        raise ValueError("y_true contains NaN")
+    uniq = np.unique(y)
+    if not set(uniq.tolist()).issubset({0, 1}):
+        raise ValueError(f"y_true must be binary 0/1; got values {uniq.tolist()}")
+    return y.astype(int)
+
+
+def _check_binary_labels(y):
+    """Like _check_binary_values, but require BOTH classes present (AUC needs both)."""
+    y = _check_binary_values(y)
+    if len(np.unique(y)) < 2:
+        raise ValueError("y_true must contain both classes (0 and 1)")
+    return y
+
+
+def _check_scores(s):
+    """Validate scores are finite floats."""
+    s = np.asarray(s, dtype=float)
+    if np.any(np.isnan(s)):
+        raise ValueError("scores contain NaN")
+    return s

fairscope/core/bootstrap.py

@@ -0,0 +1,66 @@
+"""Stratified bootstrap test for the difference between two AUCs.
+
+This is the significance procedure used for the cross-platform macro-AUC comparison in the
+CPFE protocol (stratified bootstrap standard errors, B = 2000 by default). It complements
+``delong`` (analytic per-subgroup CIs).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy import stats
+from sklearn.metrics import roc_auc_score
+
+from ._utils import _as_1d_arrays, _check_binary_labels, _check_scores
+
+
+def bootstrap_auc_test(y_true, score_a, score_b, n_boot=2000, random_state=None):
+    """Stratified bootstrap test of (AUC_a - AUC_b) on the same samples.
+
+    Resamples positives and negatives separately (preserving class balance). Returns a
+    dict: auc_a, auc_b, delta, se, z, p_value, ci_lower, ci_upper, n_boot.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> rng = np.random.default_rng(0)
+    >>> y = rng.integers(0, 2, 400)
+    >>> a = rng.random(400) + 0.8 * y
+    >>> b = rng.random(400) + 0.05 * y
+    >>> bootstrap_auc_test(y, a, b, n_boot=200, random_state=0)["delta"] > 0
+    True
+    """
+    y_true, score_a, score_b = _as_1d_arrays(y_true, score_a, score_b)
+    y = _check_binary_labels(y_true)
+    a = _check_scores(score_a)
+    b = _check_scores(score_b)
+    rng = np.random.default_rng(random_state)
+
+    pos_idx = np.flatnonzero(y == 1)
+    neg_idx = np.flatnonzero(y == 0)
+    auc_a = float(roc_auc_score(y, a))
+    auc_b = float(roc_auc_score(y, b))
+    observed = auc_a - auc_b
+
+    deltas = np.empty(n_boot, dtype=float)
+    for i in range(n_boot):
+        bp = rng.choice(pos_idx, size=pos_idx.size, replace=True)
+        bn = rng.choice(neg_idx, size=neg_idx.size, replace=True)
+        idx = np.concatenate([bp, bn])
+        yb = y[idx]
+        deltas[i] = roc_auc_score(yb, a[idx]) - roc_auc_score(yb, b[idx])
+
+    se = float(deltas.std(ddof=1))
+    z = observed / se if se > 0 else 0.0
+    lo, hi = np.percentile(deltas, [2.5, 97.5])
+    return {
+        "auc_a": auc_a,
+        "auc_b": auc_b,
+        "delta": observed,
+        "se": se,
+        "z": float(z),
+        "p_value": float(2.0 * stats.norm.sf(abs(z))),
+        "ci_lower": float(lo),
+        "ci_upper": float(hi),
+        "n_boot": n_boot,
+    }

fairscope/core/calibration.py

@@ -0,0 +1,168 @@
+"""Calibration analysis and a subgroup-stratified interface to standard recalibration.
+
+ECE/MCE bin the predicted positive-class probability (equal-width or equal-frequency) and
+compare each bin's mean probability to its observed frequency. ``temperature_scale``
+(Guo et al., 2017) and ``isotonic_recalibrate`` (Zadrozny & Elkan, 2002) are standard
+recalibration methods; the contribution here is the per-subgroup interface and pre/post-ECE
+reporting, not the methods themselves.
+
+References
+----------
+Guo, C., Pleiss, G., Sun, Y., & Weinberger, K. Q. (2017). On calibration of modern neural
+networks. ICML.
+Zadrozny, B., & Elkan, C. (2002). Transforming classifier scores into accurate multiclass
+probability estimates. KDD.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy import optimize
+from sklearn.isotonic import IsotonicRegression
+
+from ._utils import _as_1d_arrays, _check_binary_values, _check_scores
+
+
+def _bin_edges(y_prob, n_bins, strategy):
+    if strategy == "uniform":
+        return np.linspace(0.0, 1.0, n_bins + 1)
+    if strategy == "quantile":
+        edges = np.unique(np.quantile(y_prob, np.linspace(0, 1, n_bins + 1)))
+        edges[0], edges[-1] = 0.0, 1.0
+        return edges
+    raise ValueError("strategy must be 'uniform' or 'quantile'")
+
+
+def _binned_gaps(y_true, y_prob, n_bins, strategy):
+    edges = _bin_edges(y_prob, n_bins, strategy)
+    idx = np.digitize(y_prob, edges[1:-1], right=False)
+    n = len(y_prob)
+    gaps, weights = [], []
+    for b in range(len(edges) - 1):
+        mask = idx == b
+        if not np.any(mask):
+            continue
+        conf = float(np.mean(y_prob[mask]))
+        acc = float(np.mean(y_true[mask]))
+        gaps.append(abs(acc - conf))
+        weights.append(mask.sum() / n)
+    return np.array(gaps), np.array(weights)
+
+
+def expected_calibration_error(y_true, y_prob, n_bins=10, strategy="uniform"):
+    """Weighted mean |observed frequency - mean predicted probability| across bins.
+
+    Returns 0.0 if there is no data. ``strategy`` is 'uniform' (equal-width) or 'quantile'
+    (equal-frequency) bins.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> y = np.array([0, 0, 1, 1])
+    >>> p = np.array([0.0, 0.0, 1.0, 1.0])
+    >>> expected_calibration_error(y, p)
+    0.0
+    """
+    y_true, y_prob = _as_1d_arrays(y_true, y_prob)
+    y = _check_binary_values(y_true)
+    p = _check_scores(y_prob)
+    gaps, weights = _binned_gaps(y, p, n_bins, strategy)
+    return float(np.sum(weights * gaps)) if gaps.size else 0.0
+
+
+def maximum_calibration_error(y_true, y_prob, n_bins=10, strategy="uniform"):
+    """Maximum |observed frequency - mean predicted probability| over bins."""
+    y_true, y_prob = _as_1d_arrays(y_true, y_prob)
+    y = _check_binary_values(y_true)
+    p = _check_scores(y_prob)
+    gaps, _ = _binned_gaps(y, p, n_bins, strategy)
+    return float(np.max(gaps)) if gaps.size else 0.0
+
+
+def ece_by_group(y_true, y_prob, groups, n_bins=10, strategy="uniform"):
+    """Per-subgroup Expected Calibration Error. Returns ``{group: ece}``."""
+    y_true, y_prob, groups = _as_1d_arrays(y_true, y_prob, groups)
+    out = {}
+    for g in np.unique(groups):
+        mask = groups == g
+        out[g] = expected_calibration_error(y_true[mask], y_prob[mask], n_bins, strategy)
+    return out
+
+
+def reliability_diagram(y_true, y_prob, groups=None, n_bins=10):
+    """Reliability diagram (mean predicted probability vs observed frequency).
+
+    Returns a matplotlib ``Figure``. If ``groups`` is given, draws one curve per subgroup.
+    """
+    import matplotlib.pyplot as plt
+
+    y_true, y_prob = _as_1d_arrays(y_true, y_prob)
+    fig, ax = plt.subplots()
+    ax.plot([0, 1], [0, 1], linestyle="--", color="gray", label="perfect")
+
+    def _curve(yt, yp, label):
+        edges = np.linspace(0, 1, n_bins + 1)
+        idx = np.digitize(yp, edges[1:-1])
+        xs, ys = [], []
+        for b in range(n_bins):
+            m = idx == b
+            if np.any(m):
+                xs.append(float(np.mean(yp[m])))
+                ys.append(float(np.mean(yt[m])))
+        ax.plot(xs, ys, marker="o", label=label)
+
+    if groups is None:
+        _curve(np.asarray(y_true), np.asarray(y_prob), "model")
+    else:
+        groups = np.asarray(groups)
+        for g in np.unique(groups):
+            m = groups == g
+            _curve(np.asarray(y_true)[m], np.asarray(y_prob)[m], f"group={g}")
+    ax.set_xlabel("mean predicted probability")
+    ax.set_ylabel("observed frequency")
+    ax.legend()
+    return fig
+
+
+def temperature_scale(logits, y_true, max_iter=200):
+    """Fit a single temperature T>0 by minimizing NLL (Guo et al., 2017).
+
+    ``logits`` may be 1-D (binary positive-class logit) or 2-D (n, n_classes). Returns
+    ``(T, calibrated_probabilities)``; calibrated probabilities are 1-D for 1-D input.
+    """
+    logits = np.asarray(logits, dtype=float)
+    y = np.asarray(y_true).astype(int)
+    logits2 = np.column_stack([np.zeros_like(logits), logits]) if logits.ndim == 1 else logits
+
+    def _nll(log_t):
+        t = np.exp(log_t[0])  # parameterize as exp() to keep T > 0
+        z = logits2 / t
+        z = z - z.max(axis=1, keepdims=True)
+        logsumexp = np.log(np.exp(z).sum(axis=1))
+        logp = z[np.arange(len(y)), y] - logsumexp
+        return -float(np.mean(logp))
+
+    res = optimize.minimize(
+        _nll,
+        x0=[0.0],
+        method="Nelder-Mead",
+        options={"maxiter": max_iter, "xatol": 1e-4, "fatol": 1e-6},
+    )
+    temp = float(np.exp(res.x[0]))
+    z = logits2 / temp
+    z = z - z.max(axis=1, keepdims=True)
+    probs = np.exp(z)
+    probs /= probs.sum(axis=1, keepdims=True)
+    calibrated = probs[:, 1] if logits.ndim == 1 else probs
+    return temp, calibrated
+
+
+def isotonic_recalibrate(probs, y_true):
+    """Fit isotonic regression mapping predicted prob -> calibrated prob
+    (Zadrozny & Elkan, 2002). Returns ``(fitted_model, calibrated_probabilities)``."""
+    probs, y_true = _as_1d_arrays(probs, y_true)
+    p = _check_scores(probs)
+    y = _check_binary_values(y_true)
+    model = IsotonicRegression(out_of_bounds="clip", y_min=0.0, y_max=1.0)
+    calibrated = model.fit_transform(p, y)
+    return model, calibrated

fairscope/core/correction.py

@@ -0,0 +1,49 @@
+"""Multiple-comparison corrections. Outputs match
+``statsmodels.stats.multitest.multipletests`` for methods 'bonferroni' and 'fdr_bh'.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def _check_pvals(p):
+    p = np.asarray(p, dtype=float)
+    if p.ndim != 1:
+        raise ValueError("p_values must be a 1-D array")
+    if np.any(np.isnan(p)):
+        raise ValueError("p_values contain NaN")
+    if np.any((p < 0) | (p > 1)):
+        raise ValueError("p_values must lie in [0, 1]")
+    return p
+
+
+def bonferroni(p_values, alpha=0.05):
+    """Bonferroni correction. Returns adjusted, reject, threshold.
+
+    Examples
+    --------
+    >>> bonferroni([0.01, 0.5], alpha=0.05)["adjusted"].tolist()
+    [0.02, 1.0]
+    """
+    p = _check_pvals(p_values)
+    m = len(p)
+    return {
+        "adjusted": np.minimum(p * m, 1.0),
+        "reject": p <= alpha / m,
+        "threshold": alpha / m,
+    }
+
+
+def benjamini_hochberg(p_values, alpha=0.05):
+    """Benjamini-Hochberg FDR correction (step-up). Returns adjusted, reject."""
+    p = _check_pvals(p_values)
+    m = len(p)
+    order = np.argsort(p, kind="mergesort")
+    ranked = p[order]
+    adj_sorted = ranked * m / np.arange(1, m + 1)
+    adj_sorted = np.minimum.accumulate(adj_sorted[::-1])[::-1]
+    adj_sorted = np.minimum(adj_sorted, 1.0)
+    adjusted = np.empty(m, dtype=float)
+    adjusted[order] = adj_sorted
+    return {"adjusted": adjusted, "reject": adjusted <= alpha}

fairscope/core/delong.py

@@ -0,0 +1,151 @@
+"""DeLong (1988) confidence intervals and tests for AUC, via the fast midrank
+algorithm of Sun & Xu (2014).
+
+References
+----------
+DeLong, E. R., DeLong, D. M., & Clarke-Pearson, D. L. (1988). Comparing the areas under
+two or more correlated ROC curves. Biometrics, 44(3), 837-845.
+Sun, X., & Xu, W. (2014). Fast implementation of DeLong's algorithm for comparing the
+areas under correlated ROC curves. IEEE Signal Processing Letters, 21(11), 1389-1393.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy import stats
+
+from ._utils import _as_1d_arrays, _check_binary_labels, _check_scores
+
+
+def _compute_midrank(x: np.ndarray) -> np.ndarray:
+    """Midranks (average ranks for ties), O(n log n)."""
+    order = np.argsort(x, kind="mergesort")
+    sorted_x = x[order]
+    n = len(x)
+    midrank = np.zeros(n, dtype=float)
+    i = 0
+    while i < n:
+        j = i
+        while j < n and sorted_x[j] == sorted_x[i]:
+            j += 1
+        midrank[i:j] = 0.5 * (i + j - 1) + 1.0
+        i = j
+    out = np.empty(n, dtype=float)
+    out[order] = midrank
+    return out
+
+
+def _fast_delong(sorted_scores: np.ndarray, n_pos: int):
+    """Sun & Xu (2014). ``sorted_scores`` has shape (k, N) with the n_pos positives
+    first. Returns (aucs: shape (k,), covariance: shape (k, k))."""
+    k, total = sorted_scores.shape
+    n_neg = total - n_pos
+    pos = sorted_scores[:, :n_pos]
+    neg = sorted_scores[:, n_pos:]
+    tx = np.empty((k, n_pos))
+    ty = np.empty((k, n_neg))
+    tz = np.empty((k, total))
+    for r in range(k):
+        tx[r] = _compute_midrank(pos[r])
+        ty[r] = _compute_midrank(neg[r])
+        tz[r] = _compute_midrank(sorted_scores[r])
+    aucs = tz[:, :n_pos].sum(axis=1) / n_pos / n_neg - (n_pos + 1.0) / (2.0 * n_neg)
+    v01 = (tz[:, :n_pos] - tx) / n_neg
+    v10 = 1.0 - (tz[:, n_pos:] - ty) / n_pos
+    sx = np.cov(v01)
+    sy = np.cov(v10)
+    cov = sx / n_pos + sy / n_neg
+    return aucs, np.atleast_2d(cov)
+
+
+def _prepare(y: np.ndarray, score_list):
+    order = np.argsort(-y, kind="mergesort")  # label 1 (positives) first
+    n_pos = int((y == 1).sum())
+    sorted_scores = np.vstack([np.asarray(s)[order] for s in score_list])
+    return sorted_scores, n_pos
+
+
+def delong_auc_ci(y_true, y_score, alpha=0.05):
+    """AUC with a DeLong (1 - alpha) normal-approximation confidence interval.
+
+    Returns a dict: auc, ci_lower, ci_upper, se, n_pos, n_neg.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> y = np.array([1, 1, 1, 1, 0, 0, 0, 0])
+    >>> s = np.array([0.9, 0.8, 0.7, 0.4, 0.6, 0.5, 0.3, 0.2])
+    >>> round(delong_auc_ci(y, s)["auc"], 3)
+    0.875
+    """
+    y_true, y_score = _as_1d_arrays(y_true, y_score)
+    y = _check_binary_labels(y_true)
+    s = _check_scores(y_score)
+    sorted_scores, n_pos = _prepare(y, [s])
+    aucs, cov = _fast_delong(sorted_scores, n_pos)
+    auc = float(aucs[0])
+    var = float(cov[0, 0])
+    se = float(np.sqrt(var)) if var > 0 else 0.0
+    z = float(stats.norm.ppf(1 - alpha / 2.0))
+    return {
+        "auc": auc,
+        "ci_lower": max(0.0, auc - z * se),
+        "ci_upper": min(1.0, auc + z * se),
+        "se": se,
+        "n_pos": n_pos,
+        "n_neg": len(y) - n_pos,
+    }
+
+
+def delong_paired_test(y_true, score_a, score_b):
+    """Covariance-aware paired DeLong test for two scores on the SAME samples.
+
+    Returns: auc_a, auc_b, delta, z, p_value.
+    """
+    y_true, score_a, score_b = _as_1d_arrays(y_true, score_a, score_b)
+    y = _check_binary_labels(y_true)
+    a = _check_scores(score_a)
+    b = _check_scores(score_b)
+    sorted_scores, n_pos = _prepare(y, [a, b])
+    aucs, cov = _fast_delong(sorted_scores, n_pos)
+    auc_a, auc_b = float(aucs[0]), float(aucs[1])
+    var = float(cov[0, 0] + cov[1, 1] - 2.0 * cov[0, 1])
+    se = float(np.sqrt(var)) if var > 0 else 0.0
+    delta = auc_a - auc_b
+    z = delta / se if se > 0 else 0.0
+    return {
+        "auc_a": auc_a,
+        "auc_b": auc_b,
+        "delta": delta,
+        "z": float(z),
+        "p_value": float(2.0 * stats.norm.sf(abs(z))),
+    }
+
+
+def delong_unpaired_test(y_true_a, score_a, y_true_b, score_b):
+    """Unpaired DeLong test for two INDEPENDENT samples (the cross-platform case)."""
+    a = delong_auc_ci(y_true_a, score_a)
+    b = delong_auc_ci(y_true_b, score_b)
+    delta = a["auc"] - b["auc"]
+    se = float(np.sqrt(a["se"] ** 2 + b["se"] ** 2))
+    z = delta / se if se > 0 else 0.0
+    return {
+        "auc_a": a["auc"],
+        "auc_b": b["auc"],
+        "delta": delta,
+        "z": float(z),
+        "p_value": float(2.0 * stats.norm.sf(abs(z))),
+    }
+
+
+def delong_by_group(y_true, y_score, groups, alpha=0.05):
+    """Per-subgroup DeLong AUC CIs. Returns {group: ci_dict}."""
+    y_true, y_score, groups = _as_1d_arrays(y_true, y_score, groups)
+    out = {}
+    for g in np.unique(groups):
+        mask = groups == g
+        try:
+            out[g] = delong_auc_ci(y_true[mask], y_score[mask], alpha=alpha)
+        except ValueError as exc:
+            raise ValueError(f"subgroup {g!r}: {exc}") from exc
+    return out

fairscope/core/metrics.py

@@ -0,0 +1,96 @@
+"""Subgroup performance and fairness metrics.
+
+Disparate impact is the symmetric ratio of positive-prediction rates, and equalized odds
+difference is the absolute true-positive-rate gap, both as defined in the CPFE paper
+(Pall & Yadav). Note: this EOD follows the paper's definition |TPR_a - TPR_b|; some
+toolkits (e.g. Fairlearn) instead report max(|TPR diff|, |FPR diff|).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from sklearn.metrics import brier_score_loss, f1_score, roc_auc_score
+
+from ._utils import _as_1d_arrays, _check_binary_labels, _check_binary_values
+
+
+def _group_mask(groups, g):
+    mask = groups == g
+    if not np.any(mask):
+        raise ValueError(f"group {g!r} not present in `groups`")
+    return mask
+
+
+def disparate_impact(y_pred, groups, group_a, group_b):
+    """Symmetric disparate impact between two groups: min(rate_a/rate_b, rate_b/rate_a).
+
+    ``rate = P(y_pred == 1 | group)`` over hard 0/1 predictions. Result is in (0, 1];
+    < 0.80 violates the four-fifths rule and < 0.50 is a severe disparity (interpretation
+    per the CPFE paper). If both rates are 0 the groups are treated as equal (returns 1.0);
+    if exactly one rate is 0 the disparity is maximal (returns 0.0).
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> y_pred = np.array([1, 1, 0, 0, 1, 0, 0, 0])
+    >>> g = np.array(["A", "A", "A", "A", "B", "B", "B", "B"])
+    >>> round(disparate_impact(y_pred, g, "A", "B"), 3)
+    0.5
+    """
+    y_pred, groups = _as_1d_arrays(y_pred, groups)
+    yp = _check_binary_values(y_pred)
+    ra = float(np.mean(yp[_group_mask(groups, group_a)] == 1))
+    rb = float(np.mean(yp[_group_mask(groups, group_b)] == 1))
+    if ra == 0.0 and rb == 0.0:
+        return 1.0
+    if ra == 0.0 or rb == 0.0:
+        return 0.0
+    return float(min(ra / rb, rb / ra))
+
+
+def equalized_odds_difference(y_true, y_pred, groups, group_a, group_b):
+    """|TPR_a - TPR_b|, the equalized odds difference as defined in the CPFE paper.
+
+    ``TPR = P(y_pred == 1 | y_true == 1, group)``. Raises if either group has no
+    positive labels (TPR undefined).
+    """
+    y_true, y_pred, groups = _as_1d_arrays(y_true, y_pred, groups)
+    yt = _check_binary_values(y_true)
+    yp = _check_binary_values(y_pred)
+
+    def _tpr(g):
+        mask = _group_mask(groups, g)
+        pos = (yt == 1) & mask
+        if pos.sum() == 0:
+            raise ValueError(f"group {g!r} has no positive labels; TPR is undefined")
+        return float(np.mean(yp[pos] == 1))
+
+    return float(abs(_tpr(group_a) - _tpr(group_b)))
+
+
+def subgroup_metrics(y_true, y_score, groups, threshold=0.5):
+    """Per-subgroup discrimination metrics: ``{group: {auc, brier, f1, n}}``.
+
+    ``y_score`` are predicted probabilities in [0, 1] (Brier assumes a probability);
+    ``threshold`` binarizes them for F1. Raises if any subgroup is single-class (AUC
+    undefined) or if ``y_score`` contains NaN.
+    """
+    y_true, y_score, groups = _as_1d_arrays(y_true, y_score, groups)
+    y = _check_binary_labels(y_true)
+    s = np.asarray(y_score, dtype=float)
+    if np.any(np.isnan(s)):
+        raise ValueError("y_score contains NaN")
+    preds = (s >= threshold).astype(int)
+    out = {}
+    for g in np.unique(groups):
+        mask = groups == g
+        yt = y[mask]
+        if len(np.unique(yt)) < 2:
+            raise ValueError(f"subgroup {g!r} has a single class; AUC undefined")
+        out[g] = {
+            "auc": float(roc_auc_score(yt, s[mask])),
+            "brier": float(brier_score_loss(yt, s[mask])),
+            "f1": float(f1_score(yt, preds[mask], zero_division=0)),
+            "n": int(mask.sum()),
+        }
+    return out

fairscope/federated/__init__.py

@@ -0,0 +1,9 @@
+"""Cross-node (federated / multi-site) fairness auditing built on fairscope.core.
+
+AUDITS per-node predictions of an already-trained model. It does NOT perform federated
+training and provides NO privacy guarantees.
+"""
+
+from .audit import FederatedFairnessAudit, FederatedReport
+
+__all__ = ["FederatedFairnessAudit", "FederatedReport"]