Feature/add feature values to explainability result #1546

rijkvandermeulen · 2023-02-08T14:12:23Z

Summary

Currently the ExplainabilityResult object only contains the explained forecast (i.e., the shapley values for each prediction). I think it would be useful to also store the corresponding feature values and the SHAP explanation object itself. This will give the end user more options to work with the explainability results (e.g., creating plots, doing analysis etc). In any case, having this functionality added would help how we use darts a great deal so from a personal pov I'd love to see this added :)

Other Information

Since I added two methods that very much resemble 'get_explanation' I've written a decorator to take care of the validation steps. Main goal here was to avoid duplicating the validation checks across multiple methods. If you think this makes the code necessarily complex and/or less readable let me know - then we can change it back.

@hrzn @dumjax
WDYT? Do you see the added value of this? Any thoughts on how to make it better?

codecov-commenter · 2023-02-08T15:10:55Z

Codecov Report

Patch coverage: 97.56% and project coverage change: -0.08 ⚠️

Comparison is base (301122e) 94.12% compared to head (cd9cce8) 94.05%.

📣 This organization is not using Codecov’s GitHub App Integration. We recommend you install it so Codecov can continue to function properly for your repositories. Learn more

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1546      +/-   ##
==========================================
- Coverage   94.12%   94.05%   -0.08%     
==========================================
  Files         125      125              
  Lines       11308    11326      +18     
==========================================
+ Hits        10644    10653       +9     
- Misses        664      673       +9

Impacted Files	Coverage Δ
darts/explainability/explainability_result.py	`95.12% <95.00%> (-0.88%)`	⬇️
darts/explainability/shap_explainer.py	`88.83% <100.00%> (+0.85%)`	⬆️

... and 9 files with indirect coverage changes

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

…ty_result

dennisbader

@rijkvandermeulen thanks again for another great PR :)

Looks good in general! I added a suggestion that we should try to keep ExplainabilityResult as a base class, and opt for a new ShapExplainabilityResult subclass that carries the added logic specific to Shap Explainers.

Apart from that, only minor suggestions, and some fixes in the unit tests.

dennisbader · 2023-02-28T08:58:12Z

darts/explainability/shap_explainer.py

+        if len(feature_values_list) == 1:
+            feature_values_list = feature_values_list[0]
+        if len(shap_explanation_object_list) == 1:
+            shap_explanation_object_list = shap_explanation_object_list[0]


Suggested change

if len(feature_values_list) == 1:

feature_values_list = feature_values_list[0]

if len(shap_explanation_object_list) == 1:

shap_explanation_object_list = shap_explanation_object_list[0]

feature_values_list = feature_values_list[0]

shap_explanation_object_list = shap_explanation_object_list[0]

dennisbader · 2023-02-28T09:34:52Z

darts/explainability/explainability_result.py

+            The component for which to return the `shap.Explanations` object(s). Does not
+            need to be specified for univariate series.
+        """
+        if not self.shap_explanation_object:


If we have the ShapExplainabilityResult subclass, it is guaranteed that it will have a shap_explanation_object

darts/explainability/explainability_result.py

dennisbader · 2023-02-28T10:00:20Z

darts/explainability/shap_explainer.py

@@ -580,6 +601,7 @@ def shap_explanations(
                                :, :, self.target_dim * (h - 1) + t_idx
                            ]
                        )
+                        tmp_t.data = shap_explanation_tmp.data


is this required?

Yep, I believe it is. Reason being that in this particular if condition the shap.Explanation object is 'manually' constructed so the tmp_t dict doesn't contain the feature values (i.e., data) yet.

darts/tests/explainability/test_shap_explainer.py

dennisbader · 2023-02-28T10:25:11Z

darts/explainability/explainability_result.py

@@ -16,6 +18,45 @@
 logger = get_logger(__name__)


+def check_input_validity_for_querying_explainability_result(func: Callable) -> Callable:


Could we simply make this a normal function and call it at the begging in each method?

Wrappers can swallow up the actual method/function arguments in the documentation (from IDE for example) without some additional code

…rator

…ssert + other small stuff

… ShapExplainabilityResult

…ty_result # Conflicts: # darts/tests/explainability/test_shap_explainer.py

rijkvandermeulen · 2023-03-06T07:26:25Z

@dennisbader thanks for the review! I believe I've addressed all your comments and suggestions. Let me know in case you've any additional remarks :)

…ty_result

dennisbader

Looks great @rijkvandermeulen, thanks for the updates!

I only had one suggestion for refactoring :) After that we can merge this one! 🚀

darts/explainability/explainability_result.py

dennisbader · 2023-03-11T12:25:23Z

darts/explainability/explainability_result.py

+            Dict[integer, Dict[str, TimeSeries]],
+            Sequence[Dict[integer, Dict[str, TimeSeries]]],
+        ],
+        shap_explanation_object: Optional[


I guess the Optional can now be removed

dennisbader · 2023-03-11T12:31:22Z

darts/tests/explainability/test_shap_explainer.py

+        ).data
+
+        assert_array_equal(feature_values.values(), comparison)
+        self.assertTrue(


shouldn't this be assertEqual?

… code duplication

…ty_result

…ttps://github.com/rijkvandermeulen/darts into feature/add_feature_values_to_explainability_result

rijkvandermeulen · 2023-03-12T12:38:44Z

@dennisbader implemented your suggestions! :)

BTW, not very important and also not something for this PR but I was thinking about whether it would make sense to at some point refactor the attributes in ExplainabilityResult (which are now nested dictionaries) to dataclasses? Might potentially make it even more robust and easier to maintain.

dennisbader

Thanks a lot for this @rijkvandermeulen, looks great :) 🚀

And I like your idea about refactoring the ExplainabilityResult attributes with dataclasses 👍
That could make our lives much easier also for extending the Explainability module.

* store feature values and shap.Explanation object in ExplainabilityResult * accounted for is_multioutputregressor * unit8co#1545 added entry to CHANGELOG.md * unit8co#1545 update docstrings for correctness API reference docs * unit8co#1580 create ShapExplainabilityResult subclass and remove decorator * unit8co#1580 adjust unit tests to have dedicated with statement per assert + other small stuff * unit8co#1580 change asserts in unit test from ExplainabilityResult to ShapExplainabilityResult * unit8co#1580 test get_feature_values() against raw output shap * unit8co#1580 adjust docstring * unit8co#1580 fixing small stuff * unit8co#1580 added one assert to unit test * unit8co#1545 implement _query_explainability_result() helper to avoid code duplication --------- Co-authored-by: Rijk van der Meulen <rijk.vandermeulen@eyeon.nl> Co-authored-by: madtoinou <32447896+madtoinou@users.noreply.github.com> Co-authored-by: Dennis Bader <dennis.bader@gmx.ch>

Rijk van der Meulen added 3 commits February 8, 2023 12:17

store feature values and shap.Explanation object in ExplainabilityResult

5f0e203

accounted for is_multioutputregressor

b73b511

unit8co#1545 added entry to CHANGELOG.md

95218df

rijkvandermeulen requested review from hrzn and dennisbader as code owners February 8, 2023 14:12

unit8co#1545 update docstrings for correctness API reference docs

5e65c54

Merge branch 'master' into feature/add_feature_values_to_explainabili…

9cabda1

…ty_result

hrzn linked an issue Feb 10, 2023 that may be closed by this pull request

Add feature values and SHAP explanation object to ExplainabityResult #1545

Closed

dennisbader requested changes Feb 28, 2023

View reviewed changes

Rijk van der Meulen added 8 commits March 5, 2023 09:55

unit8co#1580 create ShapExplainabilityResult subclass and remove deco…

b8b6161

…rator

unit8co#1580 adjust unit tests to have dedicated with statement per a…

03aa49c

…ssert + other small stuff

unit8co#1580 change asserts in unit test from ExplainabilityResult to…

33c42bf

… ShapExplainabilityResult

unit8co#1580 test get_feature_values() against raw output shap

5bcb76c

unit8co#1580 adjust docstring

23f77c7

unit8co#1580 fixing small stuff

383a375

unit8co#1580 added one assert to unit test

579dbe4

Merge branch 'master' into feature/add_feature_values_to_explainabili…

55e9941

…ty_result # Conflicts: # darts/tests/explainability/test_shap_explainer.py

Merge branch 'master' into feature/add_feature_values_to_explainabili…

68fde66

…ty_result

dennisbader requested changes Mar 11, 2023

View reviewed changes

Rijk van der Meulen added 3 commits March 12, 2023 13:07

unit8co#1545 implement _query_explainability_result() helper to avoid…

7176e11

… code duplication

Merge branch 'master' into feature/add_feature_values_to_explainabili…

9f9f074

…ty_result

Merge branch 'feature/add_feature_values_to_explainability_result' of h…

cd9cce8

…ttps://github.com/rijkvandermeulen/darts into feature/add_feature_values_to_explainability_result

dennisbader approved these changes Mar 12, 2023

View reviewed changes

dennisbader merged commit f7c292a into unit8co:master Mar 12, 2023

dennisbader mentioned this pull request Mar 12, 2023

Add feature values and SHAP explanation object to ExplainabityResult #1545

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Feature/add feature values to explainability result #1546

Feature/add feature values to explainability result #1546

rijkvandermeulen commented Feb 8, 2023 •

edited

Loading

codecov-commenter commented Feb 8, 2023 •

edited

Loading

dennisbader left a comment

dennisbader Feb 28, 2023

dennisbader Feb 28, 2023

dennisbader Feb 28, 2023

rijkvandermeulen Mar 6, 2023

dennisbader Feb 28, 2023

rijkvandermeulen commented Mar 6, 2023

dennisbader left a comment

dennisbader Mar 11, 2023

dennisbader Mar 11, 2023

rijkvandermeulen commented Mar 12, 2023

dennisbader left a comment

		@@ -16,6 +18,45 @@
		logger = get_logger(__name__)


		def check_input_validity_for_querying_explainability_result(func: Callable) -> Callable:

Feature/add feature values to explainability result #1546

Feature/add feature values to explainability result #1546

Conversation

rijkvandermeulen commented Feb 8, 2023 • edited Loading

Summary

Other Information

codecov-commenter commented Feb 8, 2023 • edited Loading

Codecov Report

dennisbader left a comment

Choose a reason for hiding this comment

dennisbader Feb 28, 2023

Choose a reason for hiding this comment

dennisbader Feb 28, 2023

Choose a reason for hiding this comment

dennisbader Feb 28, 2023

Choose a reason for hiding this comment

rijkvandermeulen Mar 6, 2023

Choose a reason for hiding this comment

dennisbader Feb 28, 2023

Choose a reason for hiding this comment

rijkvandermeulen commented Mar 6, 2023

dennisbader left a comment

Choose a reason for hiding this comment

dennisbader Mar 11, 2023

Choose a reason for hiding this comment

dennisbader Mar 11, 2023

Choose a reason for hiding this comment

rijkvandermeulen commented Mar 12, 2023

dennisbader left a comment

Choose a reason for hiding this comment

rijkvandermeulen commented Feb 8, 2023 •

edited

Loading

codecov-commenter commented Feb 8, 2023 •

edited

Loading