KernelShap Refactoring (#207)

* change: rank_by_importance is now a standalone function

* update api and defaults names

* Delete tree_shap.py

Added this file by mistake.

* change: updated categorical_names type signature in KernelShap constructor

* doc: improved documentation to KernelShap constructor

* change: updated background dataset default size and documentation

* feat: added model type argument to KernelShap argument

* updated doc to _update_metadata

* change: categorical_names and feature_names default to the types that are returned if no user input is provided as opposed to None.

* change: ensure expected_value passed to build_explanation is always a list

* change: renamed model_type argument to task

* doc: fixed docs typos

* fix: typos in logging code

* change: changed implementation of sum_categories and extended it to work with 3D

* change: refactored KernelShap so that output summarisation happens in build_explanation. Factored out summarisation warnings in a separate method

* change: improved sum_categories readability and simplified testing code

* change: metadata update for result summarisation moved to build_explanation

* doc: improved docs to build_explanation

* change: updated imports and function names in KernelShap examples

* change: updated algorithm overview for KernelShap

* fix: linting errors

* change: implemented review suggestions

* docs: improved documentation to the explain method; changed section ordering in KernelShap docs and fixed typos

* change: modified file names for KernelShap implementation to prepare for TreeShap addition

* change: Renamed tests that will also be implemented for TreeExplainer

* change: Updated fixture names

* change: Improved clarity in Theoretical Overview section

* change: Fixed redundant warning when summarise_result=False

* doc: Improved clarity in Theoretical Overview section

* fix: Removed stray files from PR

* change: Improved typing for categorical variables start indices and dimensions

* Update source in KernelShap documentaion

* doc: Improved docstrings and fixed typos in docs

* fix: Bug in expected value casting to array

* fix: Escaped _ in constructor docstring

Author: alexcoca

alibi/api/defaults.py

@@ -89,22 +89,23 @@
 """
 
 # KernelSHAP
-DEFAULT_META_SHAP = {
+DEFAULT_META_KERNEL_SHAP = {
     "name": None,
     "type": ["blackbox"],
+    "task": None,
     "explanations": ["local", "global"],
     "params": {}
 }  # type: dict
 """
 Default KernelSHAP metadata.
 """
 
-DEFAULT_DATA_SHAP = {
+DEFAULT_DATA_KERNEL_SHAP = {
     "shap_values": [],
     "expected_value": [],
     "link": 'identity',
-    "categorical_names": None,
-    "feature_names": None,
+    "categorical_names": {},
+    "feature_names": [],
     "raw": {
         "raw_prediction": None,
         "prediction": None,

alibi/explainers/__init__.py

@@ -8,7 +8,7 @@
 from .cem import CEM
 from .cfproto import CounterFactualProto
 from .counterfactual import CounterFactual
-from .kernel_shap import KernelShap
+from .shap_wrappers import KernelShap
 
 __all__ = ["AnchorTabular",
            "DistributedAnchorTabular",

alibi/explainers/kernel_shap.py renamed to alibi/explainers/shap_wrappers.py

@@ -179,7 +179,7 @@ def at_adult_explainer(get_adult_dataset, rf_classifier, request):
 
 
 @pytest.fixture
-def mock_ks_explainer(request):
+def mock_kernel_shap_explainer(request):
     """
     Instantiates a KernelShap explainer with a mock predictor.
     """

alibi/explainers/tests/conftest.py

@@ -44,7 +44,7 @@ instance that would result in a different prediction). [Documentation](../method
 
 **Counterfactual instances**: generate counterfactual examples using a simple loss function. [Documentation](../methods/CF.ipynb), [image classification](../examples/cf_mnist.ipynb).
 
-**Kernel Shapley Additive Explanation (SHAP)**: attribute the change of a model output with respect to a given baseline (e.g., average over a training set) to each of the model features. This is achieved for each feature in turn, by averaging the difference in the model output observed when excluding a feature from the input. The exclusion of a feature is achieved by replacing it with values from the background dataset. [Documentation](../methods/KernelSHAP.ipynb), [continuous data](../examples/kernel_shap_wine_intro.ipynb), [more continous_data](../examples/kernel_shap_wine_lr.ipynb), [categorical data](../examples/kernel_shap_adult_lr.ipynb).
+**Kernel Shapley Additive Explanation (KernelSHAP)**: attribute the change of a model output with respect to a given baseline (e.g., average over a training set) to each of the input features. This is achieved for each feature in turn, by averaging the difference in the model output observed when the feature whose contribution is to be estimated is part of a group of "present" input features and the value observed when the feature is excluded from said group. The features that are not "present" (i.e., are missing) are replaced with values from a background dataset. This algorithm can be used to explain regression models. [Documentation](../methods/KernelSHAP.ipynb), [continuous data](../examples/kernel_shap_wine_intro.ipynb), [more continous data](../examples/kernel_shap_wine_lr.ipynb), [categorical data](../examples/kernel_shap_adult_lr.ipynb).
 
 **Prototype Counterfactuals**: generate counterfactuals guided by nearest class prototypes other than the class predicted on the original instance. It can use both an encoder or k-d trees to define the prototypes. This method can speed up the search, especially for black box models, and create interpretable counterfactuals. [Documentation](../methods/CFProto.ipynb), [tabular example](../examples/cfproto_housing.nblink), [tabular example with categorical features](../examples/cfproto_cat_adult_ohe.ipynb), [image classification](../examples/cfproto_mnist.ipynb).
 

alibi/explainers/tests/test_kernel_shap.py renamed to alibi/explainers/tests/test_shap_wrappers.py

@@ -76,9 +76,8 @@
     "import matplotlib.pyplot as plt\n",
     "import numpy as np\n",
     "import pandas as pd\n",
-    "import seaborn as sns\n",
     "\n",
-    "from alibi.explainers.kernel_shap import KernelShap\n",
+    "from alibi.explainers import KernelShap\n",
     "from alibi.datasets import fetch_adult\n",
     "from scipy.special import logit\n",
     "from sklearn.compose import ColumnTransformer\n",
@@ -969,7 +968,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.3"
+   "version": "3.7.6"
   }
  },
  "nbformat": 4,

doc/source/methods/KernelSHAP.ipynb

@@ -76,9 +76,8 @@
     "import matplotlib.pyplot as plt\n",
     "import numpy as np\n",
     "import pandas as pd\n",
-    "import seaborn as sns\n",
     "\n",
-    "from alibi.explainers.kernel_shap import KernelShap\n",
+    "from alibi.explainers import KernelShap\n",
     "from alibi.datasets import fetch_adult\n",
     "from scipy.special import logit\n",
     "from sklearn.compose import ColumnTransformer\n",
@@ -683,7 +682,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "def extract_importances(class_idx, beta, feature_names, intercepts=None):\n",
+    "def get_importance(class_idx, beta, feature_names, intercepts=None):\n",
     "    \"\"\"\n",
     "    Retrive and sort abs magnitude of coefficients from model.\n",
     "    \"\"\"\n",
@@ -702,7 +701,7 @@
     "\n",
     "    return feat_imp, feat_names\n",
     "\n",
-    "def plot_importances(feat_imp, feat_names, class_idx, **kwargs):\n",
+    "def plot_importance(feat_imp, feat_names, class_idx, **kwargs):\n",
     "    \"\"\"\n",
     "    Create a horizontal barchart of feature effects, sorted by their magnitude.\n",
     "    \"\"\"\n",
@@ -778,10 +777,10 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "feat_imp, srt_feat_names = extract_importances(class_idx, \n",
-    "                                               all_coef, \n",
-    "                                               perm_feat_names,\n",
-    "                                              )"
+    "feat_imp, srt_feat_names = get_importance(class_idx, \n",
+    "                                          all_coef, \n",
+    "                                          perm_feat_names,\n",
+    "                                         )"
    ]
   },
   {
@@ -837,13 +836,13 @@
     }
    ],
    "source": [
-    "_, class_0_fig = plot_importances(feat_imp, \n",
-    "                                  srt_feat_names, \n",
-    "                                  class_idx,\n",
-    "                                  left_x=-2.5,\n",
-    "                                  right_x=3.7,\n",
-    "                                  eps_factor=12  # controls text distance from end of bar\n",
-    "                                  )"
+    "_, class_0_fig = plot_importance(feat_imp, \n",
+    "                                 srt_feat_names, \n",
+    "                                 class_idx,\n",
+    "                                 left_x=-2.5,\n",
+    "                                 right_x=3.7,\n",
+    "                                 eps_factor=12  # controls text distance from end of bar\n",
+    "                                )"
    ]
   },
   {
@@ -2463,7 +2462,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.3"
+   "version": "3.7.6"
   }
  },
  "nbformat": 4,

doc/source/overview/algorithms.md

@@ -75,7 +75,6 @@
     "\n",
     "import matplotlib.pyplot as plt\n",
     "import numpy as np\n",
-    "import seaborn as sns\n",
     "\n",
     "from alibi.explainers import KernelShap\n",
     "from sklearn import svm\n",
@@ -535,7 +534,9 @@
   {
    "cell_type": "code",
    "execution_count": 16,
-   "metadata": {},
+   "metadata": {
+    "scrolled": true
+   },
    "outputs": [
     {
      "data": {
@@ -1195,7 +1196,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.3"
+   "version": "3.7.6"
   }
  },
  "nbformat": 4,

examples/kernel_shap_adult_categorical_preproc.ipynb

@@ -75,7 +75,6 @@
     "\n",
     "import matplotlib.pyplot as plt\n",
     "import numpy as np\n",
-    "import seaborn as sns\n",
     "\n",
     "from alibi.explainers import KernelShap\n",
     "from scipy.special import logit\n",
@@ -332,7 +331,7 @@
     "    \n",
     "    return np.all(arr[:-1] <= arr[1:])\n",
     "\n",
-    "def extract_importances(class_idx, beta, feature_names, intercepts=None):\n",
+    "def get_importance(class_idx, beta, feature_names, intercepts=None):\n",
     "    \"\"\"\n",
     "    Retrive and sort abs magnitude of coefficients from model.\n",
     "    \"\"\"\n",
@@ -353,7 +352,7 @@
     "\n",
     "    return feat_imp, feat_names\n",
     "\n",
-    "def plot_importances(feat_imp, feat_names, **kwargs):\n",
+    "def plot_importance(feat_imp, feat_names, **kwargs):\n",
     "    \"\"\"\n",
     "    Create a horizontal barchart of feature effects, sorted by their magnitude.\n",
     "    \"\"\"\n",
@@ -413,10 +412,10 @@
    "outputs": [],
    "source": [
     "class_idx = 0\n",
-    "feat_imp, feat_names = extract_importances(class_idx, \n",
-    "                                           beta, \n",
-    "                                           feature_names,\n",
-    "                                          )"
+    "feat_imp, feat_names = get_importance(class_idx, \n",
+    "                                      beta, \n",
+    "                                      feature_names,\n",
+    "                                      )"
    ]
   },
   {
@@ -438,13 +437,13 @@
     }
    ],
    "source": [
-    "_, class_0_fig = plot_importances(feat_imp, \n",
-    "                                  feat_names, \n",
-    "                                  left_x=-1.,\n",
-    "                                  right_x=1.25,\n",
-    "                                  xlabel = \"Feature effects (class {})\".format(class_idx),\n",
-    "                                  ylabel = \"Features\"\n",
-    "                                  )"
+    "_, class_0_fig = plot_importance(feat_imp, \n",
+    "                                 feat_names, \n",
+    "                                 left_x=-1.,\n",
+    "                                 right_x=1.25,\n",
+    "                                 xlabel = \"Feature effects (class {})\".format(class_idx),\n",
+    "                                 ylabel = \"Features\"\n",
+    "                                 )"
    ]
   },
   {
@@ -487,10 +486,10 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "feat_imp, feat_names = extract_importances(1,            # class_idx \n",
-    "                                           beta, \n",
-    "                                           feature_names,\n",
-    "                                          )"
+    "feat_imp, feat_names = get_importance(1,            # class_idx \n",
+    "                                      beta, \n",
+    "                                      feature_names,\n",
+    "                                      )"
    ]
   },
   {
@@ -519,14 +518,14 @@
     }
    ],
    "source": [
-    "_, class_1_fig = plot_importances(feat_imp, \n",
-    "                                  feat_names, \n",
-    "                                  left_x=-1.5,\n",
-    "                                  right_x=1,\n",
-    "                                  eps_factor = 5,  # controls text distance from end of bar for negative examples\n",
-    "                                  xlabel = \"Feature effects (class {})\".format(1),\n",
-    "                                  ylabel = \"Features\"\n",
-    "                                  )"
+    "_, class_1_fig = plot_importance(feat_imp, \n",
+    "                                 feat_names, \n",
+    "                                 left_x=-1.5,\n",
+    "                                 right_x=1,\n",
+    "                                 eps_factor = 5,  # controls text distance from end of bar for negative examples\n",
+    "                                 xlabel = \"Feature effects (class {})\".format(1),\n",
+    "                                 ylabel = \"Features\"\n",
+    "                                 )"
    ]
   },
   {
@@ -535,10 +534,10 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "feat_imp, feat_names = extract_importances(2, # class_idx\n",
-    "                                           beta, \n",
-    "                                           feature_names,\n",
-    "                                          )"
+    "feat_imp, feat_names = get_importance(2, # class_idx\n",
+    "                                      beta, \n",
+    "                                      feature_names,\n",
+    "                                      )"
    ]
   },
   {
@@ -567,14 +566,14 @@
     }
    ],
    "source": [
-    "_, class_2_fig = plot_importances(feat_imp, \n",
-    "                                  feat_names, \n",
-    "                                  left_x=-1.25,\n",
-    "                                  right_x=1,\n",
-    "                                  xlabel = \"Feature effects (class {})\".format(2),\n",
-    "                                  ylabel = \"Features\"\n",
+    "_, class_2_fig = plot_importance(feat_imp, \n",
+    "                                 feat_names, \n",
+    "                                 left_x=-1.25,\n",
+    "                                 right_x=1,\n",
+    "                                 xlabel = \"Feature effects (class {})\".format(2),\n",
+    "                                 ylabel = \"Features\"\n",
     "#                                   eps_factor = 5.\n",
-    "                                  )"
+    "                                 )"
    ]
   },
   {
@@ -938,7 +937,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.3"
+   "version": "3.7.6"
   }
  },
  "nbformat": 4,