Skip to content

Reason codes and waterfalls

The channels exist to answer an adverse-action question: was this applicant denied because of bad information or because of insufficient information? Reg B's reason-code taxonomy distinguishes the two, and TRIAD's channels map onto it directly.

Group A vs Group B

map_reasons (or TriadExplanation.reasons()) is a deterministic post-processor from one instance's channels to ranked reasons:

  • Group A — derogatory information, driven by the I channel: the evidence on file genuinely worsens the score.
  • Group B — insufficient information, driven by D + M, with a subtype: insufficient_missing when \(|M| \ge |D|\) (nothing on file), else insufficient_density (the value sits where training data is thin).

Candidates are ranked by absolute contribution and the top k (default 4) are emitted as ReasonCode records: feature, group, subtype, contribution, text.

Orientation

By default (orientation="higher_is_better") negative contributions count as adverse. When a higher score means higher risk — the usual credit-score-as-PD setup — pass orientation="lower_is_better" to flip the sign convention, as the synthetic credit walkthrough does.

Noise suppression

A Group B reason is only emitted when the epistemic part clears two thresholds (spec §8.3): \(|D + M| \ge \theta_{\text{abs}}\) (default 0.05) and \(|D + M| \ge \theta_{\text{rel}} \cdot |f|\) (default 0.5). Tiny epistemic residue on a well-supported feature never becomes a customer-facing reason.

Wording stays with compliance

The default templates ("Unfavorable information: {feature}", "No or limited information on file: {feature}", "Insufficient information to evaluate: {feature}") are placeholders. A dictionary argument maps features to approved reason text; legally operative wording stays with the lender's compliance function.

The three-channel waterfall

plot_waterfall (optional viz extra) renders one instance's decomposition as stacked bars per feature, ordered by absolute total contribution:

  • I segments solid,
  • D segments hatched and translucent — the direction of an under-supported contribution is the model's guess,
  • M segments gray,
  • features outside the training view starred, and approximate-mode plots badged.

A thin-file applicant's score is visibly carried by the M segment; a derogatory applicant's by solid I.