shapiq.approximator.ProxySPEX¶

class shapiq.approximator.ProxySPEX(*, n, max_order=2, index='k-SII', proxy_model='lightgbm', hpo=True, sampling_weights=None, pairing_trick=False, top_order=False, random_state=None)[source]¶

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

ProxySPEX (SParse EXplainer) via Fourier transform sampling.

An approximator for cardinal interaction indices using Fourier transform sampling to efficiently compute sparse higher-order interactions. ProxySPEX is presented in Butler et al. [2025].

Initialize the ProxySPEX approximator.

Parameters:

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

  • max_order (int) – Maximum interaction order to consider.

  • index (Literal['k-SII', 'STII', 'FSII', 'FBII', 'SII', 'SV', 'BV']) – The Interaction index to use. All indices supported by shapiq’s MoebiusConverter are supported.

  • top_order (bool) – If True, only reports interactions of exactly order max_order. Otherwise, reports all interactions up to order max_order. Defaults to False.

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

  • sampling_weights (ndarray | 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.

  • proxy_model (Union[Any, Literal['xgboost', 'lightgbm', 'tree', 'linear'], ProxyModelWithHPO]) –

    Proxy model used to approximate the value function. ProxySPEX reads interactions off the proxy’s tree structure, so only tree proxies are supported. May be:

    • a string identifier ("lightgbm" (default), "xgboost", "tree") selecting a tree estimator; "linear" is rejected since ProxySPEX is tree-only. When hpo is set, a resolved gradient-boosting backend is wrapped in its default grid search (the reference HPO-informed proxy of Butler et al. [2025]); "tree" and any backend-missing fallback to a DecisionTreeRegressor stay bare. ProxySPEX does not require the optional gradient-boosting backends: if the requested package is unavailable the tag warns and falls back to a bare scikit-learn DecisionTreeRegressor.

    • a fitted-on-call estimator implementing the scikit-learn regressor interface, or a hyperparameter-search wrapper exposing best_estimator_ (e.g. GridSearchCV or the ProxyModelWithHPO wrappers).

  • hpo (bool) – If True (default), wrap a string-resolved gradient-boosting proxy in its default grid search (the HPO-informed proxy of Butler et al. [2025]). If False, use the bare resolved estimator. Has no effect when proxy_model is a passed-in estimator/wrapper.

  • random_state (int | None) – Seed for random number generator. Defaults to None.

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

Approximates the interaction values using a sparse transform approach.

Parameters:

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

  • game (Game | Callable[[ndarray], ndarray]) – The game function that returns the values for the coalitions.

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

Return type:

InteractionValues

Returns:

The approximated Shapley interaction values.

fourier_to_moebius(four_dict)[source]¶

Converts a Fourier representation of a function to its Moebius representation.

Return type:

dict[tuple[int, ...], float]

Parameters:

four_dict (dict[tuple[int, ...], float])