shapiq.approximator#

This module contains the approximators to estimate the Shapley interaction values.

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

Bases: Regression

Estimates the FSI values using the weighted least square approach.

Parameters:

  • n (int) – The number of players.

  • max_order – The interaction order of the approximation.

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

n#

The number of players.

N#

The set of players (starting from 0 to n - 1).

max_order#

The interaction order of the approximation.

min_order#

The minimum order of the approximation. For FSI, min_order is equal to 1.

iteration_cost#

The cost of a single iteration of the regression FSI.

Example

>>> from games import DummyGame
>>> from approximator import KernelSHAP
>>> game = DummyGame(n=5, interaction=(1, 2))
>>> approximator = KernelSHAP(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,
    }
)
class shapiq.approximator.PermutationSamplingSII(n, max_order, index='SII', top_order=False, random_state=None)[source]#

Bases: Approximator, KShapleyMixin

Permutation Sampling approximator for the SII (and k-SII) index.

Parameters:

  • n (int) – The number of players.

  • max_order (int) – The interaction order of the approximation.

  • top_order (bool) – Whether to approximate only the top order interactions (True) or all orders up to the specified order (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.

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 PermutationSamplingSII
>>> game = DummyGame(n=5, interaction=(1, 2))
>>> approximator = PermutationSamplingSII(n=5, max_order=2)
>>> approximator.approximate(budget=1_000, game=game)
InteractionValues(
    index=SII, order=2, estimated=True, estimation_budget=988,
    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=5)[source]#

Approximates the interaction values.

Parameters:

  • budget (int) – The budget for the approximation.

  • 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 1. Defaults to 5.

Returns:

The estimated interaction values.

Return type:

InteractionValues

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

Bases: Approximator

Permutation Sampling approximator for the Shapley Taylor Index (STI).

Parameters:

  • n (int) – The number of players.

  • max_order (int) – The interaction order of the approximation.

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

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 PermutationSamplingSTI
>>> game = DummyGame(n=5, interaction=(1, 2))
>>> approximator = PermutationSamplingSTI(n=5, max_order=2)
>>> approximator.approximate(budget=200, game=game)
InteractionValues(
    index=STI, order=2, estimated=True, estimation_budget=165,
    values={
        (0,): 0.2,
        (1,): 0.2,
        (2,): 0.2,
        (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=1)[source]#

Approximates the interaction values.

Parameters:

  • budget (int) – The budget for the approximation.

  • game (Callable[[ndarray], ndarray]) – The game function as a callable that takes a set of players and returns the value.

  • batch_size (int) – The size of the batch. If None, the batch size is set to 1. Defaults to 1.

Returns:

The estimated interaction values.

Return type:

InteractionValues

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

Bases: Regression, KShapleyMixin

Estimates the FSI values [1] using the weighted least square approach.

Parameters:

  • n (int) – The number of players.

  • max_order (int) – The interaction order of the approximation.

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

n#

The number of players.

N#

The set of players (starting from 0 to n - 1).

max_order#

The interaction order of the approximation.

min_order#

The minimum order of the approximation. For FSI, min_order is equal to 1.

iteration_cost#

The cost of a single iteration of the regression FSI.

References

[1]: Tsai, C.-P., Yeh, C.-K., & Ravikumar, P. (2023). Faith-Shap: The Faithful Shapley

Interaction Index. J. Mach. Learn. Res., 24, 94:1-94:42. Retrieved from http://jmlr.org/papers/v24/22-0202.html

Example

>>> from games import DummyGame
>>> from approximator import RegressionFSI
>>> game = DummyGame(n=5, interaction=(1, 2))
>>> approximator = RegressionFSI(n=5, max_order=2)
>>> approximator.approximate(budget=100, game=game)
InteractionValues(
    index=FSI, 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
    }
)
class shapiq.approximator.RegressionSII(n, max_order, random_state=None)[source]#

Bases: Regression, KShapleyMixin

Estimates the SII values using the weighted least square approach.

Parameters:

  • n (int) – The number of players.

  • max_order (int) – The interaction order of the approximation.

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

n#

The number of players.

N#

The set of players (starting from 0 to n - 1).

max_order#

The interaction order of the approximation.

min_order#

The minimum order of the approximation. For the regression estimator, min_order is equal to 1.

iteration_cost#

The cost of a single iteration of the regression SII.

Example

>>> from games import DummyGame
>>> from approximator import RegressionSII
>>> game = DummyGame(n=5, interaction=(1, 2))
>>> approximator = RegressionSII(n=5, max_order=2)
>>> approximator.approximate(budget=100, 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
    }
)
class shapiq.approximator.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.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,
    }
)
shapiq.approximator.convert_ksii_into_one_dimension(ksii_values)[source]#

Converts the k-SII values into one-dimensional values.

Parameters:

ksii_values (InteractionValues) – The k-SII values to convert.

Return type:

tuple[ndarray[float], ndarray[float]]

Returns:

The positive and negative one-dimensional values.

shapiq.approximator.transforms_sii_to_ksii(sii_values, *, approximator=None, n=None, max_order=None, interaction_lookup=None)[source]#

Transforms the SII values into k-SII values.

Parameters:

  • sii_values (Union[ndarray[float], InteractionValues]) – The SII values to transform. Can be either a numpy array or an InteractionValues object. The output will be of the same type.

  • approximator (Optional[Approximator]) – The approximator used to estimate the SII values. If provided, meta information for the transformation is taken from the approximator. Defaults to None.

  • n (Optional[int]) – The number of players. Required if approximator is not provided. Defaults to None.

  • max_order (Optional[int]) – The maximum order of the approximation. Required if approximator is not provided. Defaults to None.

  • interaction_lookup (Optional[dict]) – A dictionary that maps interactions to their index in the values vector. If interaction_lookup is not provided, it is computed from the n_players and the max_order parameters. Defaults to None.

Return type:

Union[ndarray[float], InteractionValues]

Returns:

The k-SII values in the same format as the input.

Modules

shapiq.approximator.k_sii

This module provides the functionality to transform SII values into k-SII values.

shapiq.approximator.moebius_converter

shapiq.approximator.permutation

This module contains all permutation-based sampling algorithms to estimate SII/nSII and STI.

shapiq.approximator.regression

This module contains the regression-based approximators to estimate Shapley interaction values.

shapiq.approximator.sampling

This module contains stochastic sampling procedures for coalitions of players.

shapiq.approximator.shapiq

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