Package: nshap
Welcome to the nshap Package!This is a python package to compute interaction indices that extend the Shapley Value. It accompanies the AISTATS'23 paperFrom Shapley Values to Generalized Additive Models and backby Sebastian Bordt and Ulrike von Luxburg.The package supports, among others,n-Shapley Values, introduced in our paperSHAP Interaction Values, a popular interaction index that can also be computed with theshappackagetheShapley Taylorinteraction indextheFaith-Shapinteraction indextheFaith-Banzhafinteraction index.The package  works with arbitrary user-defined value functions. It also provides a model-agnostic implementation of the interventional SHAP value function.The computed interaction indices are an estimatethat can be inaccurate, especially if the order of the interaction is large.Documentation is available athttps://tml-tuebingen.github.io/nshap.⚠️ DisclaimerThis package does not provide an efficient way to compute Shapley Values. For this you should refer to theshappackage or approaches likeFastSHAP. In practice, the current implementation works for arbitrary functions of up to ~10 variables. This package should be used for research purposes only.SetupTo install the package runpip install nshapComputing Interaction IndicesLet's assume that we have trained a Gradient Boosted Tree on theFolktablesIncome data set.gbtree=xgboost.XGBClassifier()gbtree.fit(X_train,Y_train)print(f'Accuracy:{accuracy_score(Y_test,gbtree.predict(X_test)):0.3f}')Accuracy: 0.806Now we want to compute an interaction index. This package supports interaction indices that extend the Shapley Value. This means that the interaction index is based on a value function, just as the Shapley Value. So we need to define a value function. We can use the functionnshap.vfunc.interventional_shap, which approximates the interventional SHAP value function.importnshapvfunc=nshap.vfunc.interventional_shap(gbtree.predict_proba,X_train,target=0,num_samples=1000)The function takes 4 argumentsThe function that we want to explainThe training data or another sample from the data distributionThe target class (required here since 'predict_proba' has 2 outputs).The number of samples that should be used to estimate the expectation (Default: 1000)Equipped with a value function, we can compute different kinds of interaction indices. We can compute n-Shapley Valuesn_shapley_values=nshap.n_shapley_values(X_test[0,:],vfunc,n=10)the Shapley-Taylor interaction indexshapley_taylor=nshap.shapley_taylor(X_test[0,:],vfunc,n=10)or the Faith-Shap interaction index of order 3faith_shap=nshap.shapley_taylor(X_test[0,:],vfunc,n=3)Functions that compute interaction indices have a common interface. They take 3 argumentsThe data point for which we want to compute the explanationThe value functionThe order of the interaction indexAll functions return an object of typeInteractionIndex. This is a pythondictwith some added functionallity.To get the interaction effect between features 2 and 3, simply calln_shapley_values[(2,3)]0.0074To visualize an interaction index, calln_shapley_values.plot(feature_names=feature_names)This works for all interaction indicesfaith_shap.plot(feature_names=feature_names)For n-Shapley Values, we can compute interaction indices of lower order from those of higher ordern_shapley_values.k_shapley_values(2).plot(feature_names=feature_names)We can also compute the original Shapley Values and plot them with the plotting functions from theshappackage.shap.force_plot(vfunc(X_test[0,:],[]),n_shapley_values.shapley_values())Let us compare our result to the Shapley Values from the KernelSHAP Algorithm.importshapexplainer=shap.KernelExplainer(gbtree.predict_proba,shap.kmeans(X_train,25))shap.force_plot(explainer.expected_value[0],shap_values[0])There are differences which is not surprising since the KernelSHAP algorithm only approximates the Shapley Values.Overview of the packageComputing Interaction IndicesThe package has a separate function for the computation of each interaction index.n_shapley_values(X, v_func, n=-1)for $n$-Shapley Values.shapley_taylor(X, v_func, n=-1)for the Faith-Shap Interaction Index.faith_shap(X, v_func, n=-1)for the Faith-Shap Interaction Index.and so on. The parameters for all of these function arex: A singe data point for which to compute the interaction index (numpy.ndarray)v_func: A value function, the basic primitive in the computation of all computations (see below on how to define custom value functions)n, the desired order of the interaction index. Defaults to the number of features (complete functional decomposition or Shapley-GAM).These function an object of typeInteractionIndex.TheInteractionIndexclassTheInteractionIndexclass is a pythondictwith some added functionallity. It supports the following operations.The individual attributions can be indexed with tuples of integers. For example, indexing with(0,)returns the main effect of the first feature. Indexing with(0,1,2)returns the interaction effect between features 0, 1 and 2.plot()generates the plots described in the paper.sum()sums the individual attributions (this does usually sum to the function value minus the value of the empty coalition)save(fname)serializes the object to json. Can be loaded from there withnshap.load(fname). This can be useful since computing $n$-Shapley Values takes time, so you might want to compute them in parallel in the cloud, then aggregate the results for analysis.Some function can only be called certain interaction indices:k_shapley_values(k)computes the $k$-Shapley Values using the recursive relationship among $n$-Shapley Values of different order (requires $k\leq n$). Can only be called for $n$-Shapley Values.shapley_values()returns the associated original Shapley Values as a list. Useful for compatiblity with theshappackage.Definig Value FunctionsA value function has to follow the interfacev_func(x, S)wherexis a single data point (anumpy.ndarray) andSis a pythonlistwith the indices the the coordinates that belong to the coaltion.In the introductory example with the Gradient Boosted Tree,vfunc(x,[])returns the expected predicted probability that an observation belongs to class 0, andvfunc(x,[0,1,2,3,4,5,6,7,8,9])returns the predicted probability that the observationxbelongs to class 0 (note that the problem is 10-dimensional).Implementation DetailsAt the moment all functions computes interaction indices simply via their definition. Independent of the ordernof the $n$-Shapley Values, this requires to call the value functionv_funconce for all $2^d$ subsets of coordinates. Thus, the current implementation provides no essential speedup for the computation of $n$-Shapley Values of lower order.The functionnshap.vfunc.interventional_shapapproximates the interventional SHAP value function by intervening on the coordinates of randomly sampled points from the data distributions.Accuray of the computed interaction indicesThe computed $n$-Shapley Values are an estimate which can be inaccurate.The estimation error depends on the precision of the value function. With the provided implementation of the interventional SHAP value function, the precision depends on the number of samples used to estimate the expectation.A simple way to test whether your result is precisely estimated to increase the number of samples (thenum_samplesparameter ofnshap.vfunc.interventional_shap) and see if the result changes.For more details, check out the discussion inSection 8 of our paper.Replicating the Results in our PaperThe foldernotebooks\replicate-papercontains Jupyter Notebooks that allow to replicated the results in ourpaper.The notebooksfigures.ipynbandcheckerboard-figures.ipynbgenerate all the figures in the paper.The notebookestimation.ipynbprovides the estimation example with the kNN classifier on the Folktables Travel data set that we discuss in Appendix Section B.The notebookhyperparameters.ipynbcross-validates the parameter $k$ of the kNN classifier.The notebookscompute.ipynb,compute-vfunc.ipynb,checkerboard-compute.ipynbandcheckerboard-compute-million.ipynbcompute the different $n$-Shapley Values. You do not have to run these notebooks, the pre-computed results can be downloadedhere.⚠️ ImportantYou have use version 0.1.0 of this package in order to run the notebooks that replicate the results in the paper.pip install nshap=0.1.0Citing nshapIf you use this software in your research, we encourage you to cite our paper.@article{bordtlux2022,title={From Shapley Values to Generalized Additive Models and back},author={Bordt, Sebastian and von Luxburg, Ulrike},url={https://arxiv.org/abs/2209.04012},publisher={AISTATS},year={2023},}If you use interaction indices that were introduced in other works, such asShapley TaylororFaith-Shap, you should also consider to cite the respective papers.