Merge pull request #270 from MAIF/feature/explanation_metrics

Feature/explanation metrics

Author: ThomasBouche

docs/autodocs/shapash.explainer.rst

@@ -14,6 +14,11 @@ The Plot Methods
 ----------------
 
 .. autoclass:: shapash.explainer.smart_plotter.SmartPlotter
-   :members: features_importance, contribution_plot, local_plot, compare_plot, top_interactions_plot
+   :members: features_importance, contribution_plot, local_plot, compare_plot, top_interactions_plot, local_neighbors_plot, stability_plot, compacity_plot
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: shapash.explainer.consistency.Consistency
+   :members: consistency_plot
    :undoc-members:
    :show-inheritance:

setup.py

@@ -10,6 +10,7 @@
 
 requirements = [
         'plotly==4.12.0',
+        'matplotlib>=3.3.0',
         'numpy>1.18.0',
         'pandas>1.0.2',
         'shap>=0.36.0',
@@ -31,7 +32,6 @@
 extras['report'] = [
     'nbconvert==6.0.7',
     'papermill',
-    'matplotlib',
     'seaborn<=0.11.1',
     'notebook',
     'Jinja2',

shapash/explainer/consistency.py

@@ -5,6 +5,7 @@
 import copy
 import tempfile
 import shutil
+import numpy as np
 import pandas as pd
 from shapash.webapp.smart_app import SmartApp
 from shapash.utils.io import save_pickle
@@ -26,6 +27,7 @@
 from .smart_plotter import SmartPlotter
 import shapash.explainer.smart_predictor
 from shapash.utils.model import predict_proba, predict
+from shapash.utils.explanation_metrics import find_neighbors, shap_neighbors, get_min_nb_features, get_distance
 
 logging.basicConfig(level=logging.INFO)
 
@@ -91,6 +93,13 @@ class SmartExplainer:
         Dictionary that references the numbers of feature values ​​in the x_pred
     features_imp: pandas.Series (regression) or list (classification)
         Features importance values
+    local_neighbors: dict
+        Dictionary of values to be displayed on the local_neighbors plot.
+        The key is "norm_shap (normalized contributions values of instance and neighbors)
+    features_stability: dict
+        Dictionary of arrays to be displayed on the stability plot.
+        The keys are "amplitude" (average contributions values for selected instances) and
+        "stability" (stability metric across neighborhood)
     preprocessing : category_encoders, ColumnTransformer, list or dict
         The processing apply to the original data.
     postprocessing : dict
@@ -278,6 +287,9 @@ def compile(self, x, model, explainer=None, contributions=None, y_pred=None,
         self.features_groups = features_groups
         if features_groups:
             self._compile_features_groups(features_groups)
+        self.local_neighbors = None
+        self.features_stability = None
+        self.features_compacity = None
 
     def _compile_features_groups(self, features_groups):
         """
@@ -998,6 +1010,71 @@ def compute_features_import(self, force=False):
             if self.features_imp is None or force:
                 self.features_imp = self.state.compute_features_import(self.contributions)
 
+    def compute_features_stability(self, selection):
+        """
+        For a selection of instances, compute features stability metrics used in
+        methods `local_neighbors_plot` and `local_stability_plot`.
+        - If selection is a single instance, the method returns the (normalized) contribution values
+        of instance and corresponding neighbors.
+        - If selection represents multiple instances, the method returns the average (normalized) contribution values
+        of instances and neighbors (=amplitude), as well as the variability of those values in the neighborhood (=variability)
+
+        Parameters
+        ----------
+        selection: list
+            Indices of rows to be displayed on the stability plot
+
+        Returns
+        -------
+        Dictionary
+            Values that will be displayed on the graph. Keys are "amplitude", "variability" and "norm_shap"
+        """
+        if (self._case == "classification") and (len(self._classes) > 2):
+            raise AssertionError("Multi-class classification is not supported")
+
+        all_neighbors = find_neighbors(selection, self.x_init, self.model, self._case)
+
+        # Check if entry is a single instance or not
+        if len(selection) == 1:
+            # Compute explanations for instance and neighbors
+            norm_shap, _, _ = shap_neighbors(all_neighbors[0], self.x_init, self.contributions, self._case)
+            self.local_neighbors = {"norm_shap": norm_shap}
+        else:
+            numb_expl = len(selection)
+            amplitude = np.zeros((numb_expl, self.x_pred.shape[1]))
+            variability = np.zeros((numb_expl, self.x_pred.shape[1]))
+            # For each instance (+ neighbors), compute explanation
+            for i in range(numb_expl):
+                (_, variability[i, :], amplitude[i, :],) = shap_neighbors(all_neighbors[i], self.x_init, self.contributions, self._case)
+            self.features_stability = {"variability": variability, "amplitude": amplitude}
+
+    def compute_features_compacity(self, selection, distance, nb_features):
+        """
+        For a selection of instances, compute features compacity metrics used in method `compacity_plot`.
+
+        The method returns :
+        * the minimum number of features needed for a given approximation level
+        * conversely, the approximation reached with a given number of features
+
+        Parameters
+        ----------
+        selection: list
+            Indices of rows to be displayed on the stability plot
+        distance : float
+            How close we want to be from model with all features
+        nb_features : int
+            Number of features used
+        """
+        if (self._case == "classification") and (len(self._classes) > 2):
+            raise AssertionError("Multi-class classification is not supported")
+
+        features_needed = get_min_nb_features(selection, self.contributions, self._case, distance)
+        distance_reached = get_distance(selection, self.contributions, self._case, nb_features)
+        # We clip large approximations to 100%
+        distance_reached = np.clip(distance_reached, 0, 1)
+
+        self.features_compacity = {"features_needed": features_needed, "distance_reached": distance_reached}
+
     def init_app(self, settings: dict = None):
         """
         Simple init of SmartApp in case of host smartapp by another way