Add Game.compute function and related test to the Game class

shapiq/games/base.py

@@ -419,6 +419,26 @@ def precompute(self, coalitions: np.ndarray | None = None) -> None:
         self.coalition_lookup = coalitions_dict
         self.precompute_flag = True
 
+    def compute(
+        self, coalitions: np.ndarray | None = None
+    ) -> tuple[np.ndarray, dict[tuple[int, ...], int], float]:
+        """Compute the game values for all or a given set of coalitions.
+
+        Args:
+            coalitions: The coalitions to evaluate.
+
+        Returns:
+            A tuple containing:
+            - np.ndarray: The values of the coalitions.
+            - dict[tuple[int, ...], int]: The lookup of the coalitions
+            - float: The normalization value (optional, if return_normalization is 'True')
+
+        """
+        coalitions: np.ndarray = self._check_coalitions(coalitions)
+        game_values = self.value_function(coalitions)
+
+        return game_values, self.coalition_lookup, self.normalization_value
+
     def save_values(self, path: Path | str) -> None:
         """Saves the game values to the given path.
 

shapiq/utils/__init__.py

@@ -6,6 +6,7 @@
 from .sets import (
     count_interactions,
     generate_interaction_lookup,
+    generate_interaction_lookup_from_coalitions,
     get_explicit_subsets,
     pair_subset_sizes,
     powerset,
@@ -23,6 +24,7 @@
     "split_subsets_budget",
     "get_explicit_subsets",
     "generate_interaction_lookup",
+    "generate_interaction_lookup_from_coalitions",
     "transform_coalitions_to_array",
     "transform_array_to_coalitions",
     "count_interactions",

shapiq/utils/sets.py

@@ -232,6 +232,31 @@ def generate_interaction_lookup(
     }
 
 
+def generate_interaction_lookup_from_coalitions(
+    coalitions: np.ndarray,
+) -> dict[tuple[Any, ...], int]:
+    """Generates a lookup dictionary for interactions based on an array of coalitions.
+
+    Args:
+        coalitions: An array of player coalitions.
+
+    Returns:
+        A dictionary that maps interactions to their index in the values vector
+
+    Example:
+        >>> coalitions = np.array([
+        ...     [1, 0, 1],
+        ...     [0, 1, 1],
+        ...     [1, 1, 0],
+        ...     [0, 0, 1]
+        ... ])
+        >>> generate_interaction_lookup_from_coalitions(coalitions)
+        {(0, 2): 0, (1, 2): 1, (0, 1): 2, (2,): 3}
+
+    """
+    return {tuple(np.where(coalition)[0]): idx for idx, coalition in enumerate(coalitions)}
+
+
 def transform_coalitions_to_array(
     coalitions: Collection[tuple[int, ...]],
     n_players: int | None = None,

tests/tests_games/test_base_game.py

@@ -326,3 +326,22 @@ def test_exact_computer_call():
     sv = game.exact_values(index=index, order=order)
     assert sv.index == index
     assert sv.max_order == order
+
+
+def test_compute():
+    """Tests the compute function with and without returned normalization."""
+    normalization_value = 1.0  # not zero
+
+    n_players = 3
+    game = DummyGame(n=n_players, interaction=(0, 1))
+
+    coalitions = np.array([[1, 0, 0], [0, 1, 1]])
+
+    # Make sure normalization value is added
+    game.normalization_value = normalization_value
+    assert game.normalize
+
+    result = game.compute(coalitions=coalitions)
+    assert len(result[0]) == len(coalitions)
+    assert result[2] == 1.0  # normalization_value
+    assert len(result) == 3  # game_values, normalization_value and coalition_lookup

tests/tests_utils/test_utils_sets.py

@@ -8,6 +8,7 @@
 from shapiq.utils import (
     count_interactions,
     generate_interaction_lookup,
+    generate_interaction_lookup_from_coalitions,
     get_explicit_subsets,
     pair_subset_sizes,
     powerset,
@@ -110,6 +111,37 @@ def test_generate_interaction_lookup(n, min_order, max_order, expected):
     assert generate_interaction_lookup(n, min_order, max_order) == expected
 
 
+@pytest.mark.parametrize(
+    ("coalitions", "expected"),
+    [
+        (
+            np.array([[1, 0, 1], [0, 1, 1], [1, 1, 0], [0, 0, 1]]),
+            {(0, 2): 0, (1, 2): 1, (0, 1): 2, (2,): 3},
+        ),
+        (
+            np.array([[1, 1, 1], [0, 1, 0], [1, 0, 0], [0, 0, 1]]),
+            {(0, 1, 2): 0, (1,): 1, (0,): 2, (2,): 3},
+        ),
+        (
+            np.array([[1, 0, 0], [0, 1, 0], [0, 0, 1]]),
+            {(0,): 0, (1,): 1, (2,): 2},
+        ),
+        (
+            np.array([[1, 1, 0, 1], [0, 0, 1, 1], [1, 0, 1, 0]]),
+            {(0, 1, 3): 0, (2, 3): 1, (0, 2): 2},
+        ),
+        (
+            np.array([[0, 0, 0], [1, 1, 1]]),
+            {(): 0, (0, 1, 2): 1},
+        ),
+    ],
+)
+def test_generate_interaction_lookup_from_coalitions(coalitions, expected):
+    """Tests the generate_interaction_lookup_from_coalitions function."""
+    result = generate_interaction_lookup_from_coalitions(coalitions)
+    assert result == expected
+
+
 @pytest.mark.parametrize(
     ("coalitions", "n_player", "expected"),
     [