shapiq.approximator.ProxySHAP

class shapiq.approximator.ProxySHAP(n, *, max_order=2, index='k-SII', proxy_model='xgboost', hpo=False, adjustment='msr', sampling_weights=None, pairing_trick=True, random_state=None)[source]

Bases: Approximator[Literal[‘k-SII’, ‘FSII’, ‘FBII’, ‘SII’, ‘SV’, ‘BV’]]

ProxySHAP is a proxy-based approximator that uses a regression model to approximate the value function and applies an adjustment method to better match the true value function.

It extends RegressionMSR able to compute any-order cardinal-probabilistic indices and supports multiple adjustment methods, including MSR, SVARMIQ, and KernelSHAPIQ.

The regression model is trained on a subset of the coalitions, and its predictions are adjusted using the selected method to better match the true value function.

Example

>>> from shapiq_games.synthetic import DummyGame
>>> from shapiq.approximator import ProxySHAP
>>> game = DummyGame(n=5, interaction=(1, 2))
>>> approximator = ProxySHAP(n=5, max_order=2, index="k-SII", adjustment="svarm")
>>> approximator.approximate(budget=100, game=game)
InteractionValues(
    index=k-SII, max_order=2, estimated=False, estimation_budget=100
)

Initialize the ProxySHAP approximator.

Parameters:

  • n (int) – Number of features (players).

  • max_order (int) – Maximum order of interactions to consider.

  • index (Literal['k-SII', 'FSII', 'FBII', 'SII', 'SV', 'BV']) – Index of the instance to explain.

  • proxy_model (Union[ProxyModel, ProxyModelWithHPO, Literal['xgboost', 'lightgbm', 'tree', 'linear']]) – Optional proxy model to use for approximating the value function. If None, a default XGBoost regressor will be used. We support HPO of tree-models, via sklearn’s GridSearchCV, RandomizedSearchCV, and HalvingGridSearchCV. In this case, the .best_estimator_ will be used as the proxy model for interaction extraction and adjustment.

  • hpo (bool) – If True, wrap a string-resolved gradient-boosting proxy ("xgboost" / "lightgbm") in its default grid search (the HPO-informed proxy). Defaults to False (a bare estimator). Has no effect when proxy_model is a passed-in estimator/wrapper, or for the "tree" / "linear" tags.

  • adjustment (str) – Method for adjusting the proxy model’s predictions to better match the true value function. Options are “none” (no adjustment), “msr”,”svarm” (statified MSR), “kernel” (KernelSHAPIQ).

  • sampling_weights (ndarray[tuple[Any, ...], dtype[floating]] | None) – 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. Defaults to None.

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

  • random_state (int | None) – The random state of the estimator. Defaults to None, which is internally replaced by a fixed seed (0). ProxySHAP and its residual-adjustment approximator use separate coalition samplers, and the residual correction most beneficial when they use the same coalitions. A shared, fixed seed guarantees this alignment; with random_state=None the two samplers would diverge and the adjustment would be applied to mismatched coalitions. Pass an explicit integer to control the (still shared) seed; passing None keeps results deterministic across runs.

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

Approximate interaction values, dispatching on the proxy’s base estimator type.

The proxy is fit by fit_proxy() (which selects the feature transform from the base estimator type and unwraps any HPO wrapper). Interactions are then read out of the fitted model by _extract_proxy_interactions(), which dispatches on its type: linear models route to _extract_linear(), registered tree models to _extract_tree(). The optional residual adjustment and baseline fix are applied here. The adjustment approximator re-samples the same coalitions (ProxySHAP fixes a shared random_state), so the residuals stay aligned with the proxy’s predictions on the features it was fit on.

Parameters:

  • budget (int) – Number of coalition evaluations to draw.

  • game (Game | Callable[[ndarray], ndarray]) – Coalition game (a shapiq.game.Game or any callable accepting a binary coalition matrix and returning game values).

  • **kwargs (dict) – Ignored; present for interface compatibility.

Return type:

InteractionValues

Returns:

InteractionValues for orders 0 through self.max_order.

set_adjustment_method(adjustment)[source]

Select the method for adjusting the proxy model’s predictions.

Return type:

None

Parameters:

adjustment (str)