Documentation

Functions that compute interaction indices

nshap.functions.banzhaf_interaction_index(x, v_func, n=-1)

Compute the Banzhaf Interaction Index (https://link.springer.com/article/10.1007/s001820050125) at the data point x, and all S such that |S|<=n, given a coalition value function.

Parameters:

x (numpy.ndarray) – A data point
v_func (function) – The value function. It takes two arguments: The datapoint x and a list with the indices of the coalition.
n (int) – Order up to which the Shapley Interaction Index should be computed.

Returns:

The interaction index.

Return type:

nshap.InteractionIndex

nshap.functions.faith_banzhaf(x, v_func, n=-1)

Compute the Faith-Banzhaf Interaction Index (https://arxiv.org/abs/2203.00870) of the value function v_func at the data point x.

Parameters:

x (numpy.ndarray) – A data point.
v_func (function) – The value function. It takes two arguments: The datapoint x and a list with the indices of the coalition.
n (int, optional) – Order of the Interaction Index or -1 for n=d. Defaults to -1.

Returns:

The interaction index.

Return type:

nshap.InteractionIndex

nshap.functions.faith_shap(x, v_func, n=-1)

Compute the Faith-Shap Interaction Index (https://arxiv.org/abs/2203.00870) of the value function v_func at the data point x.

Parameters:

x (numpy.ndarray) – A data point.
v_func (function) – The value function. It takes two arguments: The datapoint x and a list with the indices of the coalition.
n (int, optional) – Order of the Interaction Index or -1 for n=d. Defaults to -1.

Returns:

The interaction index.

Return type:

nshap.InteractionIndex

nshap.functions.moebius_transform(x, v_func)

Compute the Moebius Transform of of the value function v_func at the data point x.

Parameters:

x (numpy.ndarray) – A data point.
v_func (function) – The value function. It takes two arguments: The datapoint x and a list with the indices of the coalition.

Returns:

The interaction index.

Return type:

nshap.InteractionIndex

nshap.functions.n_shapley_values(x, v_func, n=-1)

This function provides an exact computation of n-Shapley Values (https://arxiv.org/abs/2209.04012) via their definition.

Parameters:

x (numpy.ndarray) – A data point.
v_func (function) – The value function. It takes two arguments: The datapoint x and a list with the indices of the coalition.
n (int, optional) – Order of n-Shapley Values or -1 for n=d. Defaults to -1.

Returns:

The interaction index.

Return type:

nshap.InteractionIndex

nshap.functions.shapley_interaction_index(x, v_func, n=-1)

Compute the Shapley Interaction Index (https://link.springer.com/article/10.1007/s001820050125) at the data point x, and all S such that |S|<=n, given a coalition value function.

Parameters:

x (numpy.ndarray) – A data point
v_func (function) – The value function. It takes two arguments: The datapoint x and a list with the indices of the coalition.
n (int) – Order up to which the Shapley Interaction Index should be computed.

Returns:

The interaction index.

Return type:

nshap.InteractionIndex

nshap.functions.shapley_taylor(x, v_func, n=-1)

Compute the Shapley Taylor Interaction Index (https://arxiv.org/abs/1902.05622) of the value function v_func at the data point x.

Parameters:

x (numpy.ndarray) – A data point.
v_func (function) – The value function. It takes two arguments: The datapoint x and a list with the indices of the coalition.
n (int, optional) – Order of the Shapley Taylor Interaction Index or -1 for n=d. Defaults to -1.

Returns:

The interaction index.

Return type:

nshap.InteractionIndex

nshap.functions.shapley_values(x, v_func)

Compute the original Shapley Values, according to the Shapley Formula.

Parameters:

x (numpy.ndarray) – A data point.
v_func (function) – The value function. It takes two arguments: The datapoint x and a list with the indices of the coalition.

Returns:

The interaction index.

Return type:

nshap.InteractionIndex

nshap.functions.validate_inputs(x, v_func)

Value Functions

nshap.vfunc.interventional_shap(f, X, target=None, num_samples=1000, random_state=None, meomized=True)

Approximate the value function of interventional SHAP.

In order to compute n-Shapley Values, a data set is sampled once and then fixed for all evaluations of the value function.

Parameters:

f (function) – The function to be explained. Will be called as f(x) where x has shape (1,d).
X (_type_) – Sample from the data distribution.
target (int, optional) – Target class. Required if the output of f(x) is multi-dimensional. Defaults to None.
num_samples (int, optional) – The number of samples that should be drawn from X in order estimate the value function. Defaults to 1000.
random_state (_type_, optional) – Random state that is passed to np.random.default_rng. Used for reproducibility. Defaults to None.
meomized (bool, optional) – Whether the returned value function should be meomized. Defaults to True.

Returns:

The vaue function.

Return type:

function

class nshap.vfunc.memoized_vfunc(func)

Bases: object

Decorator to meomize a vfunc. Handles hashability of the numpy.ndarray and the list.

The hash depends only on the values of x that are in the subset of coordinates.

This function is able to handle parameters x of shape (d,) and (1,d).

Meomization helps to avoid duplicate evaluations of the value function, even if we perform computations that involve the same term multiple times.

https://wiki.python.org/moin/PythonDecoratorLibrary

The InteractionIndex class

class nshap.InteractionIndex.InteractionIndex(index_type: str, values, n=None, d=None)

Bases: UserDict

Class for different interaction indices (n-Shapley Values, Shapley Taylor, Faith-Shap). Interaction indices are a Python dict with added functionality.

copy()

Return a copy of the current object.

Returns:: The copy.
Return type:: nshap.InteractionIndex

get_index_type()

Return the type of the interaction index (for example, “Shapley Taylor”)

Returns:: See function description.
Return type:: str

get_input_dimension()

Return the input dimension of the function for which we computed the interaction index (‘d’).

Returns:: See function description.
Return type:: integer

get_order()

Return the order of the interaction index (‘n’).

Returns:: See function description.
Return type:: integer

k_shapley_values(k)

Compute k-Shapley Values of lower order. Requires k <= n.

Parameters:: k (int) – The desired order.
Returns:: k-Shapley Values.
Return type:: nShapleyValues

plot(*args, **kwargs)

Generate a plots of the n-Shapley Values.

This function simply calls nshap.plots.plot_n_shapley.

Returns:: The axis of the matplotlib plot.

save(fname)

Save the interaction index to a JSON file.

Parameters:: fname (str) – Filename.

shapley_values()

Compute the original Shapley Values.

Returns:: Shaley Values. If you prefer an object of type nShapleyValues, call k_shapley_values(self, 1).
Return type:: numpy.ndarray

sum()

Sum all the terms that are invovled in the interaction index.

For many interaction indices, the result is equal to the value of the function that we attempt to explain, minus the value of the empty coalition.

Returns:: The sum.
Return type:: Float

Plotting and Utilities

nshap.plot.plot_interaction_index(I: InteractionIndex, max_degree=None, axis=None, feature_names=None, rotation=70, legend=True, fig_kwargs={'figsize': (6, 6)}, barwidth=0.5)

Generate the plots in the paper.

Parameters:

n_shapley_values (nshap.nShapleyValues) – The n-Shapley Values that we want to plot.
max_degree (int, optional) – Plots all effect of order larger than max_degree with a single color. Defaults to None.
axis (optional) – Matplotlib axis on which to plot. Defaults to None.
feature_names (_type_, optional) – Used to label the x-axis. Defaults to None.
rotation (int, optional) – Rotation for x-axis labels. Defaults to 70.
legend (bool, optional) – Plot legend. Defaults to True.
fig_kwargs (dict, optional) – fig_kwargs, handed down to matplotlib figure. Defaults to {“figsize”: (6, 6)}.
barwidth (float, optional) – Widht of the bars. Defaults to 0.5.

Returns:

The plot axis.

Return type:

Matplotlib axis

nshap.util.allclose(dict1, dict2, rtol=1e-05, atol=1e-08)

Compare if two dicts of n-Shapley Values are close according to numpy.allclose.

Useful for testing purposes.

Parameters:

dict1 (dict) – The first dict.
dict2 (dict) – The second dict.
rtol (float, optional) – passed to numpy.allclose. Defaults to 1e-05.
atol (float, optional) – passed to numpy.allclose. Defaults to 1e-08.

Returns:

Result of numpy.allclose.

Return type:

bool

nshap.util.load(fname)

Load an interaction index from a JSON file.

Parameters:: fname (str) – Filename.
Returns:: The loaded interaction index.
Return type:: nshap.InteractionIndex

nshap.util.powerset(iterable): The powerset function from https://docs.python.org/3/library/itertools.html#itertools-recipes.

nshap.util.read_remove(d, key): Read and remove a key from a dict d.

nshap.util.save(values, fname)

Save an interaction index to a JSON file.

Parameters:

values (nshap.InteractionIndex) – The interaction index.
fname (str) – Filename.

nshap.util.to_int_tuple(str_tuple)

Convert string representations of integer tuples back to python integer tuples.

This utility function is used to load n-Shapley Values from JSON.

Parameters:: str_tuple (str) – String representaiton of an integer tuple, for example “(1,2,3)”
Returns:: Tuple of integers, for example (1,2,3)
Return type:: tuple