shapiq.approximator.ProxySHAP¶

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

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

ProxySHAP is a proxy-based approximator that uses a regression model to approximate the value function and can correct the proxy’s error with an MSR residual adjustment.

The regression proxy is trained on the sampled coalitions, and interaction values are read out of the fitted model exactly. Optionally (adjustment=True), the proxy’s residuals (true game values minus proxy predictions) are estimated with a self-contained, fully vectorized MSR (maximum sample reuse) Monte Carlo routine ( unstratified SHAP-IQ Fumagalli et al. [2023]). Depending on k_folds the adjustment is computed in-sample (k_folds=1) or out-of-fold (k_folds>1) on the same sampled coalitions, and added to the proxy’s interactions.

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")
>>> approximator.approximate(budget=100, game=game)
InteractionValues(
    index=k-SII, max_order=2, min_order=0, estimated=False, estimation_budget=32,
    n_players=5, baseline_value=0.0
)

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', 'STII', 'SII', 'SV', 'BII', '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 residual 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 (bool) – If True, the MSR residual adjustment is applied to the proxy’s interactions, covering the complete interaction lattice up to max_order. Defaults to False (no adjustment). Note the lattice grows as O(n**max_order), so the adjustment is infeasible for high orders on high-dimensional games; extraction-only runs (the default) are not affected. For FSII/FBII only the top order is corrected (see top_order below), so their lower orders are returned as the uncorrected proxy readout.

  • k_folds (int) – Number of folds the sampled coalitions are split into. With the default 1, a single proxy is fit on all sampled coalitions and its residuals are computed in-sample. For values > 1, one proxy is fit per fold (KFold) on the training split, its interactions are extracted, and its residuals are computed on the held-out split only; the per-fold results are averaged.

  • 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. None means uniform sampling by size and uniform within each size.

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

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(). If enabled, the proxy’s residuals are estimated with the vectorized MSR routine. Depending on k_folds, the residuals are corrected either in-sample (k_folds=1) or out-of-fold (k_folds>1) and added to the proxy’s interactions. For k_folds>1, the final interaction values are the average of the per-fold results, and the baseline is fixed to the empty-coalition value of the game.

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 (Any) – Ignored; present for interface compatibility.

Return type:

InteractionValues

Returns:

InteractionValues for orders 0 through self.max_order.