shapiq.approximator.Approximator

class shapiq.approximator.Approximator(n, max_order, index, *, top_order=False, min_order=0, pairing_trick=False, sampling_weights=None, random_state=None, initialize_dict=True)[source]

Bases: ABC, Generic[TIndices]

This class is the base class for all approximators.

Approximators are used to estimate the interaction values of a model or any value function. Different approximators can be used to estimate different interaction indices. Some can be used to estimate all indices.

Variables:

  • n – The number of players.

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

  • _grand_coalition_array – The array of players (starting from 0 to n).

  • max_order – The interaction order of the approximation.

  • index – The interaction index to be estimated.

  • top_order – If True, the approximation is performed only for the top order interactions. If False, the approximation is performed for all orders up to the specified order.

  • min_order – The minimum order of the approximation. If top_order is True, min_order is equal to max_order. Otherwise, min_order is equal to 0.

  • iteration_cost – The cost of a single iteration of the approximator.

Parameters:

  • n (int)

  • max_order (int)

  • index (TIndices)

  • top_order (bool)

  • min_order (int)

  • pairing_trick (bool)

  • sampling_weights (FloatVector | None)

  • random_state (int | None)

  • initialize_dict (bool)

Initialize the Approximator.

Parameters:

  • n (int) – The number of players.

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

  • index (TypeVar(TIndices, bound= Literal['SV', 'BV', 'SII', 'BII', 'k-SII', 'STII', 'FBII', 'FSII', 'kADD-SHAP', 'CHII'])) – The interaction index to be estimated.

  • top_order (bool) – If True, the approximation is performed only for the top order interactions. If False, the approximation is performed for all orders up to the specified order.

  • min_order (int) – The minimum interaction order of the approximation. Defaults to 0.

  • pairing_trick (bool) – If True, the pairing trick is applied to the sampling procedure. Defaults to False.

  • sampling_weights (ndarray[tuple[Any, ...], dtype[floating]] | None) – An optional array of weights for the sampling procedure. The weights must be of shape (n + 1,) and are used to determine the probability of sampling a coalition of a certain size. Defaults to None.

  • random_state (int | None) – The random state to use for the approximation. Defaults to None. If not None, the random state is used to seed the random number generator.

  • initialize_dict (bool) – If True, initializes the interaction lookup dictionary. Defaults to True. Note this is often True for estimators that estimate all interactions for each order. This is set to False for example in SPEX.

static aggregate_interaction_values(base_interactions, order=None)[source]

Aggregates the interaction values.

Parameters:

  • base_interactions (InteractionValues) – The base interaction values to aggregate.

  • order (int | None) – The order of the aggregation. For example, the order of the k-SII aggregation. If None (default), the maximum order of the base interactions is used.

Return type:

InteractionValues

Returns:

The aggregated interaction values.

__call__(budget, game, **kwargs)[source]

Calls the approximate method.

This method is a wrapper around the approximate method. It is used to call the approximator with the given budget and game function.

Parameters:

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

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

  • **kwargs (Any) – Additional keyword arguments to pass to the approximate method.

Return type:

InteractionValues

abstractmethod approximate(budget, game, **kwargs)[source]

Approximates the interaction values.

Abstract method that needs to be implemented for each approximator.

Parameters:

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

  • game (Game | Callable[[ndarray], ndarray]) – The game function.

  • *args – Additional positional arguments.

  • **kwargs (Any) – Additional keyword arguments.

Return type:

InteractionValues

Returns:

The interaction values.

Raises:

NotImplementedError – If the method is not implemented.

set_random_state(random_state=None)[source]

Sets the random state for the approximator.

Parameters:

random_state (int | None) – The random state to set. If None, no random state is set.

Return type:

None

property approximator_id: int

Returns the ID of the approximator.

property interaction_lookup: dict[tuple[int, ...], int]

Returns the interaction lookup dictionary.

valid_indices: tuple[TIndices, ...] = ('SV', 'BV', 'SII', 'BII', 'k-SII', 'STII', 'FBII', 'FSII', 'kADD-SHAP', 'CHII')

The valid indices for the base approximator.