feat: add waterfall plot for local explanations (#453) by laasyapriya2007 · Pull Request #698 · interpretml/interpret

laasyapriya2007 · 2026-10-23T10:06:42Z

Description

This PR resolves #453 by adding support for waterfall plots in local explanations.

Waterfall charts are one of the most effective and widely-used ways to visualize local additive feature attributions (similar to SHAP waterfall plots), clearly illustrating how the prediction is obtained starting from the base value (Intercept), through individual feature score contributions, to the final model Prediction.

Key Changes

plot_waterfall in interpret.visual.plot:
- Generates Plotly go.Waterfall charts for local explanation data dictionaries.
- Starts with Intercept as the baseline, cascades each sorted feature score contribution, and terminates with a total bar for Prediction.
- Supports both horizontal (orientation="h", default) and vertical (orientation="v") orientations.
- Supports configurable top_n (defaults to 15), automatically aggregating the remaining lower-magnitude terms into an "Other features" step.
- Handles regression, binary classification, and multiclass models (allowing class_idx selection).
Local Explanation API (visualize and show):
- FeatureValueExplanation.visualize(key, plot_type="waterfall")
- EBMExplanation.visualize(key, plot_type="waterfall")
- LinearExplanation.visualize(key, plot_type="waterfall")
- Compatible with interpret.show(local_exp, key=0, plot_type="waterfall") and inline / preserve providers.
Unit Tests:
- Added comprehensive tests in tests/visual/test_plot.py covering basic waterfall generation, vertical layout, top_n grouping, multiclass support, and model explanation visualization.

How to Test

import numpy as np
from interpret.glassbox import ExplainableBoostingRegressor

X = np.random.randn(100, 3)
y = 2.0 * X[:, 0] - 1.5 * X[:, 1] + 5.0

ebm = ExplainableBoostingRegressor(max_rounds=5, outer_bags=1)
ebm.fit(X, y)
local_exp = ebm.explain_local(X[:2], y[:2])

# Render waterfall plot
fig = local_exp.visualize(0, plot_type="waterfall")
fig.show()

Add plot_waterfall in interpret.visual.plot and support plot_type='waterfall' in local explanation visualize() and show(). - Implements plot_waterfall to visualize instance score breakdown from intercept to final prediction. - Supports both horizontal and vertical orientations and configurable top_n with remaining features aggregation. - Extends FeatureValueExplanation, EBMExplanation, and LinearExplanation visualize() to support plot_type='waterfall'. - Adds unit tests for regression, binary, and multiclass waterfall visualizations. Signed-off-by: Laasya Priya <laasyapriya1234@gmail.com>

for more information, see https://pre-commit.ci

codecov · 2026-10-23T10:35:59Z

Codecov Report

❌ Patch coverage is 94.25287% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 67.94%. Comparing base (4a492be) to head (2824eb9).

Files with missing lines	Patch %	Lines
python/interpret-core/interpret/visual/plot.py	94.11%	4 Missing ⚠️
python/interpret-core/interpret/glassbox/_ebm.py	87.50%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #698      +/-   ##
==========================================
+ Coverage   67.80%   67.94%   +0.13%     
==========================================
  Files          77       77              
  Lines       11893    11969      +76     
==========================================
+ Hits         8064     8132      +68     
- Misses       3829     3837       +8

Flag	Coverage Δ
bdist_linux_311_python	`67.71% <94.25%> (+0.17%)`	⬆️
bdist_linux_312_python	`?`
bdist_linux_313_python	`?`
bdist_linux_314_python	`67.62% <94.25%> (+0.17%)`	⬆️
bdist_linuxarm_311_python	`67.71% <94.25%> (+0.15%)`	⬆️
bdist_linuxarm_312_python	`?`
bdist_linuxarm_313_python	`?`
bdist_linuxarm_314_python	`67.62% <94.25%> (+0.15%)`	⬆️
bdist_mac_311_python	`67.85% <94.25%> (+0.17%)`	⬆️
bdist_mac_312_python	`?`
bdist_mac_313_python	`?`
bdist_mac_314_python	`67.76% <94.25%> (+0.17%)`	⬆️
bdist_win_311_python	`67.87% <94.25%> (+0.15%)`	⬆️
bdist_win_312_python	`?`
bdist_win_313_python	`?`
bdist_win_314_python	`67.80% <94.25%> (+0.18%)`	⬆️
sdist_linux_311_python	`?`
sdist_linux_312_python	`?`
sdist_linux_313_python	`?`
sdist_linux_314_python	`?`
sdist_linuxarm_311_python	`?`
sdist_linuxarm_312_python	`?`
sdist_linuxarm_313_python	`?`
sdist_linuxarm_314_python	`?`
sdist_mac_311_python	`?`
sdist_mac_312_python	`?`
sdist_mac_313_python	`?`
sdist_mac_314_python	`?`
sdist_win_311_python	`?`
sdist_win_312_python	`?`
sdist_win_313_python	`?`
sdist_win_314_python	`?`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Copilot

🟡 Changes recommended

Unresolved issues break existing preserve() calls, prevent waterfall rendering through the default show() path, and produce incomplete or inaccurate waterfall summaries and prediction totals.

5 open issues

What changed in this PR

Adds waterfall plots for local feature attributions, addressing #453 by showing the intercept, individual contributions, and their accumulated total within the existing explanation visualization API.

Changes:

Adds a Plotly waterfall helper with horizontal/vertical layouts, top-term grouping, and multiclass selection.
Extends explanation APIs and inline/preserve providers to accept waterfall selection.
Adds tests for plotting options and EBM/linear-model integration.

File	Description
`python/interpret-core/tests/visual/test_plot.py`	Tests waterfall layouts, grouping, class selection, and model integration.
`python/interpret-core/interpret/visual/plot.py`	Implements the waterfall plotting helper.
`python/interpret-core/interpret/visual/_inline.py`	Forwards visualization options to explanation rendering.
`python/interpret-core/interpret/provider/_visualize.py`	Adds plot selection to preserve and option forwarding to inline rendering.
`python/interpret-core/interpret/glassbox/_linear.py`	Forwards plot options from linear explanations.
`python/interpret-core/interpret/glassbox/_ebm.py`	Integrates waterfall rendering into EBM local explanations.
`python/interpret-core/interpret/core/templates.py`	Routes local waterfall requests to the plotting helper.

_{Review effort: Balanced}


        # Get visual object
-        visual = explanation.visualize(key=key)
+        visual = explanation.visualize(key=key, plot_type=plot_type)


        # Handle local instance graphs
        if self.explanation_type == "local":
+            if plot_type == "waterfall":
+                return plot_waterfall(data_dict, title=title, **kwargs)


            default_key=key,
            detected_envs=self.detected_envs,
            js_url=self.js_url,
+            **kwargs,


+    if top_n is not None and len(pairs) > top_n:
+        top_pairs = pairs[:top_n]
+        remaining_sum = sum(s for _, s in pairs[top_n:])
+        if abs(remaining_sum) > 1e-9:


+    step_names = [intercept_name] + [p[0] for p in pairs] + ["Prediction"]
+    step_scores = [intercept] + [p[1] for p in pairs] + [0.0]
+    measures = ["relative"] * (len(step_names) - 1) + ["total"]


laasyapriya2007 and others added 2 commits October 23, 2026 15:31

[pre-commit.ci] auto fixes from pre-commit.com hooks

71f3461

for more information, see https://pre-commit.ci

Merge branch 'main' into waterfall-local-explanation

d4be92f

paulbkoch requested a balanced review from Copilot October 27, 2026 08:03

Copilot started reviewing on behalf of paulbkoch October 27, 2026 08:10

View session

Copilot AI reviewed Oct 27, 2026

View reviewed changes

Merge branch 'main' into waterfall-local-explanation

2824eb9

Navigation Menu

Repository navigation

feat: add waterfall plot for local explanations (#453) - #698

feat: add waterfall plot for local explanations (#453)#698
laasyapriya2007 wants to merge 4 commits into
interpretml:mainfrom
laasyapriya2007:waterfall-local-explanation

laasyapriya2007 commented Oct 23, 2026

Uh oh!

codecov Bot commented Oct 23, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

Conversation

laasyapriya2007 commented Oct 23, 2026

Description

Key Changes

How to Test

Uh oh!

codecov Bot commented Oct 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

codecov Bot commented Oct 23, 2026 •

edited

Loading