Skip to content

triadxai

TRIAD: three-channel attribution decomposition (Information / Density / Missingness) for credit-risk models.

triadxai answers: how much of this score rests on evidence, and how much on the model guessing? Every feature's contribution is split into three signed channels that sum back exactly:

  • I — Information: the part supported by training data,
  • D — Density / epistemic: the under-supported part — where the model guesses,
  • M — Missingness: the part routed through missing-value handling.

The identity I_j + D_j + M_j = f_j(x_j) holds per feature (C1), and channel totals reconcile exactly to the model score (C2). This separates "denied because of bad information" from "denied because we lack information" — aligned with the Reg B adverse-action reason-code taxonomy that distinguishes derogatory from insufficient-information reasons.

from triadxai import TriadExplainer, fit_lgbm_gam

result = fit_lgbm_gam(X_train, y_train)       # additive-constrained bagged LightGBM
expl = TriadExplainer(result)
exp = expl.explain(X_test)

exp.channels                    # long DataFrame: (instance, feature) x [I, D, M, w, oov]
exp.epistemic_score()           # ES, ES_signed, KR per instance
exp.reasons(k=4)                # ranked, group-tagged adverse-action reasons
exp.plot_waterfall(i=0)         # three-channel waterfall (D hatched)

Highlights

  • Exact additivity, guarded at runtime — channels sum to each feature's contribution and channel totals plus the intercept reproduce the raw score; explain re-checks the reconciliation on every call (channels and guarantees).
  • Two modes, one API — exact mode for additive models (fit_lgbm_gam boosters, InterpretML EBM) and approximate mode for any LightGBM booster via native TreeSHAP (how it works, approximate mode).
  • A principled support weight — per-bin empirical-Bayes shrinkage w = τ²/(τ²+v) decides how much of a contribution counts as information, with an auditable per-term parameter frame (shrinkage).
  • Epistemic variance from the data itself — bootstrap bag replicas supply the variance signal; EBMs contribute their native outer-bag SDs (epistemic variance).
  • Reg-B-style reason codes — Group A (derogatory, carried by I) versus Group B (insufficient information, carried by D + M), ranked and thresholded against noise (reason codes and waterfalls).
  • Validated on known ground truth — synthetic DGPs (density gap, MCAR/MAR/MNAR missingness, pure-noise feature, interactions) back a C1–C8 invariant suite run over both modes (tutorial).

Where to start

  1. Getting started — install and your first decomposition in five minutes.
  2. How it works — the full pipeline, from bin tensors to reconciled channels.
  3. Synthetic credit walkthrough — a runnable notebook: exact mode, epistemic scores, reason codes, waterfalls, density gap, approximate mode.

Project

Design decisions