shapiq.approximator.shapiq#

This module contains the shapiq estimator to approximate all cardinal interaction indices.

class shapiq.approximator.shapiq.ShapIQ(n, max_order, index='SII', top_order=False, random_state=None)[source]#

Bases: Approximator, ShapleySamplingMixin, KShapleyMixin

The ShapIQ estimator.

Parameters:

n (int) – The number of players.
max_order (int) – The interaction order of the approximation.
index (str) – The index to approximate. Defaults to “SII”.
top_order (bool) – Whether to approximate only the top order interactions (True) or all orders up to the specified order (False). Defaults to False.
random_state (Optional[int]) – The random state to use for the permutation sampling. Defaults to None.

n#: The number of players.

max_order#: The interaction order of the approximation.

index#: The index to approximate.

top_order#: Whether to approximate only the top order interactions (True) or all orders up to the specified order (False).

min_order#: The minimum order to approximate.

iteration_cost#: The cost of a single iteration of the permutation sampling.

Example

>>> from games import DummyGame
>>> from approximator import ShapIQ
>>> game = DummyGame(n=5, interaction=(1, 2))
>>> approximator = ShapIQ(n=5, max_order=2, index="SII")
>>> approximator.approximate(budget=50, game=game)
InteractionValues(
    index=SII, order=2, estimated=False, estimation_budget=32,
    values={
        (0,): 0.2,
        (1,): 0.7,
        (2,): 0.7,
        (3,): 0.2,
        (4,): 0.2,
        (0, 1): 0,
        (0, 2): 0,
        (0, 3): 0,
        (0, 4): 0,
        (1, 2): 1.0,
        (1, 3): 0,
        (1, 4): 0,
        (2, 3): 0,
        (2, 4): 0,
        (3, 4): 0
    }
)

approximate(budget, game, batch_size=None, pairing=True, replacement=True)[source]#

Approximates the interaction values using the ShapIQ estimator.

Parameters:

budget (int) – The budget for the approximation (i.e., the number of game evaluations).
game (Callable[[ndarray], ndarray]) – The game function as a callable that takes a set of players and returns the value.
batch_size (Optional[int]) – The size of the batch. If None, the batch size is set to budget. Defaults to None.
pairing (bool) – Whether to use pairwise sampling (True) or not (False). Defaults to True. Paired sampling can increase the approximation quality.
replacement (bool) – Whether to sample with replacement (True) or without replacement (False). Defaults to True.

Return type:

InteractionValues

Returns:

The estimated interaction values.

class shapiq.approximator.shapiq.UnbiasedKernelSHAP(n, random_state=None)[source]#

Bases: ShapIQ

The Unbiased KernelSHAP approximator for estimating the Shapley value (SV).

The Unbiased KernelSHAP estimator is a variant of the KernelSHAP estimator (though deeply different). Unbiased KernelSHAP was proposed in Covert and Lee’s [original paper](http://proceedings.mlr.press/v130/covert21a/covert21a.pdf) as an unbiased version of KernelSHAP. Recently, in Fumagalli et al.’s [paper](https://proceedings.neurips.cc/paper_files/paper/2023/hash/264f2e10479c9370972847e96107db7f-Abstract-Conference.html), it was shown that Unbiased KernelSHAP is a more specific variant of the ShapIQ approximation method (Theorem 4.5).

Parameters:

n (int) – The number of players.
random_state (Optional[int]) – The random state of the estimator. Defaults to None.

Example

>>> from shapiq.games import DummyGame
>>> from shapiq.approximator import UnbiasedKernelSHAP
>>> game = DummyGame(n=5, interaction=(1, 2))
>>> approximator = UnbiasedKernelSHAP(n=5)
>>> approximator.approximate(budget=100, game=game)
InteractionValues(
    index=SV, order=1, estimated=False, estimation_budget=32,
    values={
        (0,): 0.2,
        (1,): 0.7,
        (2,): 0.7,
        (3,): 0.2,
        (4,): 0.2,
    }
)

Modules

`shapiq.approximator.shapiq.shapiq`	This module contains the shapiq estimator.
`shapiq.approximator.shapiq.unbiased_kernelshap`	This module contains the Unbiased KernelSHAP approximation method for the Shapley value (SV).