[shap-waterfall] SHAP Waterfall Plot for Feature Attribution

[MarkusNeusinger]

Description

A waterfall-style chart showing how each feature contributes to pushing a model prediction from a base value (expected output) to the final predicted value. Bars extend left (negative SHAP value) or right (positive SHAP value), stacking cumulatively. This is a core ML explainability visualization complementing the existing SHAP summary plot.

Applications

• Explaining individual predictions in credit scoring models
• Debugging unexpected model outputs in healthcare ML
• Communicating feature impact to non-technical stakeholders
• Regulatory compliance (model explainability requirements)

Data

• feature (str) — feature names
• shap_value (float) — SHAP contribution per feature
• base_value (float) — expected model output
• final_value (float) — actual prediction
• Size: 10–20 features typical

Notes

• Features ordered by absolute SHAP value magnitude
• Cumulative bar segments from base_value to final_value
• Color: red for positive, blue for negative contributions
• Show base value and final prediction as reference lines

[claude]

✅ Spec ID: shap-waterfall

Rationale: Follows the existing shap-summary naming convention; "waterfall" describes the cumulative bar-segment visualization of individual feature attributions from base value to final prediction.

Related specs: shap-summary (distribution-level view, complementary), waterfall-basic (generic financial waterfall, different domain/data).

Add label approved to begin generation.

[github-actions]

✅ Specification Ready: shap-waterfall

PR: #5253

---

specification.md

shap-waterfall: SHAP Waterfall Plot for Feature Attribution

Description

A waterfall-style chart showing how each feature contributes to pushing a model prediction from a base value (expected model output) to the final predicted value. Horizontal bar segments extend right for positive SHAP values and left for negative SHAP values, stacking cumulatively so the viewer can trace the path from baseline to prediction. This is a core ML explainability visualization for explaining individual predictions, complementing the SHAP summary plot which shows feature effects across many samples.

Applications

• Explaining individual predictions in credit scoring models to auditors or loan applicants
• Debugging unexpected model outputs in healthcare ML by identifying which features drove the prediction
• Communicating feature impact to non-technical stakeholders in business decision-making
• Satisfying regulatory compliance requirements for model explainability (e.g., GDPR right to explanation)

Data

• feature (str) - Feature names (e.g., "Age", "Income", "Credit Score")
• shap_value (float) - SHAP contribution value per feature (positive pushes prediction up, negative pushes down)
• base_value (float) - Expected model output (mean prediction across training data), single scalar
• final_value (float) - Actual model prediction for this instance (base_value + sum of SHAP values), single scalar
• Size: 10-20 features typical; show top features by absolute SHAP magnitude

Notes

• Order features by absolute SHAP value magnitude (largest contribution at top)
• Cumulative bar segments flow from base_value to final_value
• Color bars red/pink for positive SHAP contributions and blue for negative contributions
• Display base value and final prediction value as labeled reference lines or annotations
• Show numeric SHAP values on or beside each bar segment
• Use a horizontal layout with feature names on the y-axis for readability
• Consider a connector line between segments to emphasize the cumulative flow

---

Next: Add approved label to merge this specification to main.

---

🤖 spec-create workflow

[github-actions]

🚀 Specification Merged!

Specification: shap-waterfall
PR: #5253 (merged)

The specification is now in main and synced to PostgreSQL.

---

Next: Add generate:{library} labels to start generating implementations.

Available libraries: matplotlib, seaborn, plotly, bokeh, altair, plotnine, pygal, highcharts, letsplot

Or use workflow dispatch for bulk operations.

---

🤖 spec-create workflow