shapiq.utils.sets#
This module contains utility functions for dealing with sets, coalitions and game theory.
Functions
|
Generates a lookup dictionary for interactions. |
|
Enumerates all subsets of the given sizes and returns a one-hot matrix. |
|
Determines what subset sizes are paired together. |
|
Return a powerset of an iterable as tuples with optional size limits. |
|
Determines which subset sizes can be computed explicitly and which sizes need to be sampled. |
|
Transforms a 2d one-hot matrix of coalitions into a list of tuples. |
|
Transforms a collection of coalitions to a binary array (one-hot encodings). |
- shapiq.utils.sets.generate_interaction_lookup(players, min_order, max_order)[source]#
Generates a lookup dictionary for interactions.
- Parameters:
- Return type:
- 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.sets.get_explicit_subsets(n, subset_sizes)[source]#
Enumerates all subsets of the given sizes and returns a one-hot matrix.
- Parameters:
- Return type:
- 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.sets.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:
- Return type:
- 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.sets.powerset(iterable, min_size=0, max_size=None)[source]#
Return a powerset of an iterable as tuples with optional size limits.
- Parameters:
- 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.sets.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:
- Return type:
- 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.sets.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:
- 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.sets.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:
- 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]])