refactor: add conversion from/to array into InteractionValues object

Author: Zaphoood

docs/source/notebooks/tabular_notebooks/data_valuation.ipynb

@@ -7,19 +7,18 @@
 
 import numpy as np
 
+from shapiq import InteractionValues
 from shapiq.explainer.nn.base import NNExplainerBase
 
 from ._util import (
     assert_valid_index_and_order,
     warn_ignored_parameters,
 )
-from .iv_utils import interaction_values_from_array
 
 if TYPE_CHECKING:
     import numpy.typing as npt
     from sklearn.neighbors import KNeighborsClassifier
 
-    from shapiq import InteractionValues
     from shapiq.explainer.custom_types import ExplainerIndices
 
 
@@ -79,4 +78,4 @@ def explain_function(self, x: npt.NDArray[np.floating]) -> InteractionValues:
         inv_sortperm = np.zeros_like(sortperm)
         inv_sortperm[sortperm] = np.arange(sortperm.shape[0])
 
-        return interaction_values_from_array(sv[inv_sortperm])
+        return InteractionValues.from_first_order_array(sv[inv_sortperm], index="SV")

src/shapiq/explainer/nn/knn.py

@@ -13,16 +13,14 @@
     import sklearn.neighbors
     from sklearn.neighbors import RadiusNeighborsClassifier
 
-    from shapiq import InteractionValues
     from shapiq.explainer.custom_types import ExplainerIndices
-
+from shapiq import InteractionValues
 
 from ._util import (
     assert_valid_index_and_order,
     warn_ignored_parameters,
 )
 from .base import NNExplainerBase
-from .iv_utils import interaction_values_from_array
 
 
 class ThresholdNNExplainer(NNExplainerBase):
@@ -104,4 +102,4 @@ def explain_function(self, x: npt.NDArray[np.floating]) -> InteractionValues:
 
         sv = first_summand + second_summand
 
-        return interaction_values_from_array(sv)
+        return InteractionValues.from_first_order_array(sv, index="SV")

src/shapiq/explainer/nn/threshold_nn.py

@@ -8,18 +8,17 @@
 from shapiq.explainer.nn.base import NNExplainerBase
 
 from ._util import assert_valid_index_and_order, warn_ignored_parameters
-from .iv_utils import interaction_values_from_array
 
 if TYPE_CHECKING:
     import numpy.typing as npt
     from sklearn.neighbors import KNeighborsClassifier
 
     from shapiq.explainer.custom_types import ExplainerIndices
-    from shapiq.interaction_values import InteractionValues
-
 import numpy as np
 from scipy.special import comb
 
+from shapiq.interaction_values import InteractionValues
+
 
 class WeightedKNNExplainer(NNExplainerBase):
     r"""Explainer for weighted KNN models.
@@ -82,7 +81,9 @@ def explain_function(self, x: npt.NDArray[np.floating]) -> InteractionValues:
 
         n_classes = len(self.y_train_classes)
         if n_classes == 1:
-            return interaction_values_from_array(np.full(n_players, 1 / n_players))
+            return InteractionValues.from_first_order_array(
+                np.full(n_players, 1 / n_players), index="SV"
+            )
 
         sortperm, weights = self._get_prepared_weights(x)
 
@@ -91,7 +92,7 @@ def explain_function(self, x: npt.NDArray[np.floating]) -> InteractionValues:
             sv += self._explain_binary(other_class_index, sortperm, weights)
         sv /= n_classes - 1
 
-        return interaction_values_from_array(sv)
+        return InteractionValues.from_first_order_array(sv, index="SV")
 
     def _explain_binary(
         self,

src/shapiq/explainer/nn/weighted_knn.py

@@ -119,6 +119,8 @@
 
 AllIndices: tuple[IndexType, ...] = tuple(get_args(IndexType))
 
+FIRST_ORDER_INDICES = ["SV", "BV", "JointSV"]
+
 
 def is_index_valid(index: str, *, raise_error: bool = False) -> bool:
     """Checks if the given index is a valid interaction index.
@@ -300,3 +302,24 @@ def is_empty_value_the_baseline(index: str) -> bool:
 
     """
     return index not in ["SII", "FBII", "BII", "BV"]
+
+
+def is_first_order(index: str, *, raise_error: bool = False) -> bool:
+    """Check if the index represents only first-order interactions.
+
+    Args:
+        index: The interaction index.
+        raise_error: If ``True``, raises a ``ValueError`` if the index is not first-order
+
+    Returns:
+        ``True`` if the index is a first-order index, ``False`` otherwise.
+    """
+    first_order = index in FIRST_ORDER_INDICES
+    if not first_order and raise_error:
+        msg = (
+            f"Expected first-order index but got '{index}'. First-order indices are: "
+            + ", ".join(FIRST_ORDER_INDICES)
+        )
+        raise ValueError(msg)
+
+    return first_order

src/shapiq/game_theory/indices.py

@@ -16,6 +16,7 @@
     AllIndices,
     get_index_from_computation_index,
     is_empty_value_the_baseline,
+    is_first_order,
     is_index_aggregated,
     is_index_valid,
 )
@@ -924,6 +925,61 @@ def to_dict(self) -> dict:
             "baseline_value": self.baseline_value,
         }
 
+    @classmethod
+    def from_first_order_array(
+        cls, first_order_values: np.ndarray, index: str, baseline_value: float = 0
+    ) -> InteractionValues:
+        """Convert an array of first-order values to an :class:`shapiq.InteractionValues` object.
+
+        Args:
+            first_order_values: An array containing the value of the ith training point at index i.
+            index: The game theoretic index of the resulting :class:`shapiq.InteractionValues` object. Must be a
+                first-order index.
+            baseline_value: Baseline value, defaults to ``0``.
+
+        Returns:
+            An :class:`~shapiq.InteractionValues` object containing the provided values.
+
+        Raises:
+            ValueError: If the provided ``index`` is not a first-order index.
+        """
+        is_first_order(index, raise_error=True)
+
+        n_players = first_order_values.shape[0]
+        interaction_lookup: dict[tuple[int, ...], int] = {(i,): i for i in range(n_players)}
+
+        return InteractionValues(
+            first_order_values,
+            index=index,
+            min_order=0,
+            max_order=1,
+            n_players=n_players,
+            baseline_value=baseline_value,
+            interaction_lookup=interaction_lookup,
+        )
+
+    def to_first_order_array(self) -> np.ndarray:
+        """Convert to an array of first-order values.
+
+        Returns:
+            An array of shape ``(self.n_players,)`` containing at index ``i`` the first-order value of player ``i``.
+
+        Raises:
+            RuntimeError: If the method was called on an :class:`~shapiq.InteractionValues` object with max order
+                not equal to ``1``.
+        """
+        if self.max_order != 1:
+            msg = f"Max order must be 1 but was {self.max_order}"
+            raise ValueError(msg)
+
+        out = np.zeros((self.n_players,))
+        for coalition, lookup_idx in self.interaction_lookup.items():
+            if coalition == ():
+                continue
+            out[coalition[0]] = self.values[lookup_idx]
+
+        return out
+
     def aggregate(
         self,
         others: Sequence[InteractionValues],