18754124332

Committed 23 Oct 2025 03:48PM UTC coverage: 92.865% (-0.2%) from 93.032%

Build # 18754124332

Build Type

Pull #431

github

Committed by

web-flow

Commit Message

Merge e4a9a83cb into 830c6bc23

Pull Request Pull Request #431: Product kernel explainer

Run Details

186 of 210 new or added lines in 13 files covered. (88.57%)

2 existing lines in 1 file now uncovered.

5375 of 5788 relevant lines covered (92.86%)

0.93 hits per line

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

90.91

/src/shapiq/explainer/product_kernel/explainer.py

"""Implementation of the ProductKernelExplainer class."""

from __future__ import annotations

from typing import TYPE_CHECKING, Any

from shapiq import InteractionValues
from shapiq.explainer.base import Explainer
from shapiq.game_theory import get_computation_index

from .product_kernel import ProductKernelComputer, ProductKernelSHAPIQIndices
from .validation import validate_pk_model

if TYPE_CHECKING:
    import numpy as np

    from shapiq.typing import Model

    from .base import ProductKernelModel


class ProductKernelExplainer(Explainer):
    """The ProductKernelExplainer class for product kernel-based models.

    The ProductKernelExplainer can be used with a variety of product kernel-based models. The explainer can handle both regression and
    classification models. See [pkex-shapley]_ for details.


    References:
        .. [pkex-shapley] Majid Mohammadi and Siu Lun Chau, Krikamol Muandet. (2025). Computing Exact Shapley Values in Polynomial Time for Product-Kernel Methods. https://arxiv.org/abs/2505.16516

    Attributes:
        model: The product kernel model to explain. Can be a dictionary, a ProductKernelModel, or a list of ProductKernelModels.
        max_order: The maximum interaction order to be computed. Defaults to ``1``.
        min_order: The minimum interaction order to be computed. Defaults to ``0``.
        index: The type of interaction to be computed. Currently, only ``"SV"`` is supported.

    Note:
        When explaining classification models, the class which is explained equals the predicted class of the model.
        For further details, consult [pkex-shapley]_ .
    """

    def __init__(
        self,
        model: (
            ProductKernelModel | Model  # pyright: ignore[reportInvalidTypeVarUse]
        ),
        *,
        min_order: int = 0,
        max_order: int = 1,
        index: ProductKernelSHAPIQIndices = "SV",
        **kwargs: Any,  # noqa: ARG002
    ) -> None:
        """Initializes the ProductKernelExplainer.

        Args:
            model: A product kernel-based model to explain.

            min_order: The minimum interaction order to be computed. Defaults to ``0``.

            max_order: The maximum interaction order to be computed. An interaction order of ``1``
                corresponds to the Shapley value. Defaults to ``1``.

            index: The type of interaction to be computed. Currently, only ``"SV"`` is supported.

            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.

            **kwargs: Additional keyword arguments are ignored.

        """
        if max_order > 1:
            msg = "ProductKernelExplainer currently only supports max_order=1."
            raise ValueError(msg)

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

        self._min_order = min_order
        self._max_order = max_order

        self._index = index
        self._base_index: str = get_computation_index(self._index)

        # validate model
        self.converted_model = validate_pk_model(model)

        self.explainer = ProductKernelComputer(
            model=self.converted_model,
            max_order=max_order,
            index=index,
        )

        self.empty_prediction = self._compute_baseline_value()

    def explain_function(
        self,
        x: np.ndarray,
        **kwargs: Any,  # noqa: ARG002
    ) -> InteractionValues:
        """Compute Shapley values for all features of an instance.

        Args:
           x: The instance (1D array) for which to compute Shapley values.
           **kwargs: Additional keyword arguments are ignored.

        Returns:
           The interaction values for the instance.
        """
        n_players = self.converted_model.d

        # compute the kernel vectors for the instance x
        kernel_vectors = self.explainer.compute_kernel_vectors(self.converted_model.X_train, x)

        shapley_values = {}
        for j in range(self.converted_model.d):
            shapley_values.update({(j,): self.explainer.compute_shapley_value(kernel_vectors, j)})

        return InteractionValues(
            values=shapley_values,
            index=self._base_index,
            min_order=self._min_order,
            max_order=self.max_order,
            n_players=n_players,
            estimated=False,
            baseline_value=self.empty_prediction,
            target_index=self._index,
        )

    def _compute_baseline_value(self) -> float:
        """Computes the baseline value for the explainer.

        Returns:
            The baseline value for the explainer.

        """
        return self.converted_model.alpha.sum() + self.converted_model.intercept

1	"""Implementation of the ProductKernelExplainer class."""
2
3	from __future__ import annotations	1✔
4
5	from typing import TYPE_CHECKING, Any	1✔
6
7	from shapiq import InteractionValues	1✔
8	from shapiq.explainer.base import Explainer	1✔
9	from shapiq.game_theory import get_computation_index	1✔
10
11	from .product_kernel import ProductKernelComputer, ProductKernelSHAPIQIndices	1✔
12	from .validation import validate_pk_model	1✔
13
14	if TYPE_CHECKING:	1✔
NEW 15	import numpy as np	×
16
NEW 17	from shapiq.typing import Model	×
18
NEW 19	from .base import ProductKernelModel	×
20
21
22	class ProductKernelExplainer(Explainer):	1✔
23	"""The ProductKernelExplainer class for product kernel-based models.
24
25	The ProductKernelExplainer can be used with a variety of product kernel-based models. The explainer can handle both regression and
26	classification models. See [pkex-shapley]_ for details.
27
28
29	References:
30	.. [pkex-shapley] Majid Mohammadi and Siu Lun Chau, Krikamol Muandet. (2025). Computing Exact Shapley Values in Polynomial Time for Product-Kernel Methods. https://arxiv.org/abs/2505.16516
31
32	Attributes:
33	model: The product kernel model to explain. Can be a dictionary, a ProductKernelModel, or a list of ProductKernelModels.
34	max_order: The maximum interaction order to be computed. Defaults to ``1``.
35	min_order: The minimum interaction order to be computed. Defaults to ``0``.
36	index: The type of interaction to be computed. Currently, only ``"SV"`` is supported.
37
38	Note:
39	When explaining classification models, the class which is explained equals the predicted class of the model.
40	For further details, consult [pkex-shapley]_ .
41	"""
42
43	def __init__(	1✔
44	self,
45	model: (
46	ProductKernelModel \| Model # pyright: ignore[reportInvalidTypeVarUse]
47	),
48	*,
49	min_order: int = 0,
50	max_order: int = 1,
51	index: ProductKernelSHAPIQIndices = "SV",
52	**kwargs: Any, # noqa: ARG002
53	) -> None:
54	"""Initializes the ProductKernelExplainer.
55
56	Args:
57	model: A product kernel-based model to explain.
58
59	min_order: The minimum interaction order to be computed. Defaults to ``0``.
60
61	max_order: The maximum interaction order to be computed. An interaction order of ``1``
62	corresponds to the Shapley value. Defaults to ``1``.
63
64	index: The type of interaction to be computed. Currently, only ``"SV"`` is supported.
65
66	class_index: The class index of the model to explain. Defaults to ``None``, which will
67	set the class index to ``1`` per default for classification models and is ignored
68	for regression models.
69
70	**kwargs: Additional keyword arguments are ignored.
71
72	"""
73	if max_order > 1:	1✔
74	msg = "ProductKernelExplainer currently only supports max_order=1."	1✔
75	raise ValueError(msg)	1✔
76
77	super().__init__(model, index=index, max_order=max_order)	1✔
78
79	self._min_order = min_order	1✔
80	self._max_order = max_order	1✔
81
82	self._index = index	1✔
83	self._base_index: str = get_computation_index(self._index)	1✔
84
85	# validate model
86	self.converted_model = validate_pk_model(model)	1✔
87
88	self.explainer = ProductKernelComputer(	1✔
89	model=self.converted_model,
90	max_order=max_order,
91	index=index,
92	)
93
94	self.empty_prediction = self._compute_baseline_value()	1✔
95
96	def explain_function(	1✔
97	self,
98	x: np.ndarray,
99	**kwargs: Any, # noqa: ARG002
100	) -> InteractionValues:
101	"""Compute Shapley values for all features of an instance.
102
103	Args:
104	x: The instance (1D array) for which to compute Shapley values.
105	**kwargs: Additional keyword arguments are ignored.
106
107	Returns:
108	The interaction values for the instance.
109	"""
110	n_players = self.converted_model.d	1✔
111
112	# compute the kernel vectors for the instance x
113	kernel_vectors = self.explainer.compute_kernel_vectors(self.converted_model.X_train, x)	1✔
114
115	shapley_values = {}	1✔
116	for j in range(self.converted_model.d):	1✔
117	shapley_values.update({(j,): self.explainer.compute_shapley_value(kernel_vectors, j)})	1✔
118
119	return InteractionValues(	1✔
120	values=shapley_values,
121	index=self._base_index,
122	min_order=self._min_order,
123	max_order=self.max_order,
124	n_players=n_players,
125	estimated=False,
126	baseline_value=self.empty_prediction,
127	target_index=self._index,
128	)
129
130	def _compute_baseline_value(self) -> float:	1✔
131	"""Computes the baseline value for the explainer.
132
133	Returns:
134	The baseline value for the explainer.
135
136	"""
137	return self.converted_model.alpha.sum() + self.converted_model.intercept	1✔

mmschlk / shapiq / 18754124332

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