fairscope 0.3.0__py3-none-any.whl

fairscope/nlp/attribution.py

@@ -0,0 +1,54 @@
+"""Axis 5 of CPFE: attribution stability via Jaccard overlap of top-K gradient-saliency
+token sets across platforms (CPFE paper). The Jaccard computation is dependency-free; the
+gradient-saliency extraction uses Captum and requires ``pip install fairscope[nlp]``.
+"""
+
+from __future__ import annotations
+
+
+def jaccard_topk(saliency_a, saliency_b, k):
+    """Jaccard overlap of the top-k tokens by saliency: ``|topK(A) ∩ topK(B)| / |union|``.
+
+    ``saliency_*`` map token -> saliency score. Returns 0.0 if both are empty.
+
+    Examples
+    --------
+    >>> jaccard_topk({"a": 0.9, "b": 0.8}, {"a": 0.7, "c": 0.6}, k=2)
+    0.3333333333333333
+    """
+    top_a = set(sorted(saliency_a, key=saliency_a.get, reverse=True)[:k])
+    top_b = set(sorted(saliency_b, key=saliency_b.get, reverse=True)[:k])
+    union = top_a | top_b
+    return len(top_a & top_b) / len(union) if union else 0.0
+
+
+def token_saliency(model, tokenizer, text, target=None):
+    """Per-token gradient saliency ``s_i = ‖∂P(y|x)/∂E_i‖₂`` via Captum (optional).
+    Requires ``pip install fairscope[nlp]``. Returns ``{token: saliency}``."""
+    try:
+        import captum  # noqa: F401  (captum depends on torch; one import gates the extra)
+    except ImportError as exc:
+        raise ImportError(
+            "token_saliency requires the optional dependency: pip install fairscope[nlp]"
+        ) from exc
+    return _captum_token_saliency(model, tokenizer, text, target)  # pragma: no cover
+
+
+def _captum_token_saliency(model, tokenizer, text, target):  # pragma: no cover - needs nlp extra
+    from captum.attr import Saliency
+
+    enc = tokenizer(text, return_tensors="pt")
+    embeddings = model.get_input_embeddings()(enc["input_ids"])
+    embeddings.requires_grad_(True)
+
+    def forward(emb):
+        return model(inputs_embeds=emb, attention_mask=enc["attention_mask"]).logits.softmax(-1)
+
+    tgt = target if target is not None else int(forward(embeddings).argmax())
+    grads = Saliency(forward).attribute(embeddings, target=tgt, abs=False)
+    scores = grads.norm(dim=-1).squeeze(0).detach().numpy()
+    tokens = tokenizer.convert_ids_to_tokens(enc["input_ids"].squeeze(0))
+    agg = {}
+    for tok, score in zip(tokens, scores):
+        agg[tok] = max(agg.get(tok, 0.0), float(score))
+    return agg

fairscope/nlp/cross_platform.py

@@ -0,0 +1,178 @@
+"""The five-axis Cross-Platform Fairness Evaluation (CPFE) protocol (Pall & Yadav).
+
+Axes 1-4 run on precomputed per-platform outputs (no torch); attribution stability
+(axis 5) is provided separately via ``fairscope.nlp.attribution`` behind the optional
+``fairscope[nlp]`` extra.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from ..core import bonferroni
+from .metrics import (
+    macro_auc,
+    macro_f1,
+    multiclass_ece,
+    per_class_disparate_impact,
+    per_class_equalized_odds,
+)
+from .significance import bootstrap_macro_auc_test
+
+# Reference bands EXPLICITLY STATED in the CPFE paper (descriptive diagnostic, NOT
+# regulatory standards). P4 declines to set a delta-AUC decision threshold (Section 6.6),
+# so that one is a constructor argument with an illustrative default instead.
+DI_FOUR_FIFTHS = 0.80  # P4 Sec 4.4: DI < 0.80 violates the four-fifths rule
+DI_SEVERE = 0.50  # P4 Sec 4.4: DI < 0.50 is a severe disparity
+ECE_WELL_CALIBRATED = 0.10  # P4 Suppl. Fig. S2: ECE < 0.10 well-calibrated
+ECE_MODERATE = 0.20  # P4 Suppl. Fig. S2: ECE > 0.20 moderate miscalibration
+JACCARD_INSTABILITY = 0.20  # P4 Suppl. Fig. S7: J < 0.20 attribution instability
+
+
+class CPFEProtocol:
+    """Run the CPFE five-axis evaluation over precomputed per-platform outputs.
+
+    Parameters
+    ----------
+    platform_data : dict ``{name: {"y_true": array, "probs": (n, n_classes) array}}``.
+    reference : the within-platform name (e.g. the training platform).
+    n_classes : number of classes.
+    delta_auc_pct_max : ILLUSTRATIVE macro-AUC-drop screening limit (percent) used by
+        ``CPFEReport.deployment_readiness``. NOT a published cutoff: P4 Section 6.6 declines
+        to set one (observed drops were 28.6-39.5%); the default echoes that ">30%" magnitude
+        and is labelled illustrative everywhere it surfaces.
+    """
+
+    def __init__(
+        self,
+        platform_data,
+        reference,
+        n_classes,
+        *,
+        n_bins=10,
+        alpha=0.05,
+        n_boot=2000,
+        delta_auc_pct_max=30.0,
+    ):
+        if reference not in platform_data:
+            raise ValueError(f"reference platform {reference!r} not in platform_data")
+        self.platform_data = platform_data
+        self.reference = reference
+        self.n_classes = n_classes
+        self.n_bins = n_bins
+        self.alpha = alpha
+        self.n_boot = n_boot
+        self.delta_auc_pct_max = delta_auc_pct_max
+
+    def run(self) -> CPFEReport:
+        ref = self.platform_data[self.reference]
+        ref_auc = macro_auc(ref["y_true"], ref["probs"])
+        others = [p for p in self.platform_data if p != self.reference]
+
+        performance = {}
+        for name, d in self.platform_data.items():
+            a = macro_auc(d["y_true"], d["probs"])
+            performance[name] = {
+                "macro_auc": a,
+                "macro_f1": macro_f1(d["y_true"], d["probs"]),
+                "ece": multiclass_ece(d["y_true"], d["probs"], self.n_bins),
+                "delta_auc_pct": 100.0 * (a - ref_auc) / ref_auc,
+            }
+
+        significance, equity, raw_p = {}, {}, []
+        for name in others:
+            d = self.platform_data[name]
+            sig = bootstrap_macro_auc_test(
+                ref["y_true"],
+                ref["probs"],
+                d["y_true"],
+                d["probs"],
+                n_boot=self.n_boot,
+                random_state=0,
+            )
+            significance[name] = sig
+            raw_p.append(sig["p_value"])
+            equity[name] = {
+                "disparate_impact": per_class_disparate_impact(
+                    ref["probs"], d["probs"], self.n_classes
+                ),
+                "equalized_odds": per_class_equalized_odds(
+                    ref["y_true"], ref["probs"], d["y_true"], d["probs"], self.n_classes
+                ),
+            }
+        if raw_p:
+            adj = bonferroni(np.array(raw_p), alpha=self.alpha)
+            for name, padj, rej in zip(others, adj["adjusted"], adj["reject"]):
+                significance[name]["p_adjusted"] = float(padj)
+                significance[name]["reject"] = bool(rej)
+
+        return CPFEReport(performance, significance, equity, self.reference, self.delta_auc_pct_max)
+
+
+class CPFEReport:
+    """Holds the five-axis results and renders tables and a deployment-readiness diagnostic."""
+
+    def __init__(self, performance, significance, equity, reference, delta_auc_pct_max):
+        self.performance = performance
+        self.significance = significance
+        self.equity = equity
+        self.reference = reference
+        self.delta_auc_pct_max = delta_auc_pct_max
+
+    def to_dataframe(self) -> pd.DataFrame:
+        return pd.DataFrame([{"platform": name, **m} for name, m in self.performance.items()])
+
+    def deployment_readiness(self):
+        """Structured per-axis, per-platform screening DIAGNOSTIC -- NOT a deployment
+        decision. Following the CPFE paper (Sections 6.5-6.6), cross-platform degradation
+        is an informative diagnostic, not definitive evidence of bias.
+
+        Thresholds: calibration uses P4's stated ECE bands (Suppl. Fig. S2); equity uses
+        P4's four-fifths rule; discrimination uses an ILLUSTRATIVE ``delta_auc_pct_max``
+        (P4 Section 6.6 declines to set a published cutoff). Returns
+        ``{platform: {"ready": bool, "axes": {axis: {pass, value, threshold, source, reason}}}}``.
+        """
+        verdict = {}
+        for name, perf in self.performance.items():
+            if name == self.reference:
+                continue
+            drop = -perf["delta_auc_pct"]
+            ece = perf["ece"]
+            di = self.equity.get(name, {}).get("disparate_impact", {})
+            violations = sorted(c for c, v in di.items() if v < DI_FOUR_FIFTHS)
+            severe = sorted(c for c, v in di.items() if v < DI_SEVERE)
+            if violations:
+                equity_reason = (
+                    f"four-fifths violations (DI<{DI_FOUR_FIFTHS}) for classes "
+                    f"{violations}; severe (<{DI_SEVERE}) {severe}"
+                )
+            else:
+                equity_reason = "no four-fifths violations"
+            axes = {
+                "discrimination": {
+                    "pass": drop <= self.delta_auc_pct_max,
+                    "value": drop,
+                    "threshold": self.delta_auc_pct_max,
+                    "source": "illustrative (not a published cutoff; P4 Section 6.6)",
+                    "reason": f"macro-AUC drop {drop:.1f}% vs reference "
+                    f"(illustrative limit {self.delta_auc_pct_max:.0f}%)",
+                },
+                "calibration": {
+                    "pass": ece < ECE_WELL_CALIBRATED,
+                    "value": ece,
+                    "threshold": ECE_WELL_CALIBRATED,
+                    "source": "P4 Suppl. Fig. S2",
+                    "reason": f"ECE {ece:.3f} (well-calibrated < {ECE_WELL_CALIBRATED}; "
+                    f"moderate miscalibration > {ECE_MODERATE})",
+                },
+                "equity": {
+                    "pass": len(violations) == 0,
+                    "value": {"violations": violations, "severe": severe},
+                    "threshold": DI_FOUR_FIFTHS,
+                    "source": "P4 four-fifths rule (Sec 4.4)",
+                    "reason": equity_reason,
+                },
+            }
+            verdict[name] = {"ready": all(a["pass"] for a in axes.values()), "axes": axes}
+        return verdict

fairscope/nlp/metrics.py

@@ -0,0 +1,87 @@
+"""Multiclass metrics for the CPFE protocol (axes 1, 2, 4 primitives).
+
+Pure functions that reuse ``fairscope.core`` where the definition is shared. The
+confidence-accuracy ECE follows the formula in the CPFE paper (Pall & Yadav), and is
+distinct from ``core.expected_calibration_error`` (binary prob-vs-frequency calibration).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from sklearn.metrics import f1_score, roc_auc_score
+
+from ..core import disparate_impact, equalized_odds_difference
+
+
+def _check_probs(y_true, probs):
+    y = np.asarray(y_true)
+    p = np.asarray(probs, dtype=float)
+    if p.ndim != 2:
+        raise ValueError("probs must be a 2-D array of shape (n_samples, n_classes)")
+    if len(y) != p.shape[0]:
+        raise ValueError("y_true and probs must have the same number of rows")
+    if np.any(np.isnan(p)):
+        raise ValueError("probs contain NaN")
+    return y, p
+
+
+def macro_auc(y_true, probs):
+    """Macro one-vs-rest AUC. Requires every class present in ``y_true``."""
+    y, p = _check_probs(y_true, probs)
+    return float(roc_auc_score(y, p, multi_class="ovr", average="macro"))
+
+
+def macro_f1(y_true, probs):
+    """Macro F1 of the argmax predictions."""
+    y, p = _check_probs(y_true, probs)
+    return float(f1_score(y, p.argmax(axis=1), average="macro"))
+
+
+def multiclass_ece(y_true, probs, n_bins=10):
+    """Confidence-accuracy Expected Calibration Error (Guo et al. 2017; CPFE paper):
+    ``ECE = sum_m (|B_m|/n) * |acc(B_m) - conf(B_m)|`` with ``conf = max prob`` and
+    ``acc = top-1 correct``."""
+    y, p = _check_probs(y_true, probs)
+    conf = p.max(axis=1)
+    correct = (p.argmax(axis=1) == y).astype(float)
+    edges = np.linspace(0.0, 1.0, n_bins + 1)
+    idx = np.digitize(conf, edges[1:-1])
+    n = len(y)
+    ece = 0.0
+    for b in range(n_bins):
+        m = idx == b
+        if np.any(m):
+            ece += (m.sum() / n) * abs(correct[m].mean() - conf[m].mean())
+    return float(ece)
+
+
+def per_class_disparate_impact(probs_a, probs_b, n_classes):
+    """Symmetric DI per class between two platforms, reusing ``core.disparate_impact`` with
+    the class binarized (``pred == c``) and platform as the two-group label."""
+    pa = np.asarray(probs_a).argmax(axis=1)
+    pb = np.asarray(probs_b).argmax(axis=1)
+    groups = np.array(["a"] * len(pa) + ["b"] * len(pb))
+    out = {}
+    for c in range(n_classes):
+        ypred = np.concatenate([(pa == c).astype(int), (pb == c).astype(int)])
+        out[c] = disparate_impact(ypred, groups, "a", "b")
+    return out
+
+
+def per_class_equalized_odds(y_a, probs_a, y_b, probs_b, n_classes):
+    """EOD per class between two platforms (``|TPR_c(A) - TPR_c(B)|``), reusing
+    ``core.equalized_odds_difference``. A class with no positive labels in a platform is
+    returned as ``None`` (TPR undefined)."""
+    pa = np.asarray(probs_a).argmax(axis=1)
+    pb = np.asarray(probs_b).argmax(axis=1)
+    ya, yb = np.asarray(y_a), np.asarray(y_b)
+    groups = np.array(["a"] * len(ya) + ["b"] * len(yb))
+    out = {}
+    for c in range(n_classes):
+        yt = np.concatenate([(ya == c).astype(int), (yb == c).astype(int)])
+        yp = np.concatenate([(pa == c).astype(int), (pb == c).astype(int)])
+        try:
+            out[c] = equalized_odds_difference(yt, yp, groups, "a", "b")
+        except ValueError:
+            out[c] = None  # a platform has no examples of class c
+    return out

fairscope/nlp/significance.py

@@ -0,0 +1,51 @@
+"""Axis 3 of CPFE: unpaired bootstrap comparison of macro one-vs-rest AUC across two
+platforms (independent test sets), as in the CPFE paper (stratified bootstrap standard
+errors, B = 2000 by default, combined for a normal-approximation z-test).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy import stats
+
+from .metrics import macro_auc
+
+
+def _bootstrap_se(y, probs, n_boot, rng):
+    """Stratified (by class) bootstrap standard error of the macro AUC."""
+    y = np.asarray(y)
+    probs = np.asarray(probs, dtype=float)
+    class_idx = [np.flatnonzero(y == c) for c in np.unique(y)]
+    aucs = np.empty(n_boot)
+    for i in range(n_boot):
+        idx = np.concatenate([rng.choice(ci, size=ci.size, replace=True) for ci in class_idx])
+        aucs[i] = macro_auc(y[idx], probs[idx])
+    return float(aucs.std(ddof=1))
+
+
+def bootstrap_macro_auc_test(y_a, probs_a, y_b, probs_b, n_boot=2000, random_state=None):
+    """Compare macro AUC across two platforms (independent test sets).
+
+    Each platform's macro-AUC standard error is estimated by a class-stratified bootstrap;
+    the errors are combined for an unpaired z-test. Returns a dict: auc_a, auc_b, delta,
+    se, z, p_value, n_boot.
+    """
+    rng = np.random.default_rng(random_state)
+    probs_a = np.asarray(probs_a, dtype=float)
+    probs_b = np.asarray(probs_b, dtype=float)
+    auc_a = macro_auc(y_a, probs_a)
+    auc_b = macro_auc(y_b, probs_b)
+    se_a = _bootstrap_se(y_a, probs_a, n_boot, rng)
+    se_b = _bootstrap_se(y_b, probs_b, n_boot, rng)
+    delta = auc_a - auc_b
+    se = float(np.sqrt(se_a**2 + se_b**2))
+    z = delta / se if se > 0 else 0.0
+    return {
+        "auc_a": auc_a,
+        "auc_b": auc_b,
+        "delta": delta,
+        "se": se,
+        "z": float(z),
+        "p_value": float(2.0 * stats.norm.sf(abs(z))),
+        "n_boot": n_boot,
+    }

fairscope-0.3.0.dist-info/METADATA

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: fairscope
+Version: 0.3.0
+Summary: Subgroup-stratified, calibration-aware fairness auditing for ML models, grounded in peer-reviewed methods.
+Project-URL: Homepage, https://github.com/Rajveer-code/fairscope
+Project-URL: Repository, https://github.com/Rajveer-code/fairscope
+Project-URL: Issues, https://github.com/Rajveer-code/fairscope/issues
+Author: Rajveer Singh Pall
+License-Expression: MIT
+License-File: LICENSE
+Keywords: auc,calibration,delong,fairness,machine-learning,model-auditing,subgroup-analysis
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: matplotlib>=3.6
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=1.5
+Requires-Dist: scikit-learn>=1.1
+Requires-Dist: scipy>=1.9
+Provides-Extra: all
+Requires-Dist: captum>=0.6; extra == 'all'
+Requires-Dist: econml>=0.15; extra == 'all'
+Requires-Dist: shap>=0.42; extra == 'all'
+Requires-Dist: torch>=2.0; extra == 'all'
+Requires-Dist: transformers>=4.30; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: black>=24.0; extra == 'dev'
+Requires-Dist: nbmake>=1.5; 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'
+Requires-Dist: statsmodels>=0.14; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.4; extra == 'docs'
+Requires-Dist: mkdocs>=1.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
+Provides-Extra: lending
+Requires-Dist: econml>=0.15; extra == 'lending'
+Provides-Extra: nlp
+Requires-Dist: captum>=0.6; extra == 'nlp'
+Requires-Dist: torch>=2.0; extra == 'nlp'
+Requires-Dist: transformers>=4.30; extra == 'nlp'
+Provides-Extra: shap
+Requires-Dist: shap>=0.42; extra == 'shap'
+Description-Content-Type: text/markdown
+
+# fairscope
+
+[![CI](https://github.com/Rajveer-code/fairscope/actions/workflows/ci.yml/badge.svg)](https://github.com/Rajveer-code/fairscope/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.9%E2%80%933.12-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-live-brightgreen.svg)](https://rajveer-code.github.io/fairscope/)
+
+**Subgroup-stratified, calibration-aware fairness auditing for machine-learning models — grounded in peer-reviewed methods.**
+
+📖 **Documentation:** <https://rajveer-code.github.io/fairscope/>
+
+`fairscope` packages statistical machinery that mainstream fairness toolkits do not expose as
+first-class, subgroup-stratified functions, and adds one novel protocol on top:
+
+- **DeLong confidence intervals** for per-subgroup AUC (fast midrank algorithm).
+- **Per-subgroup Expected/Maximum Calibration Error** with reliability diagrams.
+- **Significance testing** of subgroup performance gaps (paired/unpaired DeLong, stratified
+  bootstrap) with **Bonferroni / Benjamini–Hochberg** correction.
+- A subgroup-stratified **interface to standard recalibration** — temperature scaling
+  (Guo et al. 2017) and isotonic regression (Zadrozny & Elkan 2002), with pre/post-ECE.
+- A novel five-axis **Cross-Platform Fairness Evaluation (CPFE)** protocol.
+- One-call **domain audits**: `healthcare`, `lending`, `federated`.
+
+Only the CPFE protocol is presented as novel. Every other function ports a documented method
+and cites its source; the recalibration methods are standard, and the contribution there is the
+per-subgroup interface and pre/post-ECE reporting.
+
+> **Status — v0.3.0.** All five modules (`core`, `healthcare`, `nlp`/CPFE, `federated`,
+> `lending`) are implemented, tested, and released. 100% line coverage on the statistical core;
+> CI green across Python 3.9–3.12. See [`docs/DESIGN.md`](docs/DESIGN.md) for methods and design.
+
+## Install
+
+```bash
+pip install fairscope
+```
+
+Releases are uploaded to PyPI by the maintainer; if a version isn't available there yet,
+install from source or from the [release assets](https://github.com/Rajveer-code/fairscope/releases):
+
+```bash
+git clone https://github.com/Rajveer-code/fairscope
+cd fairscope
+pip install -e ".[dev]"
+pytest
+```
+
+The base install is light (NumPy, SciPy, scikit-learn, pandas, matplotlib). Optional extras:
+`fairscope[nlp]` (torch, transformers, captum), `fairscope[lending]` (econml),
+`fairscope[shap]`, `fairscope[docs]`.
+
+## Quickstart
+
+```python
+from fairscope.healthcare import HealthcareFairnessAudit
+
+# y_true : binary outcomes
+# y_score: the model's positive-class probabilities
+# age_group: a protected attribute, aligned row-for-row
+report = HealthcareFairnessAudit.from_scores(
+    y_true, y_score, {"age_group": age_group}
+).run()
+
+print(report.summary())     # per-subgroup AUC (DeLong CI), ECE, Brier, F1; flags the largest gap
+report.to_dataframe()       # tidy per-subgroup table
+report.plot_auc_forest()    # forest plot of per-subgroup AUC with DeLong intervals
+```
+
+Every domain is also reachable through one dispatcher,
+`FairnessAudit(model, domain=...)`, with `domain` in `{"healthcare", "nlp", "federated",
+"lending"}`. A runnable end-to-end example on a committed synthetic fixture is in the
+[getting-started guide](https://rajveer-code.github.io/fairscope/getting-started/) and in
+[`notebooks/`](notebooks/).
+
+## Modules
+
+| Module | Purpose | Status |
+|---|---|---|
+| `core/` | DeLong CI, bootstrap-AUC test, ECE/MCE + reliability, multiple-testing correction, subgroup metrics | ✅ shipped |
+| `healthcare/` | one-call clinical fairness audit + report (tables, forest & reliability plots, PDF, optional SHAP) | ✅ shipped |
+| `nlp/` | CPFE five-axis cross-platform protocol (centerpiece) + Captum attribution stability | ✅ shipped |
+| `federated/` | per-node DeLong + cross-node disparity + per-node recalibration | ✅ shipped |
+| `lending/` | annual approval-gap + subgroup CATE (Causal Forest DML) | ✅ shipped |
+
+Plotting (forest plots, reliability diagrams) currently lives in the domain reports.
+`lending`'s CATE estimation needs the optional `fairscope[lending]` extra (`econml`). The
+`federated` module audits per-node predictions only — it performs no training and provides no
+privacy guarantee.
+
+## How it differs from AIF360 / Fairlearn
+
+`fairscope` is complementary to AIF360 and Fairlearn, not a replacement: those toolkits do bias
+*mitigation*; `fairscope` does uncertainty-aware *measurement*. The table below was verified by
+inspecting the installed public APIs of **AIF360 0.6.1** and **Fairlearn 0.14.0** (checked
+2026-06; re-confirm if versions change).
+
+| Capability | AIF360 | Fairlearn | fairscope |
+|---|:---:|:---:|:---:|
+| Per-subgroup AUC confidence interval (DeLong) | no | no\* | yes |
+| Per-subgroup Expected Calibration Error | no | no | yes |
+| Subgroup significance test + multiple-comparison correction | no | no | yes |
+| Subgroup-stratified recalibration (temperature / isotonic) | partial† | no | yes |
+| Cross-platform five-axis protocol (CPFE) | no | no | yes (novel) |
+| Per-node / federated audit | no | no | yes |
+| Bias-mitigation algorithms | yes | yes | out of scope |
+
+\* Fairlearn's `MetricFrame` computes per-subgroup AUC *point estimates* (e.g.
+`roc_auc_score_group_min`), but provides no analytic (DeLong) confidence interval.
+† AIF360 ships `CalibratedEqOddsPostprocessing` (calibration-aware equalized-odds
+postprocessing), not a general per-subgroup temperature/isotonic recalibration interface.
+
+**Closest related work — `meval`** (Sutariya & Petersen, 2025,
+[arXiv:2512.17409](https://arxiv.org/abs/2512.17409)): a statistical toolbox for stratified,
+fine-grained model-performance analysis that *also* provides subgroup metric uncertainty and
+multiple-comparison corrections (with a medical-imaging focus). `fairscope` overlaps with it on
+uncertainty + significance; what `fairscope` adds is the specific DeLong AUC intervals, the
+per-subgroup calibration **and recalibration** interface, the five-axis cross-platform CPFE
+protocol, and one-call domain audits (healthcare / lending / federated).
+
+## Engineering
+
+- **Test-driven**, with regression tests anchored to authoritative reference values where they
+  exist (DeLong's worked example; `statsmodels` multiple-testing routines).
+- **100% line coverage** on the statistical core; CI runs pytest + coverage, ruff, and black
+  across Python 3.9–3.12, and executes the replication notebooks via `nbmake`.
+- Full type hints, NumPy-style docstrings with runnable examples, and explicit input validation
+  (an AUC on a single-class subgroup raises rather than returning a meaningless value).
+- Committed fixtures are **small, synthetic, and labelled as such**; no datasets or trained
+  models are bundled.
+
+## Grounded in published research
+
+`fairscope` ports methods from the author's peer-reviewed and under-review papers; it invents no
+new mathematics. Each function cites its source. Full venues and identifiers are in
+[`CITATION.cff`](CITATION.cff).
+
+- Diabetes risk prediction with external validation + fairness analysis (XGBoost, NHANES→BRFSS) — IEEE CIPHER, 2026.
+- A five-axis Cross-Platform Fairness Evaluation for mental-health NLP — under review.
+- Privacy-preserving federated learning for diabetes risk across heterogeneous nodes — under review.
+- Heterogeneous racial effects in mortgage approval (Causal Forest Double Machine Learning, HMDA) — under review.
+- Racial disparities in mortgage lending (RDD / DiD / decomposition, HMDA) — under review.
+
+## Citation
+
+If you use `fairscope`, please cite it via [`CITATION.cff`](CITATION.cff).
+
+## License
+
+[MIT](LICENSE) © 2026 Rajveer Singh Pall · ORCID [0009-0001-6762-6134](https://orcid.org/0009-0001-6762-6134)

fairscope-0.3.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+fairscope/__init__.py,sha256=aZb7kP8vyFmMZqXe7MdhXI5TuszHSXJNK01-m9KFJSI,1979
+fairscope/core/__init__.py,sha256=BqMc2kIC0Kjm2qvm7lqKJ7cLKNLDcdXeEQ53hN0t9Dw,1420
+fairscope/core/_utils.py,sha256=K7NaqaWXfoZRtIc0xvDH5q9zRVTSVi1Q1SWq4yLAbTE,1368
+fairscope/core/bootstrap.py,sha256=tETKVrGRNlkktGza0ITnVLh6vJIBDAh95OqwZ5fK2eE,2244
+fairscope/core/calibration.py,sha256=FyFyVjGZ0EzjKDvcO_B9Y3aSXGwA9bG6nHn4s-Touw4,6188
+fairscope/core/correction.py,sha256=3t3lIfThiP9nTIRiFgPJh2tNS3AAHMxMVMvcrPCHxGo,1443
+fairscope/core/delong.py,sha256=9ZNh_98Zre4oHYYQaUxT5ydIrrg-2SIE0wJkNH81Ed0,5044
+fairscope/core/metrics.py,sha256=NOIlTpzsTuVYbCPPOsfG2NdmtNn1DAaO9ZyqVlNKS_4,3655
+fairscope/federated/__init__.py,sha256=3ieUZDgobc2OKjBPvnKittDuxRc2ZSDwL7SR1hSkFxM,336
+fairscope/federated/audit.py,sha256=_MYnn_I9dBvVqZMHjxaJhHMktNWUS69XK0pVozeeCd0,8235
+fairscope/healthcare/__init__.py,sha256=rmFIfUt_Qao0kZ0b2i7pNSCSD0RKIkxT3n1oN3CnwKc,179
+fairscope/healthcare/audit.py,sha256=q84h7mpfgwwfczbuOWpBwFTZzJsq7tXWSsetqtCw5dc,9180
+fairscope/lending/__init__.py,sha256=nS1UJjpO12mDduDrz5pwPsSDeFZMx_GLkHM2wBwL7Uc,195
+fairscope/lending/audit.py,sha256=QEHHB3tdSG2ULVAVFOuKzFlMX0v-1MWuWyzJQBtLDGc,5989
+fairscope/nlp/__init__.py,sha256=OmFoKumKjdCOjsvKOaSgCUyWuF-JEILmA0tC3Bj9i50,798
+fairscope/nlp/attribution.py,sha256=7cGLZ2b5lbezvFr14B81uVpHf_2Nno_4YUpqSk6Ky6I,2292
+fairscope/nlp/cross_platform.py,sha256=SaBgu69GLhKbBaZCq9S8tvXZphCORpbrvTvAxz0Xdcc,7507
+fairscope/nlp/metrics.py,sha256=E5BJgdp6ooQbSsbxRgqLCyeHK0BOQsSw2GlkifLH794,3405
+fairscope/nlp/significance.py,sha256=TXf2LgyLMvtan3xaOCbA6j27aHH6ejxeAGIbJ6Pd6oE,1859
+fairscope-0.3.0.dist-info/METADATA,sha256=MYgXmLdl_jYdYbaQZKrroRQ3CwfHDusld4HIBIBH8-Q,10074
+fairscope-0.3.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+fairscope-0.3.0.dist-info/licenses/LICENSE,sha256=33pRQQTdA8whKltAeAn7UzoxgIS-y3hQWQ-ZcxB0Pss,1075
+fairscope-0.3.0.dist-info/RECORD,,

fairscope-0.3.0.dist-info/WHEEL

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

fairscope-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rajveer Singh Pall
+
+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.