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

91.18

/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.utils.custom_types 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.

    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.
        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.
    """

    def __init__(
        self,
        model: dict
        | ProductKernelModel
        | list[ProductKernelModel]
        | Model,  # TODO (IsaH57): check if list of models is needed (Issue #425)
        *,
        min_order: int = 0,
        max_order: int = 1,
        index: ProductKernelSHAPIQIndices = "SV",
        class_index: int | None = None,
        **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: int = min_order
        self._max_order: int = max_order

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

        self._class_label: int | None = class_index

        # validate model
        self.converted_model = validate_pk_model(model, class_label=class_index)

        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.utils.custom_types 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.
27
28	References:
29	-- [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
30
31	Attributes:
32	model: The product kernel model to explain. Can be a dictionary, a ProductKernelModel, or a list of ProductKernelModels.
33	max_order: The maximum interaction order to be computed. Defaults to ``1``.
34	min_order: The minimum interaction order to be computed. Defaults to ``0``.
35	index: The type of interaction to be computed. Currently, only ``"SV"`` is supported.
36	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.
37	"""
38
39	def __init__(	1✔
40	self,
41	model: dict
42	\| ProductKernelModel
43	\| list[ProductKernelModel]
44	\| Model, # TODO (IsaH57): check if list of models is needed (Issue #425)
45	*,
46	min_order: int = 0,
47	max_order: int = 1,
48	index: ProductKernelSHAPIQIndices = "SV",
49	class_index: int \| None = None,
50	**kwargs: Any, # noqa: ARG002
51	) -> None:
52	"""Initializes the ProductKernelExplainer.
53
54	Args:
55	model: A product kernel-based model to explain.
56
57	min_order: The minimum interaction order to be computed. Defaults to ``0``.
58
59	max_order: The maximum interaction order to be computed. An interaction order of ``1``
60	corresponds to the Shapley value. Defaults to ``1``.
61
62	index: The type of interaction to be computed. Currently, only ``"SV"`` is supported.
63
64	class_index: The class index of the model to explain. Defaults to ``None``, which will
65	set the class index to ``1`` per default for classification models and is ignored
66	for regression models.
67
68	**kwargs: Additional keyword arguments are ignored.
69
70	"""
71	if max_order > 1:	1✔
72	msg = "ProductKernelExplainer currently only supports max_order=1."	1✔
73	raise ValueError(msg)	1✔
74
75	super().__init__(model, index=index, max_order=max_order)	1✔
76
77	self._min_order: int = min_order	1✔
78	self._max_order: int = max_order	1✔
79
80	self._index: ProductKernelSHAPIQIndices = index	1✔
81	self._base_index: str = get_computation_index(self._index)	1✔
82
83	self._class_label: int \| None = class_index	1✔
84
85	# validate model
86	self.converted_model = validate_pk_model(model, class_label=class_index)	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 / 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