Add Game.compute function and related test to the Game class (mmschlk#397)

* add compute() function and related test to the Game class

* adjust compute()

* add function and test to generate interaction lookup from coalition

* fix lookup generation from coalitions

* adjusted return type

* checks that compute is not normalized in test

* add to CHANGELOG.md

---------

Co-authored-by: Maximilian <[email protected]>

Author: IsaH57

CHANGELOG.md

@@ -10,6 +10,7 @@
 - adds ``verbose`` parameter to the ``Explainer``'s ``explain_X()`` method to control weather a progress bar is shown or not which is defaulted to ``False``. [#391](https://github.com/mmschlk/shapiq/pull/391)
 - made `InteractionValues.get_n_order()` and `InteractionValues.get_n_order_values()` function more efficient by iterating over the stored interactions and not over the powerset of all potential interactions, which made the function not usable for higher player counts (models with many features, and results obtained from `TreeExplainer`). Note, this change does not really help `get_n_order_values()` as it still needs to create a numpy array of shape `n_players` times `order` [#372](https://github.com/mmschlk/shapiq/pull/372)
 - streamlined the ``network_plot()`` plot function to use the ``si_graph_plot()`` as its backend function. This allows for more flexibility in the plot function and makes it easier to use the same code for different purposes. In addition, the ``si_graph_plot`` was modified to make plotting more easy and allow for more flexibility with new parameters. [#349](https://github.com/mmschlk/shapiq/pull/349)
+- adds `Game.compute()` method to the `shapiq.Game` class to compute game values without changing the state of the game object. The compute method also introduces a `shapiq.utils.sets.generate_interaction_lookup_from_coalitions()` utility method which creates an interaction lookup dict from an array of coalitions. [#397](https://github.com/mmschlk/shapiq/pull/397)
 
 #### Testing, Code-Quality and Documentation
 - activates ``"ALL"`` rules in ``ruff-format`` configuration to enforce stricter code quality checks and addressed around 500 (not automatically solvable) issues in the code base. [#391](https://github.com/mmschlk/shapiq/pull/391)

shapiq/games/base.py

@@ -419,6 +419,35 @@ 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:
+            - The computed game values in the same order of the coalitions.
+            - A lookup dictionary mapping from coalitions to the indices in the array.
+            - The normalization value used to center/normalize the game values.
+
+        Note:
+            This method does not change the state of the game and does not normalize the values.
+
+        Examples:
+            >>> from shapiq.games.benchmark import DummyGame
+            >>> game = DummyGame(4, interaction=(1, 2))
+            >>> game.compute(np.array([[0, 1, 0, 0], [0, 1, 1, 0]], dtype=bool))
+            (array([0.25, 1.5]), {(1): 0, (1, 2): 1.5}, 0.0)
+
+        """
+        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,27 @@ 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)  # number of coalitions is correct
+    assert result[2] == normalization_value
+    assert len(result) == 3  # game_values, normalization_value and coalition_lookup
+
+    # check if the game values are correct and that they are not normalized from compute
+    game_values = result[0]
+    assert game(coalitions[0]) + normalization_value == pytest.approx(game_values[0])
+    assert game(coalitions[1]) + normalization_value == pytest.approx(game_values[1])

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"),
     [