Create blog_post.md (#287)

* Create blog_post.md

* reworked docs

* added why to use shapiq

---------

Co-authored-by: Maximilian <[email protected]>

docs/source/conf.py

@@ -67,12 +67,12 @@
 html_css_files = [
     "css/custom.css",
 ]
-html_favicon = "_static/shapiq.ico"
+html_favicon = "_static/logo/shapiq.ico"
 pygments_dark_style = "monokai"
 html_theme_options = {
     "sidebar_hide_name": True,
-    "light_logo": "logo_shapiq_light.svg",
-    "dark_logo": "logo_shapiq_dark.svg",
+    "light_logo": "logo/logo_shapiq_light.svg",
+    "dark_logo": "logo/logo_shapiq_dark.svg",
 }
 
 html_sidebars = {

docs/source/index.rst

@@ -22,26 +22,25 @@ Contents
 
 .. toctree::
    :maxdepth: 1
-   :caption: OVERVIEW
+   :caption: INTRODUCTION
 
-   installation
-   start
+   introduction/index
+   introduction/installation
+   introduction/start
+   introduction/why-use-shapiq
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
    :caption: TUTORIALS
 
-   notebooks/sv_calculation
-   notebooks/shapiq_scikit_learn
-   notebooks/treeshapiq_lightgbm
-   notebooks/visualizing_shapley_interactions
-   notebooks/language_model_game
-   notebooks/vision_transformer
-   notebooks/conditional_imputer
-   notebooks/parallel_computation
-   notebooks/benchmark_approximators
-   notebooks/data_valuation
-   notebooks/core
+   Basic Examples <notebooks/basics>
+   Tabular Examples <notebooks/tabular>
+   Tree Examples <notebooks/trees>
+   Vision Examples <notebooks/vision>
+   Language Examples <notebooks/language>
+   Visualization <notebooks/visualization>
+   Game Theoretic Concepts <notebooks/game_theory>
+   Benchmarking <notebooks/benchmark>
 
 .. toctree::
    :maxdepth: 2

docs/source/introduction/index.md

@@ -0,0 +1,64 @@
+# What Are Shapley Interactions, and Why Should You Care?
+Shapley values are the go-to method for explainable AI because they are easy to interpret and theoretically well-founded.
+However, they struggle to capture the interplay between features.
+About two years ago, we attended a talk that introduced the concept of **Shapley interactions**, and we quickly realized that Shapley interactions were exactly the solution to our problem!
+Unfortunately, the presenter also mentioned that calculating Shapley interaction values is extremely difficult, if not impossible.
+We started experimenting a bit and soon came up with a preliminary approach to compute Shapley interactions for any machine learning model.
+After receiving positive feedback and growing interest from the community, we realized that this research gap was a perfect opportunity to pursue our own interests and create impact for others.
+That’s when our shapiq project was born. Here, we want to tell you what Shapley interactions are and why you should care.
+
+## What Are Interactions?
+
+Imagine you're working with the California housing dataset and we want to predict house prices. Features like location, median income, and year built all play a role.
+Location, for example, is represented by longitude (west-east) and latitude (north-south).
+But here’s the twist: looking at longitude or latitude individually doesn’t tell the whole story. It’s their combination—pinpointing the exact location—that influences house prices.
+Take two houses (with otherwise similar properties) near the ocean:
+* Close to San Francisco: $454,000.
+* Far from major hotspots: $210,000.
+
+This difference isn’t explained by longitude or latitude alone but by their interaction. Interactions capture the idea that one feature's influence (longitude) depends on the value of another (latitude).
+
+## Limitations of Shapley Values
+Shapley values are popular because they distribute the effects of features fairly.
+For example, if you explain the above-mentioned house in San Francisco with a predicted house price of 454,000$, Shapley values show that both longitude and latitude positively contribute (see image below).
+But there's a problem: Shapley values merge individual effects and interaction effects into a single number. This means:
+* We can’t tell how much of a feature’s influence is individual versus interactive.
+* We don’t know which other features it interacts with.
+
+<div style="text-align:center">
+<img src="../_static/images/motivation_sv.png" width="800">
+</div>
+
+## Enter Shapley Interactions
+Shapley interactions enhance the traditional Shapley value approach by breaking down the effects of features into **individual contributions** and **interactions between features**.
+Instead of providing a single value per feature, Shapley interactions distribute the prediction's influence across both individual features and groups of interacting features.
+So for each combination of features we, potentially, can get a value of an interaction.
+Let’s return to our **California housing** example, the decomposition up to order 2 compared to order 1 (Shapley value) shows that:
+* Longitude has a high individual contribution, showing the importance of proximity to the ocean.
+* Latitude, however, has little individual impact, with its contribution coming entirely from its interaction with longitude (in the image below latitude’s contribution vanishes but the interaction between longitude and latitude appears). This interaction captures how the combination of longitude and latitude identifies high-value locations, like San Francisco.
+
+By predefining a **maximum interaction order**, you can control how detailed the analysis gets.
+Setting it to second-order interactions, for instance, allows you to explore how pairs of features interact (like longitude and latitude) while still capturing individual effects.
+This provides a richer understanding of how features influence predictions—whether independently or through their interplay.
+
+<div style="text-align:center">
+<img src="../_static/images/motivation_sv_and_si.png" width="800">
+</div>
+
+Hence, Shapley interactions give you more granular insights into the relationships driving model predictions, helping **uncover synergies or redundancies that traditional Shapley values can’t**.
+One of the main takeaways here is that we can interpret Shapley interactions like you are used to with SHAP, while providing more information. This level of detail, however, can come with a cost.
+
+## Balancing Insights and Complexity
+The more interactions we analyze (higher-order decompositions), the more insights we uncover.
+**But there’s a tradeoff:** explanations become more complex and harder to interpret (because we have way more values/interactions to analyze).
+Striking the right balance between depth and simplicity depends on your goals.
+
+## Computing Shapley Interactions in Python with shapiq
+
+If you're curious about how to compute these decompositions or visualize them, check out our shapiq package for an easy way to explore Shapley interactions and uncover new insights!
+Currently, we offer a range of model-agnostic and model-specific explainers and computation methods, which you can use to calculate Shapley interactions and Shapley values for all data types and model kinds.
+Check out the tutorial notebooks on how to use it for your task.
+
+<div style="text-align:center">
+<img src="../_static/images/package_overview_paper.png" width="800">
+</div>

docs/source/installation.rst → docs/source/introduction/installation.rst

@@ -1,5 +1,5 @@
-🛠️ Installation
-===============
+Installation
+=============
 
 The latest release version of ``shapiq`` can be installed from
 `PyPI <https://pypi.org/project/shapiq>`_ with:

docs/source/start.rst → docs/source/introduction/start.rst

@@ -1,5 +1,5 @@
-⭐ Getting Started
-==================
+Getting Started
+===============
 
 Explain a model with Shapley interaction values, e.g. the k-SII values.
 
@@ -50,7 +50,7 @@ Explain a model with Shapley interaction values, e.g. the k-SII values.
 
 The pseudo-code above can produce the following plot (here also an image is added):
 
-.. image:: _static/network_example2.png
+.. image:: ../_static/network_example2.png
     :width: 500
     :alt: Example of network plot for feature interactions
     :align: center

docs/source/introduction/why-use-shapiq.md

@@ -0,0 +1,29 @@
+# Why Use ``shapiq``?
+
+There are a couple of reasons why you might want to use ``shapiq``:
+
+## Explanations with Shapley Interactions
+
+``shapiq`` directly extends on ``shap`` but also allows for computation of Shapley interactions.
+These interactions can be used to explain models in more detail.
+To facilitate any-order interactions, ``shapiq`` requires specific data structure and sets of algorithms.
+
+## Explanations with Shapley values
+
+Similar to ``shap``, ``shapiq`` can also be used to explain models with the well-established Shapley values.
+Many algorithms that are available in ``shap`` are also available in ``shapiq``.
+Often, this is beneficial when you are looking into a higher-number of features.
+
+## Two Independent Perspectives: Explanation and Game Theory
+
+``shapiq`` offers two independent perspectives on the same problem: explanation and game theory.
+We introduce the notion of a general ``game``, which maps any machine learning problem (also outside the scope of machine learning) to a cooperative game without design decisions of explanation methods.
+This allows for easy computation of many game-theoretic concepts, such as the Shapley value, Shapley interactions, or the Banzhaf value.
+The explanation perspective is similar to ``shap`` and includes established mechanisms to transform any machine learning model into a cooperative game.
+``shapiq`` offers a unified interface to both perspectives.
+
+## Benchmarking of Novel Approaches
+
+``shapiq`` is a platform for benchmarking novel approaches in the field of Shapley values and Shapley interactions.
+We implement many state-of-the-art algorithms and provide a unified interface to compare them.
+Further, we provide a set of tools to evaluate the performance of these algorithms on pre-computed benchmarks tasks.

docs/source/notebooks/basics.rst

@@ -0,0 +1,11 @@
+Basic Usage Examples
+====================
+
+The following notebooks provide basic examples of how to use the ``shapiq`` package. All
+examples are self-contained and can be run in a Jupyter notebook:
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   basics_notebooks/*