shapiq.interaction_values.InteractionValues¶

class shapiq.interaction_values.InteractionValues(values, *, index, max_order, n_players, min_order, interaction_lookup=None, estimated=True, estimation_budget=None, baseline_value=0.0, target_index=None)[source]¶

Bases: object

This class contains the interaction values as estimated by an approximator.

Variables:

values – The interaction values of the model in vectorized form.
index – The interaction index estimated. All available indices are defined in ALL_AVAILABLE_INDICES.
max_order – The order of the approximation.
n_players – The number of players.
min_order – The minimum order of the approximation. Defaults to 0.
interaction_lookup – 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, min_order, and max_order parameters. Defaults to None.
estimated – Whether the interaction values are estimated or not. Defaults to True.
estimation_budget – The budget used for the estimation. Defaults to None.
baseline_value – The value of the baseline interaction also known as ‘empty prediction’ or 'empty value' since it denotes the value of the empty coalition (empty set). If not provided it is searched for in the values vector (raising an Error if not found). Defaults to None.

Raises:

UserWarning – If the index is not a valid index as defined in ALL_AVAILABLE_INDICES.
TypeError – If the baseline value is not a number.

Parameters:

values (np.ndarray | InteractionScores)
index (str)
max_order (int)
n_players (int)
min_order (int)
interaction_lookup (dict[tuple[int, ...], int] | None)
estimated (bool)
estimation_budget (int | None)
baseline_value (float | np.number)
target_index (str | None)

Initialize the InteractionValues object.

Parameters:

values (ndarray | dict[tuple[int, ...], float]) – The interaction values as a numpy array or a dictionary mapping interactions to their values.
index (target_index =) – The index of the interaction values. This should be one of the indices defined in
interpreted. (ALL_AVAILABLE_INDICES. It is used to determine how the interaction values are)
max_order (int) – The maximum order of the interactions.
n_players (which means it will be generated from the) – The number of players in the game.
min_order (int) – The minimum order of the interactions. Defaults to 0.
interaction_lookup (dict[tuple[int, ...], int] | None) – A dictionary mapping interactions to their index in the values vector.
None (Defaults to)
n_players
min_order
parameters. (and max_order)
estimated (bool) – Whether the interaction values are estimated or not. Defaults to True.
estimation_budget (int | None) – The budget used for the estimation. Defaults to None.
baseline_value (float | number) – The baseline value of the interaction values, also known as the empty prediction or empty value.
target_index (str | None) – The index to which the InteractionValues should be finalized. Defaults to None, which means that
index

classmethod from_dict(data)[source]¶

Create an InteractionValues object from a dictionary.

Parameters:: data (dict[str, Any]) – The dictionary containing the data to create the InteractionValues object from.
Return type:: InteractionValues
Returns:: The InteractionValues object created from the dictionary.

classmethod from_first_order_array(first_order_values, index, baseline_value=0)[source]¶

Convert an array of first-order values to an shapiq.InteractionValues object.

Parameters:

first_order_values (ndarray) – An array containing the value of the ith training point at index i.
index (str) – The game theoretic index of the resulting shapiq.InteractionValues object.
baseline_value (float) – Baseline value, defaults to 0.

Return type:

InteractionValues

Returns:

An InteractionValues object containing the provided values.

classmethod from_json_file(path)[source]¶

Loads an InteractionValues object from a JSON file.

Parameters:: path (Path) – The path to the JSON file. Note that the path must end with ‘.json’.
Return type:: InteractionValues
Returns:: The InteractionValues object loaded from the JSON file.
Raises:: ValueError – If the path does not end with ‘.json’.

classmethod load(path)[source]¶

Load an InteractionValues object from a file.

Parameters:: path (Path | str) – The path to load the InteractionValues object from.
Return type:: InteractionValues
Returns:: The loaded InteractionValues object.

aggregate(others, aggregation='mean')[source]¶

Aggregates InteractionValues objects using a specific aggregation method.

Parameters:

others (Sequence[InteractionValues]) – A list of InteractionValues objects to aggregate.
aggregation (str) – The aggregation method to use. Defaults to "mean". Other options are "median", "sum", "max", and "min".

Return type:

InteractionValues

Returns:

The aggregated InteractionValues object.

Note

For documentation on the aggregation methods, see the aggregate_interaction_values() function.

get_n_order(order=None, min_order=None, max_order=None)[source]¶

Select particular order of interactions.

Creates a new InteractionValues object containing only the interactions within the specified order range.

You can specify:

order: to select interactions of a single specific order (e.g., all pairwise
interactions).
min_order and/or max_order: to select a range of interaction orders.
If order and min_order/max_order are both set, min_order and max_order will
override the order value.

Example

>>> interaction_values = InteractionValues(
...     values=np.array([1, 2, 3, 4, 5, 6, 7]),
...     interaction_lookup={(0,): 0, (1,): 1, (2,): 2, (0, 1): 3, (0, 2): 4, (1, 2): 5, (0, 1, 2): 6},
...     index="SII",
...     max_order=3,
...     n_players=3,
...     min_order=1,
...     baseline_value=0.0,
... )
>>> interaction_values.get_n_order(order=1).dict_values
{(0,): 1.0, (1,): 2.0, (2,): 3.0}
>>> interaction_values.get_n_order(min_order=1, max_order=2).dict_values
{(0,): 1.0, (1,): 2.0, (2,): 3.0, (0, 1): 4.0, (0, 2): 5.0, (1, 2): 6.0}
>>> interaction_values.get_n_order(min_order=2).dict_values
{(0, 1): 4.0, (0, 2): 5.0, (1, 2): 6.0, (0, 1, 2): 7.0}

Parameters:

order (int | None) – The order of the interactions to return. Defaults to None which requires min_order or max_order to be set.
min_order (int | None) – The minimum order of the interactions to return. Defaults to None which sets it to the order.
max_order (int | None) – The maximum order of the interactions to return. Defaults to None which sets it to the order.

Return type:

InteractionValues

Returns:

The interaction values of the specified order.

Raises:

ValueError – If all three parameters are set to None.

get_n_order_values(order)[source]¶

Returns the interaction values of a specific order as a numpy array.

Note

Depending on the order and number of players the resulting array might be sparse and very large.

Parameters:: order (int) – The order of the interactions to return.
Return type:: ndarray
Returns:: The interaction values of the specified order as a numpy array of shape (n_players,) for order 1 and (n_players, n_players) for order 2, etc.
Raises:: ValueError – If the order is less than 1.

get_subset(players)[source]¶

Selects a subset of players from the InteractionValues object.

Parameters:: players (list[int]) – List of players to select from the InteractionValues object.
Returns:: Filtered InteractionValues object containing only values related to selected players.
Return type:: InteractionValues

Example

>>> interaction_values = InteractionValues(
...     values=np.array([0.1, 0.2, 0.3, 0.4, 0.5, 0.6]),
...     interaction_lookup={(0,): 0, (1,): 1, (2,): 2, (0, 1): 3, (0, 2): 4, (1, 2): 5},
...     index="SII",
...     max_order=2,
...     n_players=3,
...     min_order=1,
...     baseline_value=0.0,
... )
>>> interaction_values.get_subset([0, 1]).dict_values
{(0,): 0.1, (1,): 0.2, (0, 1): 0.3}
>>> interaction_values.get_subset([0, 2]).dict_values
{(0,): 0.1, (2,): 0.3, (0, 2): 0.4}
>>> interaction_values.get_subset([1]).dict_values
{(1,): 0.2}

get_top_k(k, *, as_interaction_values=True)[source]¶

Returns the top k interactions.

Parameters:

k (int) – The number of top interactions to return.
as_interaction_values (bool) – Whether to return the top k interactions as an InteractionValues object. Defaults to False.

Return type:

InteractionValues | tuple[dict, list[tuple]]

Returns:

The top k interactions as a dictionary and a sorted list of tuples.

Examples

>>> interaction_values = InteractionValues(
...     values=np.array([0.1, 0.2, 0.3, 0.4, 0.5, 0.6]),
...     interaction_lookup={(0,): 0, (1,): 1, (2,): 2, (0, 1): 3, (0, 2): 4, (1, 2): 5},
...     index="SII",
...     max_order=2,
...     n_players=3,
...     min_order=1,
...     baseline_value=0.0,
... )
>>> top_k_interactions, sorted_top_k_interactions = interaction_values.get_top_k(2, False)
>>> top_k_interactions
{(0, 2): 0.5, (1, 0): 0.6}
>>> sorted_top_k_interactions
[((1, 0), 0.6), ((0, 2), 0.5)]

get_top_k_interactions(k)[source]¶

Returns the top k interactions.

Parameters:: k (int) – The number of top interactions to return.
Return type:: InteractionValues
Returns:: The top k interactions as an InteractionValues object.

plot_force(feature_names=None, *, show=True, abbreviate=True, contribution_threshold=0.05)[source]¶

Visualize InteractionValues on a force plot.

For arguments, see shapiq.plots.force_plot().

Parameters:

feature_names (ndarray | None) – The feature names used for plotting. If no feature names are provided, the feature indices are used instead. Defaults to None.
show (bool) – Whether to show the plot. Defaults to False.
abbreviate (bool) – Whether to abbreviate the feature names or not. Defaults to True.
contribution_threshold (float) – The threshold for contributions to be displayed in percent. Defaults to 0.05.

Return type:

Figure | None

Returns:

The force plot as a matplotlib figure (if show is False).

plot_network(*, show=True, **kwargs)[source]¶

Visualize InteractionValues on a graph.

Note

For arguments, see shapiq.plot.network.network_plot() and: shapiq.plot.si_graph.si_graph_plot().

Parameters:

show (bool) – Whether to show the plot. Defaults to True.
**kwargs (Any) – Additional keyword arguments to pass to the plotting function.

Return type:

tuple[Figure, Axes] | None

Returns:

If show is False, the function returns a tuple with the figure and the axis of the: plot.

plot_sentence(words, *, show=True, **kwargs)[source]¶

Plots the first order effects (attributions) of a sentence or paragraph.

For arguments, see shapiq.plots.sentence_plot().

Return type:

tuple[Figure, Axes] | None

Returns:

If show is True, the function returns None. Otherwise, it returns a tuple with the figure and the axis of the plot.

Parameters:

words (list[str])
show (bool)
kwargs (Any)

plot_si_graph(*, show=True, **kwargs)[source]¶

Visualize InteractionValues as a SI graph.

For arguments, see shapiq.plots.si_graph_plot().

Return type:

tuple[Figure, Axes] | None

Returns:

The SI graph as a tuple containing the figure and the axes.

Parameters:

show (bool)
kwargs (Any)

plot_stacked_bar(*, show=True, **kwargs)[source]¶

Visualize InteractionValues on a graph.

For arguments, see shapiq.plots.stacked_bar_plot().

Return type:

tuple[Figure, Axes] | None

Returns:

The stacked bar plot as a tuple containing the figure and the axes.

Parameters:

show (bool)
kwargs (Any)

plot_upset(*, show=True, **kwargs)[source]¶

Plots the upset plot.

For arguments, see shapiq.plot.upset_plot().

Return type:

Figure | None

Returns:

The upset plot as a matplotlib figure (if show is False).

Parameters:

show (bool)
kwargs (Any)

plot_waterfall(feature_names=None, *, show=True, abbreviate=True, max_display=10)[source]¶

Draws interaction values on a waterfall plot.

Note

Requires the shap Python package to be installed.

Parameters:

feature_names (ndarray | None) – The feature names used for plotting. If no feature names are provided, the feature indices are used instead. Defaults to None.
show (bool) – Whether to show the plot. Defaults to False.
abbreviate (bool) – Whether to abbreviate the feature names or not. Defaults to True.
max_display (int) – The maximum number of interactions to display. Defaults to 10.

Return type:

Axes | None

save(path)[source]¶

Save the InteractionValues object to a JSON file.

Parameters:: path (Path) – The path to save the InteractionValues object to.
Return type:: None

sparsify(threshold=0.001)[source]¶

Manually sets values close to zero actually to zero (removing values).

Parameters:: threshold (float) – The threshold value below which interactions are zeroed out. Defaults to 1e-3.
Return type:: None

to_dict()[source]¶

Convert the InteractionValues object to a dictionary.

Return type:: dict
Returns:: The InteractionValues object as a dictionary.

to_first_order_array()[source]¶

Convert to an array of first-order values.

Return type:: ndarray
Returns:: An array of shape (self.n_players,) containing at index i the first-order value of player i.
Raises:: ValueError – If the method was called on an InteractionValues object with max order not equal to 1.

to_json_file(path, *, desc=None, created_from=None, **kwargs)[source]¶

Saves the InteractionValues object to a JSON file.

Parameters:

path (Path) – The path to the JSON file.
desc (str | None) – A description of the InteractionValues object. Defaults to None.
created_from (object | None) – An object from which the InteractionValues object was created. Defaults to None.
**kwargs (str | int | float | bool | None | Sequence[JSONType] | Mapping[str, JSONType]) – Additional parameters to store in the metadata of the JSON file.

Return type:

None

property dict_values: dict[tuple[int, ...], float]¶: Getter for the dict directly mapping from all interactions to scores.

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

Getter for the interaction lookup of the InteractionValues object.

Returns:: The interaction lookup of the InteractionValues object as a dictionary mapping interactions to their index in the values vector.

interactions: dict[tuple[int, ...], float]¶: The interactions as a dictionary mapping interactions to their values.

property values: ndarray¶

Getter for the values of the InteractionValues object.

Returns:: The values of the InteractionValues object as a numpy array.