17613931038

Committed 10 Sep 2025 12:36PM UTC coverage: 93.646% (-0.2%) from 93.845%

Build # 17613931038

Build Type

Pull #431

github

Committed by

web-flow

Commit Message

Merge 0344967e6 into dede390c9

Pull Request Pull Request #431: Product kernel explainer

Run Details

180 of 203 new or added lines in 14 files covered. (88.67%)

4 existing lines in 2 files now uncovered.

5099 of 5445 relevant lines covered (93.65%)

0.94 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

85.71

/src/shapiq/explainer/tabular.py

"""Tabular Explainer class for the shapiq package."""

from __future__ import annotations

from typing import TYPE_CHECKING, Any, Literal
from warnings import warn

from overrides import overrides

from shapiq.explainer.base import Explainer
from shapiq.game_theory.indices import is_empty_value_the_baseline

from .configuration import setup_approximator
from .custom_types import ExplainerIndices

if TYPE_CHECKING:
    import numpy as np

    from shapiq.approximator.base import Approximator
    from shapiq.imputer.base import Imputer
    from shapiq.interaction_values import InteractionValues
    from shapiq.typing import Model


TabularExplainerApproximators = Literal["spex", "montecarlo", "svarm", "permutation", "regression"]
TabularExplainerImputers = Literal["marginal", "baseline", "conditional"]
TabularExplainerIndices = ExplainerIndices


class TabularExplainer(Explainer):
    """The tabular explainer as the main interface for the shapiq package.

    The ``TabularExplainer`` class is the main interface for the ``shapiq`` package and tabular
    data. It can be used to explain the predictions of any model by estimating the Shapley
    interaction values.

    Attributes:
        index: Type of Shapley interaction index to use.
        data: A background data to use for the explainer.

    Properties:
        baseline_value: A baseline value of the explainer.

    """

    def __init__(
        self,
        model: Model,
        data: np.ndarray,
        *,
        class_index: int | None = None,
        imputer: Imputer | TabularExplainerImputers = "marginal",
        approximator: (Literal["auto"] | TabularExplainerApproximators | Approximator) = "auto",
        index: TabularExplainerIndices = "k-SII",
        max_order: int = 2,
        random_state: int | None = None,
        verbose: bool = False,
        **kwargs: Any,
    ) -> None:
        """Initializes the TabularExplainer.

        Args:
            model: The model to be explained as a callable function expecting data points as input
                and returning 1-dimensional predictions.

            data: A background dataset to be used for imputation.

            class_index: The class index of the model to explain. Defaults to ``None``, which will
                set the class index to ``1`` per default for classification models and is ignored
                for regression models.

            imputer: Either an :class:`~shapiq.games.imputer.Imputer` as implemented in the
                :mod:`~shapiq.games.imputer` module, or a literal string from
                ``["marginal", "baseline", "conditional"]``. Defaults to ``"marginal"``, which
                initializes the default
                :class:`~shapiq.games.imputer.marginal_imputer.MarginalImputer` with its default
                parameters or as provided in ``kwargs``.

            approximator: An :class:`~shapiq.approximator.Approximator` object to use for the
                explainer or a literal string from
                ``["auto", "spex", "montecarlo", "svarm", "permutation"]``. Defaults to ``"auto"``
                which will automatically choose the approximator based on the number of features and
                the desired index.
                    - for index ``"SV"``: :class:`~shapiq.approximator.KernelSHAP`
                    - for index ``"SII"`` or ``"k-SII"``: :class:`~shapiq.approximator.KernelSHAPIQ`
                    - for index ``"FSII"``: :class:`~shapiq.approximator.RegressionFSII`
                    - for index ``"FBII"``: :class:`~shapiq.approximator.RegressionFBII`
                    - for index ``"STII"``: :class:`~shapiq.approximator.SVARMIQ`

            index: The index to explain the model with. Defaults to ``"k-SII"`` which computes the
                k-Shapley Interaction Index. If ``max_order`` is set to 1, this corresponds to the
                Shapley value (``index="SV"``). Options are:
                    - ``"SV"``: Shapley value
                    - ``"k-SII"``: k-Shapley Interaction Index
                    - ``"FSII"``: Faithful Shapley Interaction Index
                    - ``"FBII"``: Faithful Banzhaf Interaction Index (becomes ``BV`` for order 1)
                    - ``"STII"``: Shapley Taylor Interaction Index
                    - ``"SII"``: Shapley Interaction Index

            max_order: The maximum interaction order to be computed. Defaults to ``2``. Set to
                ``1`` for no interactions (single feature importance).

            random_state: The random state to initialize Imputer and Approximator with. Defaults to
                ``None``.

            verbose: Whether to show a progress bar during the computation. Defaults to ``False``.

            **kwargs: Additional keyword-only arguments passed to the imputers implemented in
                :mod:`~shapiq.games.imputer`.
        """
        from shapiq.imputer import (
            BaselineImputer,
            ConditionalImputer,
            MarginalImputer,
            TabPFNImputer,
        )

        super().__init__(model, data, class_index, index=index, max_order=max_order)

        # get class for self
        class_name = self.__class__.__name__
        if self._model_type == "tabpfn" and class_name == "TabularExplainer":
            warn(
                "You are using a TabPFN model with the ``shapiq.TabularExplainer`` directly. This "
                "is not recommended as it uses missing value imputation and not contextualization. "
                "Consider using the ``shapiq.TabPFNExplainer`` instead. For more information see "
                "the documentation and the example notebooks.",
                stacklevel=2,
            )

        if imputer == "marginal":
            self.imputer = MarginalImputer(
                self.predict,
                self._data,
                random_state=random_state,
                **kwargs,
            )
        elif imputer == "conditional":
            self.imputer = ConditionalImputer(
                self.predict,
                self._data,
                random_state=random_state,
                **kwargs,
            )
        elif imputer == "baseline":
            self.imputer = BaselineImputer(
                self.predict,
                self._data,
                random_state=random_state,
                **kwargs,
            )
        elif isinstance(
            imputer,
            MarginalImputer | ConditionalImputer | BaselineImputer | TabPFNImputer,
        ):
            self.imputer = imputer
        else:
            msg = (
                f"Invalid imputer {imputer}. "
                f'Must be one of ["marginal", "baseline", "conditional"], or a valid Imputer '
                f"object."
            )
            raise ValueError(msg)
        self._n_features: int = self._data.shape[1]
        self.imputer.verbose = verbose  # set the verbose flag for the imputer

        self.approximator = setup_approximator(
            approximator, self._index, self._max_order, self._n_features, random_state
        )

    @overrides
    def explain_function(
        self,
        x: np.ndarray,
        budget: int,
        *,
        random_state: int | None = None,
    ) -> InteractionValues:
        """Explains the model's predictions.

        Args:
            x: The data point to explain as a 2-dimensional array with shape
                (1, n_features).

            budget: The budget to use for the approximation. It indicates how many coalitions are
                sampled, thus high values indicate more accurate approximations, but induce higher
                computational costs.

            random_state: The random state to re-initialize Imputer and Approximator with.
                Defaults to ``None``, which will not set a random state.

        Returns:
            An object of class :class:`~shapiq.interaction_values.InteractionValues` containing
            the computed interaction values.
        """
        self.set_random_state(random_state)

        # initialize the imputer with the explanation point
        self.imputer.fit(x)

        # explain
        interaction_values = self.approximator(budget=budget, game=self.imputer)
        interaction_values.baseline_value = self.baseline_value
        # Adjust the Baseline Value if the empty value is the baseline
        if is_empty_value_the_baseline(interaction_values.index):
            interaction_values[()] = interaction_values.baseline_value
        return interaction_values

    @property
    def baseline_value(self) -> float:
        """Returns the baseline value of the explainer."""
        return self.imputer.empty_prediction

1	"""Tabular Explainer class for the shapiq package."""
2
3	from __future__ import annotations	1✔
4
5	from typing import TYPE_CHECKING, Any, Literal	1✔
6	from warnings import warn	1✔
7
8	from overrides import overrides	1✔
9
10	from shapiq.explainer.base import Explainer	1✔
11	from shapiq.game_theory.indices import is_empty_value_the_baseline	1✔
12
13	from .configuration import setup_approximator	1✔
14	from .custom_types import ExplainerIndices	1✔
15
16	if TYPE_CHECKING:	1✔
17	import numpy as np	×
18
19	from shapiq.approximator.base import Approximator	×
20	from shapiq.imputer.base import Imputer	×
21	from shapiq.interaction_values import InteractionValues	×
22	from shapiq.typing import Model	×
23
24
25	TabularExplainerApproximators = Literal["spex", "montecarlo", "svarm", "permutation", "regression"]	1✔
26	TabularExplainerImputers = Literal["marginal", "baseline", "conditional"]	1✔
27	TabularExplainerIndices = ExplainerIndices	1✔
28
29
30	class TabularExplainer(Explainer):	1✔
31	"""The tabular explainer as the main interface for the shapiq package.
32
33	The ``TabularExplainer`` class is the main interface for the ``shapiq`` package and tabular
34	data. It can be used to explain the predictions of any model by estimating the Shapley
35	interaction values.
36
37	Attributes:
38	index: Type of Shapley interaction index to use.
39	data: A background data to use for the explainer.
40
41	Properties:
42	baseline_value: A baseline value of the explainer.
43
44	"""
45
46	def __init__(	1✔
47	self,
48	model: Model,
49	data: np.ndarray,
50	*,
51	class_index: int \| None = None,
52	imputer: Imputer \| TabularExplainerImputers = "marginal",
53	approximator: (Literal["auto"] \| TabularExplainerApproximators \| Approximator) = "auto",
54	index: TabularExplainerIndices = "k-SII",
55	max_order: int = 2,
56	random_state: int \| None = None,
57	verbose: bool = False,
58	**kwargs: Any,
59	) -> None:
60	"""Initializes the TabularExplainer.
61
62	Args:
63	model: The model to be explained as a callable function expecting data points as input
64	and returning 1-dimensional predictions.
65
66	data: A background dataset to be used for imputation.
67
68	class_index: The class index of the model to explain. Defaults to ``None``, which will
69	set the class index to ``1`` per default for classification models and is ignored
70	for regression models.
71
72	imputer: Either an :class:`~shapiq.games.imputer.Imputer` as implemented in the
73	:mod:`~shapiq.games.imputer` module, or a literal string from
74	``["marginal", "baseline", "conditional"]``. Defaults to ``"marginal"``, which
75	initializes the default
76	:class:`~shapiq.games.imputer.marginal_imputer.MarginalImputer` with its default
77	parameters or as provided in ``kwargs``.
78
79	approximator: An :class:`~shapiq.approximator.Approximator` object to use for the
80	explainer or a literal string from
81	``["auto", "spex", "montecarlo", "svarm", "permutation"]``. Defaults to ``"auto"``
82	which will automatically choose the approximator based on the number of features and
83	the desired index.
84	- for index ``"SV"``: :class:`~shapiq.approximator.KernelSHAP`
85	- for index ``"SII"`` or ``"k-SII"``: :class:`~shapiq.approximator.KernelSHAPIQ`
86	- for index ``"FSII"``: :class:`~shapiq.approximator.RegressionFSII`
87	- for index ``"FBII"``: :class:`~shapiq.approximator.RegressionFBII`
88	- for index ``"STII"``: :class:`~shapiq.approximator.SVARMIQ`
89
90	index: The index to explain the model with. Defaults to ``"k-SII"`` which computes the
91	k-Shapley Interaction Index. If ``max_order`` is set to 1, this corresponds to the
92	Shapley value (``index="SV"``). Options are:
93	- ``"SV"``: Shapley value
94	- ``"k-SII"``: k-Shapley Interaction Index
95	- ``"FSII"``: Faithful Shapley Interaction Index
96	- ``"FBII"``: Faithful Banzhaf Interaction Index (becomes ``BV`` for order 1)
97	- ``"STII"``: Shapley Taylor Interaction Index
98	- ``"SII"``: Shapley Interaction Index
99
100	max_order: The maximum interaction order to be computed. Defaults to ``2``. Set to
101	``1`` for no interactions (single feature importance).
102
103	random_state: The random state to initialize Imputer and Approximator with. Defaults to
104	``None``.
105
106	verbose: Whether to show a progress bar during the computation. Defaults to ``False``.
107
108	**kwargs: Additional keyword-only arguments passed to the imputers implemented in
109	:mod:`~shapiq.games.imputer`.
110	"""
111	from shapiq.imputer import (	1✔
112	BaselineImputer,
113	ConditionalImputer,
114	MarginalImputer,
115	TabPFNImputer,
116	)
117
118	super().__init__(model, data, class_index, index=index, max_order=max_order)	1✔
119
120	# get class for self
121	class_name = self.__class__.__name__	1✔
122	if self._model_type == "tabpfn" and class_name == "TabularExplainer":	1✔
123	warn(	1✔
124	"You are using a TabPFN model with the ``shapiq.TabularExplainer`` directly. This "
125	"is not recommended as it uses missing value imputation and not contextualization. "
126	"Consider using the ``shapiq.TabPFNExplainer`` instead. For more information see "
127	"the documentation and the example notebooks.",
128	stacklevel=2,
129	)
130
131	if imputer == "marginal":	1✔
132	self.imputer = MarginalImputer(	1✔
133	self.predict,
134	self._data,
135	random_state=random_state,
136	**kwargs,
137	)
138	elif imputer == "conditional":	1✔
139	self.imputer = ConditionalImputer(	1✔
140	self.predict,
141	self._data,
142	random_state=random_state,
143	**kwargs,
144	)
145	elif imputer == "baseline":	1✔
146	self.imputer = BaselineImputer(	1✔
147	self.predict,
148	self._data,
149	random_state=random_state,
150	**kwargs,
151	)
152	elif isinstance(	1✔
153	imputer,
154	MarginalImputer \| ConditionalImputer \| BaselineImputer \| TabPFNImputer,
155	):
156	self.imputer = imputer	1✔
157	else:
UNCOV 158	msg = (	×
159	f"Invalid imputer {imputer}. "
160	f'Must be one of ["marginal", "baseline", "conditional"], or a valid Imputer '
161	f"object."
162	)
UNCOV 163	raise ValueError(msg)	×
164	self._n_features: int = self._data.shape[1]	1✔
165	self.imputer.verbose = verbose # set the verbose flag for the imputer	1✔
166
167	self.approximator = setup_approximator(	1✔
168	approximator, self._index, self._max_order, self._n_features, random_state
169	)
170
171	@overrides	1✔
172	def explain_function(	1✔
173	self,
174	x: np.ndarray,
175	budget: int,
176	*,
177	random_state: int \| None = None,
178	) -> InteractionValues:
179	"""Explains the model's predictions.
180
181	Args:
182	x: The data point to explain as a 2-dimensional array with shape
183	(1, n_features).
184
185	budget: The budget to use for the approximation. It indicates how many coalitions are
186	sampled, thus high values indicate more accurate approximations, but induce higher
187	computational costs.
188
189	random_state: The random state to re-initialize Imputer and Approximator with.
190	Defaults to ``None``, which will not set a random state.
191
192	Returns:
193	An object of class :class:`~shapiq.interaction_values.InteractionValues` containing
194	the computed interaction values.
195	"""
196	self.set_random_state(random_state)	1✔
197
198	# initialize the imputer with the explanation point
199	self.imputer.fit(x)	1✔
200
201	# explain
202	interaction_values = self.approximator(budget=budget, game=self.imputer)	1✔
203	interaction_values.baseline_value = self.baseline_value	1✔
204	# Adjust the Baseline Value if the empty value is the baseline
205	if is_empty_value_the_baseline(interaction_values.index):	1✔
206	interaction_values[()] = interaction_values.baseline_value	1✔
207	return interaction_values	1✔
208
209	@property	1✔
210	def baseline_value(self) -> float:	1✔
211	"""Returns the baseline value of the explainer."""
212	return self.imputer.empty_prediction	1✔

mmschlk / shapiq / 17613931038

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous