shapiq.utils#

This module contains utility functions for the shapiq package.

shapiq.utils.generate_interaction_lookup(players, min_order, max_order)[source]#

Generates a lookup dictionary for interactions.

Parameters:

players (Union[Iterable[Any], int]) – A unique set of players or an Integer denoting the number of players.
min_order (Optional[int]) – The minimum order of the approximation.
max_order (Optional[int]) – The maximum order of the approximation.

Return type:

dict[tuple[Any], int]

Returns:

A dictionary that maps interactions to their index in the values vector.

Example

>>> generate_interaction_lookup(3, 1, 3)
{(0,): 0, (1,): 1, (2,): 2, (0, 1): 3, (0, 2): 4, (1, 2): 5, (0, 1, 2): 6}
>>> generate_interaction_lookup(3, 2, 2)
{(0, 1): 0, (0, 2): 1, (1, 2): 2}
>>> generate_interaction_lookup(["A", "B", "C"], 1, 2)
{('A',): 0, ('B',): 1, ('C',): 2, ('A', 'B'): 3, ('A', 'C'): 4, ('B', 'C'): 5}

shapiq.utils.get_explicit_subsets(n, subset_sizes)[source]#

Enumerates all subsets of the given sizes and returns a one-hot matrix.

Parameters:

n (int) – number of players.
subset_sizes (list[int]) – list of subset sizes.

Return type:

ndarray[bool]

Returns:

one-hot matrix of all subsets of certain sizes.

Examples

>>> get_explicit_subsets(n=4, subset_sizes=[1, 2]).astype(int)
array([[1, 0, 0, 0],
       [0, 1, 0, 0],
       [0, 0, 1, 0],
       [0, 0, 0, 1],
       [1, 1, 0, 0],
       [1, 0, 1, 0],
       [1, 0, 0, 1],
       [0, 1, 1, 0],
       [0, 1, 0, 1],
       [0, 0, 1, 1]])

shapiq.utils.pair_subset_sizes(order, n)[source]#

Determines what subset sizes are paired together.

Given an interaction order and the number of players, determines the paired subsets. Paired subsets are subsets of the same size that are paired together moving from the smallest subset paired with the largest subset to the center.

Parameters:

order (int) – interaction order.
n (int) – number of players.

Return type:

tuple[list[tuple[int, int]], Optional[int]]

Returns:

paired and unpaired subsets. If there is no unpaired subset unpaired_subset is None.

Examples

>>> pair_subset_sizes(order=1, n=5)
([(1, 4), (2, 3)], None)

>>> pair_subset_sizes(order=1, n=6)
([(1, 5), (2, 4)], 3)

>>> pair_subset_sizes(order=2, n=5)
([(2, 3)], None)

shapiq.utils.powerset(iterable, min_size=0, max_size=None)[source]#

Return a powerset of an iterable as tuples with optional size limits.

Parameters:

iterable (Iterable[Any]) – Iterable.
min_size (Optional[int]) – Minimum size of the subsets. Defaults to 0 (start with the empty set).
max_size (Optional[int]) – Maximum size of the subsets. Defaults to None (all possible sizes).

Returns:

Powerset of the iterable.

Return type:

iterable

Example

>>> list(powerset([1, 2, 3]))
[(), (1,), (2,), (3,), (1, 2), (1, 3), (2, 3), (1, 2, 3)]

>>> list(powerset([1, 2, 3], min_size=1))
[(1,), (2,), (3,), (1, 2), (1, 3), (2, 3), (1, 2, 3)]

>>> list(powerset([1, 2, 3], max_size=2))
[(), (1,), (2,), (3,), (1, 2), (1, 3), (2, 3)]

>>> list(powerset(["A", "B", "C"], min_size=1, max_size=2))
[('A',), ('B',), ('C',), ('A', 'B'), ('A', 'C'), ('B', 'C')]

shapiq.utils.safe_isinstance(obj, class_path_str)[source]#

Acts as a safe version of isinstance without having to explicitly import packages which may not exist in the user’s environment. Checks if obj is an instance of type specified by class_path_str.

Note

This function was directly taken from the shap repository.

Parameters:

obj (Any) – Some object you want to test against
class_path_str (Union[str, list[str], tuple[str]]) – A string or list of strings specifying full class paths Example: sklearn.ensemble.RandomForestRegressor

Return type:

bool

Returns:

True if isinstance is true and the package exists, False otherwise

shapiq.utils.split_subsets_budget(order, n, budget, sampling_weights)[source]#

Determines which subset sizes can be computed explicitly and which sizes need to be sampled.

Given a computational budget, determines the complete subsets that can be computed explicitly and the corresponding incomplete subsets that need to be estimated via sampling.

Parameters:

order (int) – interaction order.
n (int) – number of players.
budget (int) – total allowed budget for the computation.
sampling_weights (ndarray[float]) – weight vector of the sampling distribution in shape (n + 1,). The first and last element constituting the empty and full subsets are not used.

Return type:

tuple[list, list, int]

Returns:

complete subsets, incomplete subsets, remaining budget

Examples

>>> split_subsets_budget(order=1, n=6, budget=100, sampling_weights=np.ones(shape=(6,)))
([1, 5, 2, 4, 3], [], 38)

>>> split_subsets_budget(order=1, n=6, budget=60, sampling_weights=np.ones(shape=(6,)))
([1, 5, 2, 4], [3], 18)

>>> split_subsets_budget(order=1, n=6, budget=100, sampling_weights=np.zeros(shape=(6,)))
([], [1, 2, 3, 4, 5], 100)

shapiq.utils.transform_array_to_coalitions(coalitions)[source]#

Transforms a 2d one-hot matrix of coalitions into a list of tuples.

Parameters:: coalitions (ndarray) – A binary array of coalitions.
Return type:: list[tuple[int]]
Returns:: List of coalitions as tuples.

Examples

>>> coalitions = np.array([[True, True, False], [False, True, True], [True, False, True]])
>>> transform_array_to_coalitions(coalitions)
[(0, 1), (1, 2), (0, 2)]

>>> coalitions = np.array([[False, False, False], [True, True, True]])
>>> transform_array_to_coalitions(coalitions)
[(), (0, 1, 2)]

shapiq.utils.transform_coalitions_to_array(coalitions, n_players=None)[source]#

Transforms a collection of coalitions to a binary array (one-hot encodings).

Parameters:

coalitions (Collection[tuple[int]]) – Collection of coalitions.
n_players (Optional[int]) – Number of players. Defaults to None (determined from the coalitions). If provided, n_players must be greater than the maximum player index in the coalitions.

Return type:

ndarray

Returns:

Binary array of coalitions.

Example

>>> coalitions = [(0, 1), (1, 2), (0, 2)]
>>> transform_coalitions_to_array(coalitions)
array([[ True,  True, False],
       [False,  True,  True],
       [ True, False,  True]])

>>> transform_coalitions_to_array(coalitions, n_players=4)
array([[ True,  True, False, False],
       [False,  True,  True, False],
       [ True, False,  True, False]])

shapiq.utils.try_import(name, package=None)[source]#

Try to import a module and return None if it fails.

Note

Solution adapted from [stack overflow](https://stackoverflow.com/a/53241197).

Parameters:

name (str) – The name of the module to import.
package (Optional[str]) – The package to import the module from.

Return type:

Optional[ModuleType]

Returns:

The imported module or None if the import fails.

Modules

`shapiq.utils.modules`
`shapiq.utils.sets`	This module contains utility functions for dealing with sets, coalitions and game theory.
`shapiq.utils.types`	This module contains all custom types used in the shapiq package.