Rename t parameter in SPEX and Sparse (mmschlk#392)

* updated description and name of ``t`` to be ``degree_parameter``

* updated attr description

* updated README.md

* updated readme to include SPEX

* updated degree_parameter description

* updated README.md

* updated README.md

* fixed logo_path

* Update README.md

Author: mmschlk

README.md

@@ -19,12 +19,14 @@
 Shapley Interaction Quantification (`shapiq`) is a Python package for (1) approximating any-order Shapley interactions, (2) benchmarking game-theoretical algorithms for machine learning, (3) explaining feature interactions of model predictions. `shapiq` extends the well-known [shap](https://github.com/shap/shap) package for both researchers working on game theory in machine learning, as well as the end-users explaining models. SHAP-IQ extends individual Shapley values by quantifying the **synergy** effect between entities (aka **players** in the jargon of game theory) like explanatory features, data points, or weak learners in ensemble models. Synergies between players give a more comprehensive view of machine learning models.
 
 ## 🛠️ Install
-`shapiq` is intended to work with **Python 3.10 and above**. Installation can be done via `uv` and `pip`:
-
+`shapiq` is intended to work with **Python 3.10 and above**.
+Installation can be done via `uv` :
 ```sh
 uv add shapiq
 ```
 
+or via `pip`:
+
 ```sh
 pip install shapiq
 ```
@@ -37,6 +39,7 @@ If you are interested in the underlying game theoretic algorithms, then check ou
 ### Compute any-order feature interactions
 
 Explain your models with Shapley interactions:
+Just load your data and model, and then use a `shapiq.Explainer` to compute Shapley interactions.
 
 ```python
 import shapiq
@@ -135,7 +138,7 @@ The pseudo-code above can produce the following plot (here also an image is adde
 
 ### Explain TabPFN
 
-With ``shapiq`` you can also [``TabPFN``](https://github.com/PriorLabs/TabPFN) by making use of the _remove-and-recontextualize_ explanation paradigm implemented in ``shapiq.TabPFNExplainer``.
+With ``shapiq`` you can also explain [``TabPFN``](https://github.com/PriorLabs/TabPFN) by making use of the _remove-and-recontextualize_ explanation paradigm implemented in ``shapiq.TabPFNExplainer``.
 
 ```python
 import tabpfn, shapiq
@@ -148,14 +151,36 @@ explainer = shapiq.TabPFNExplainer(   # setup the explainer
     labels=labels,
     index="FSII"
 )
-fsii_values = explainer.explain(X[0])  # explain with Faithful Shapley values
+fsii_values = explainer.explain(data[0])  # explain with Faithful Shapley values
 fsii_values.plot_force()               # plot the force plot
 ```
 
 <p align="center">
   <img width="800px" src="https://raw.githubusercontent.com/mmschlk/shapiq/main/docs/source/_static/images/fsii_tabpfn_force_plot_example.png" alt="Force Plot of FSII values as derived from the example tabpfn notebook">
 </p>
 
+### Use SPEX (SParse EXplainer) <img src="https://raw.githubusercontent.com/mmschlk/shapiq/main/docs/source/_static/images/spex_logo.png" alt="spex_logo" align="right" height="75px"/>
+For large-scale use-cases you can also check out the [👓``SPEX``](https://shapiq.readthedocs.io/en/latest/api/shapiq.approximator.sparse.html#shapiq.approximator.sparse.SPEX) approximator.
+
+```python
+# load your data and model with large number of features
+data, model, n_features = ...
+
+# use the SPEX approximator directly
+approximator = shapiq.SPEX(n=n_features, index="FBII", max_order=2)
+fbii_scores = approximator.approximate(budget=2000, game=model.predict)
+
+# or use SPEX with an explainer
+explainer = shapiq.Explainer(
+    model=model,
+    data=data,
+    index="FBII",
+    max_order=2,
+    approximator="spex"  # specify SPEX as approximator
+)
+explanation = explainer.explain(data[0])
+```
+
 
 ## 📖 Documentation with tutorials
 The documentation of ``shapiq`` can be found at https://shapiq.readthedocs.io.

shapiq/approximator/sparse/_base.py

@@ -38,8 +38,16 @@ class Sparse(Approximator):
 
     Attributes:
         transform_type: Type of transform used (currently only ``"fourier"`` is supported).
-        transform_tolerance: Error tolerance parameter for the sparse Fourier transform.
+
+        degree_parameter: A parameter that controls the maximum degree of the interactions to
+            extract during execution of the algorithm. Note that this is a soft limit, and in
+            practice, the algorithm may extract interactions of any degree. We typically find
+            that there is little value going beyond ``5``. Defaults to ``5``. Note that
+            increasing this parameter will need more ``budget`` in the :meth:`approximate`
+            method.
+
         query_args: Parameters for querying the signal.
+
         decoder_args: Parameters for decoding the transform.
 
     Raises:
@@ -60,7 +68,7 @@ def __init__(
         random_state: int | None = None,
         transform_type: Literal["fourier"] = "fourier",
         decoder_type: Literal["soft", "hard"] = "soft",
-        transform_tolerance: int = 5,
+        degree_parameter: int = 5,
     ) -> None:
         """Initialize the Sparse approximator.
 
@@ -83,15 +91,19 @@ def __init__(
 
             decoder_type: Type of decoder to use, either "soft" or "hard". Defaults to "soft".
 
-            transform_tolerance: Error tolerance parameter for the sparse Fourier transform.
-                Higher values increase accuracy but require more samples. Defaults to ``5``.
+            degree_parameter: A parameter that controls the maximum degree of the interactions to
+                extract during execution of the algorithm. Note that this is a soft limit, and in
+                practice, the algorithm may extract interactions of any degree. We typically find
+                that there is little value going beyond ``5``. Defaults to ``5``. Note that
+                increasing this parameter will need more ``budget`` in the :meth:`approximate`
+                method.
 
         """
         if transform_type.lower() not in ["fourier"]:
             msg = "transform_type must be 'fourier'"
             raise ValueError(msg)
         self.transform_type = transform_type.lower()
-        self.transform_tolerance = transform_tolerance
+        self.degree_parameter = degree_parameter
         self.decoder_type = "hard" if decoder_type is None else decoder_type.lower()
         if self.decoder_type not in ["soft", "hard"]:
             msg = "decoder_type must be 'soft' or 'hard'"
@@ -104,7 +116,7 @@ def __init__(
             "subsampling_method": "qsft",
             "delays_method_channel": "identity-siso",
             "num_repeat": 1,
-            "t": self.transform_tolerance,
+            "t": self.degree_parameter,
         }
         self.decoder_args = {
             "num_subsample": 3,
@@ -116,7 +128,7 @@ def __init__(
             else "identity",
             "regress": "lasso",
             "res_energy_cutoff": 0.9,
-            "source_decoder": get_bch_decoder(n, self.transform_tolerance, self.decoder_type),
+            "source_decoder": get_bch_decoder(n, self.degree_parameter, self.decoder_type),
         }
         super().__init__(
             n=n,
@@ -245,31 +257,31 @@ def _set_transform_budget(self, budget: int) -> int:
             ValueError: If the budget is too low to compute the transform with acceptable parameters.
         """
         b = SubsampledSignalFourier.get_b_for_sample_budget(
-            budget, self.n, self.transform_tolerance, 2, self.query_args
+            budget, self.n, self.degree_parameter, 2, self.query_args
         )
         used_budget = SubsampledSignalFourier.get_number_of_samples(
-            self.n, b, self.transform_tolerance, 2, self.query_args
+            self.n, b, self.degree_parameter, 2, self.query_args
         )
 
         if b <= 2:
-            while self.transform_tolerance > 2:
-                self.transform_tolerance -= 1
-                self.query_args["t"] = self.transform_tolerance
+            while self.degree_parameter > 2:
+                self.degree_parameter -= 1
+                self.query_args["t"] = self.degree_parameter
 
                 # Recalculate 'b' with the updated 't'
                 b = SubsampledSignalFourier.get_b_for_sample_budget(
-                    budget, self.n, self.transform_tolerance, 2, self.query_args
+                    budget, self.n, self.degree_parameter, 2, self.query_args
                 )
 
                 # Compute the used budget
                 used_budget = SubsampledSignalFourier.get_number_of_samples(
-                    self.n, b, self.transform_tolerance, 2, self.query_args
+                    self.n, b, self.degree_parameter, 2, self.query_args
                 )
 
                 # Break if 'b' is now sufficient
                 if b > 2:
                     self.decoder_args["source_decoder"] = get_bch_decoder(
-                        self.n, self.transform_tolerance, self.decoder_type
+                        self.n, self.degree_parameter, self.decoder_type
                     )
                     break
 

shapiq/approximator/sparse/spex.py

@@ -27,7 +27,7 @@ def __init__(
         top_order: bool = False,
         random_state: int | None = None,
         decoder_type: Literal["soft", "hard"] = "soft",
-        transform_tolerance: int = 5,
+        degree_parameter: int = 5,
     ) -> None:
         """Initialize the SPEX approximator.
 
@@ -47,8 +47,12 @@ def __init__(
 
             decoder_type: Type of decoder to use, either "soft" or "hard". Defaults to "soft".
 
-            transform_tolerance: Error tolerance parameter for the sparse Fourier transform.
-                Higher values increase accuracy but require more samples. Defaults to ``5``.
+            degree_parameter: A parameter that controls the maximum degree of the interactions to
+                extract during execution of the algorithm. Note that this is a soft limit, and in
+                practice, the algorithm may extract interactions of any degree. We typically find
+                that there is little value going beyond ``5``. Defaults to ``5``. Note that
+                increasing this parameter will need more ``budget`` in the :meth:`approximate`
+                method.
 
         """
         super().__init__(
@@ -59,5 +63,5 @@ def __init__(
             random_state=random_state,
             transform_type="fourier",
             decoder_type=decoder_type,
-            transform_tolerance=transform_tolerance,
+            degree_parameter=degree_parameter,
         )

tests/tests_approximators/test_approximator_spex.py

@@ -149,7 +149,7 @@ def test_sparsity_parameter(n, interaction, budget, correct_b, correct_t):
     _ = spex.approximate(budget, game)
 
     assert spex.query_args["b"] == correct_b
-    assert spex.transform_tolerance == correct_t
+    assert spex.degree_parameter == correct_t
 
 
 @pytest.mark.parametrize(