From 4e933d2e9f31c84700c1e225695f103ed24b54ba Mon Sep 17 00:00:00 2001 From: Ayush Tiwari <147244828+Ayushdevo@users.noreply.github.com> Date: Thu, 12 Nov 2026 21:11:26 +0530 Subject: [PATCH 1/2] Avoid overflow in mean absolute feature attributions --- sentinelml/explainability/root_cause.py | 10 ++++++++-- tests/test_explainability_extreme_values.py | 16 ++++++++++++++++ 2 files changed, 24 insertions(+), 2 deletions(-) create mode 100644 tests/test_explainability_extreme_values.py diff --git a/sentinelml/explainability/root_cause.py b/sentinelml/explainability/root_cause.py index f3bfd8b..8510009 100644 --- a/sentinelml/explainability/root_cause.py +++ b/sentinelml/explainability/root_cause.py @@ -33,8 +33,14 @@ def rank_contributing_features( or values.shape[1] != len(self.feature_names) or not np.isfinite(values).all()): raise ValueError("SHAP attributions must be finite nonempty observation-by-feature matrices") - baseline_mean_abs = np.mean(np.abs(baseline_shap_values), axis=0) - degraded_mean_abs = np.mean(np.abs(degraded_shap_values), axis=0) + def mean_abs(values): + absolute = np.abs(values) + scale = np.max(absolute, axis=0) + normalized = np.divide(absolute, scale, out=np.zeros_like(absolute), where=scale != 0) + return np.mean(normalized, axis=0) * scale + + baseline_mean_abs = mean_abs(baseline_shap_values) + degraded_mean_abs = mean_abs(degraded_shap_values) shift_magnitudes = np.abs(degraded_mean_abs - baseline_mean_abs) top_indices = np.argsort(shift_magnitudes)[::-1][:top_k] diff --git a/tests/test_explainability_extreme_values.py b/tests/test_explainability_extreme_values.py new file mode 100644 index 0000000..aa2bd4b --- /dev/null +++ b/tests/test_explainability_extreme_values.py @@ -0,0 +1,16 @@ +import numpy as np +import pytest + +from sentinelml.explainability.root_cause import RootCauseExplainer + + +def test_attribution_ranking_handles_extreme_finite_values(): + explainer = RootCauseExplainer(["a", "b"]) + baseline = np.array([[1e308, 1e308], [1e308, 1e308]]) + degraded = np.array([[5e307, 1e308], [5e307, 1e308]]) + with np.errstate(over="raise", invalid="raise"): + result = explainer.rank_contributing_features(baseline, degraded, top_k=2) + assert result[0]["feature"] == "a" + assert result[0]["shift_magnitude"] == pytest.approx(5e307) + assert result[1]["shift_magnitude"] == 0.0 + assert all(np.isfinite(item["baseline_importance"]) for item in result) From ab253b23b0c869cae1fd5cc22ec179a030547f27 Mon Sep 17 00:00:00 2001 From: Ayush Tiwari <147244828+Ayushdevo@users.noreply.github.com> Date: Thu, 12 Nov 2026 21:13:56 +0530 Subject: [PATCH 2/2] Stabilize attribution percentages in monitoring reports --- src/root_cause.py | 56 ++++++++++--------------- tests/test_root_cause_extreme_values.py | 40 ++++++++++++++++++ 2 files changed, 63 insertions(+), 33 deletions(-) create mode 100644 tests/test_root_cause_extreme_values.py diff --git a/src/root_cause.py b/src/root_cause.py index 8ac38d3..5a12ab0 100644 --- a/src/root_cause.py +++ b/src/root_cause.py @@ -27,6 +27,22 @@ } + +def _mean_absolute_attributions(values): + absolute = np.abs(values) + scale = np.max(absolute, axis=0) + normalized = np.divide(absolute, scale, out=np.zeros_like(absolute), where=scale != 0) + return np.mean(normalized, axis=0) * scale + + +def _importance_percentages(values): + scale = np.max(values) + if scale == 0: + return np.zeros_like(values) + normalized = values / scale + return normalized / normalized.sum() * 100 + + def analyze_root_causes(): print("\nSENTINELML — ROOT CAUSE ANALYSIS") @@ -87,9 +103,7 @@ def analyze_root_causes(): # 2. Global feature importance # -------------------------------- - mean_abs_shap = np.abs( - shap_values - ).mean(axis=0) + mean_abs_shap = _mean_absolute_attributions(shap_values) importance = pd.DataFrame( { @@ -103,19 +117,10 @@ def analyze_root_causes(): ascending=False, ) - total_importance = ( - importance["mean_abs_shap"].sum() + importance["importance_percent"] = _importance_percentages( + importance["mean_abs_shap"].to_numpy() ) - if total_importance > 0: - importance["importance_percent"] = ( - importance["mean_abs_shap"] - / total_importance - * 100 - ) - else: - importance["importance_percent"] = 0 - # -------------------------------- # 3. Analyze HIGH-risk predictions # -------------------------------- @@ -136,26 +141,11 @@ def analyze_root_causes(): shap_values[high_risk_mask] ) - high_risk_importance = ( - high_risk_shap.mean(axis=0) - ) - - total_high = ( - high_risk_importance.sum() - ) - - for feature, value in zip( - features, - high_risk_importance, - ): - - percent = ( - float(value / total_high * 100) - if total_high > 0 - else 0.0 - ) + high_risk_importance = _mean_absolute_attributions(high_risk_shap) + percentages = _importance_percentages(high_risk_importance) - high_risk_causes[feature] = percent + for feature, percent in zip(features, percentages): + high_risk_causes[feature] = float(percent) high_risk_causes = dict( sorted( diff --git a/tests/test_root_cause_extreme_values.py b/tests/test_root_cause_extreme_values.py new file mode 100644 index 0000000..8110f80 --- /dev/null +++ b/tests/test_root_cause_extreme_values.py @@ -0,0 +1,40 @@ +import json + +import numpy as np +import pandas as pd +import pytest + +from src import root_cause + + +@pytest.mark.parametrize( + "values, expected", + [ + ([[1e308, 1e308], [1e308, 1e308]], {"a": 50, "b": 50}), + ([[0., 0.], [0., 0.]], {"a": 0, "b": 0}), + ([[1., 3.], [1., 3.]], {"a": 25, "b": 75}), + ], +) +def test_finite_shap_produces_normalized_feature_importance(tmp_path, monkeypatch, values, expected): + production = tmp_path / "production.csv" + pd.DataFrame({"a": [1., 2.], "b": [3., 4.], "prediction_risk": ["HIGH", "HIGH"]}).to_csv(production, index=False) + monkeypatch.setattr(root_cause, "PRODUCTION_PATH", production) + monkeypatch.setattr(root_cause, "OUTPUT_PATH", tmp_path / "causes.json") + + class FakeModel: + feature_names_in_ = ["a", "b"] + + class FakeExplainer: + def __init__(self, model): + pass + + def shap_values(self, frame): + return np.asarray(values) + + monkeypatch.setattr(root_cause.joblib, "load", lambda _: FakeModel()) + monkeypatch.setattr(root_cause.shap, "TreeExplainer", FakeExplainer) + with np.errstate(over="raise", invalid="raise"): + root_cause.analyze_root_causes() + report = json.loads((tmp_path / "causes.json").read_text()) + assert report["global_feature_importance"] == pytest.approx(expected) + assert report["high_risk_root_causes"] == pytest.approx(expected)