GraphShapIQ Implementation

[Proman9000]

Motivation and Context

GraphSHAP-IQ is an algorithm for computing exact Shapley interaction values for Graph Neural Networks (GNNs), by Muschalik et. al https://arxiv.org/abs/2501.16944. It is the graph analogue of TreeSHAP-IQ and exploits the locality of message passing in GNNs. A node's embedding after L layers depends only on its L-hop neighborhood (its receptive field), which means Moebius interactions between nodes are zero unless all nodes fall within a single receptive field. This reduces the complexity from O(2^n) to O(n * 2^r), where r is the maximum receptive field size.

The algorithm works by:

1. Computing the L-hop receptive field for each node via BFS
2. Enumerating only coalitions within these receptive fields (not all 2^n)
3. Batch-evaluating these coalitions through the GNN game
4. Computing Moebius coefficients from the evaluations
5. Converting Moebius coefficients to the target interaction index via shapiq's existing MoebiusConverter

This PR adds a new shapiq.graph subpackage implementing this algorithm.

• GraphGame: This class wraps a GNN model (GCN, GIN, or GAT) together with an input graph. Players are graph nodes, and value_function(coalitions) evaluates the GNN's prediction for each coalition by masking absent nodes' features to a baseline while keeping the graph structure intact. Supports both classification and regression GNNs.
• GraphSHAPIQ: The core algorithm. Computes each node's L-hop receptive field via BFS, enumerates and deduplicates the union of powersets over these receptive fields, batch-evaluates them through a GraphGame, computes Moebius coefficients, and converts them to the target interaction index using the existing MoebiusConverter.
• GraphExplainer: This class integrates GraphSHAPIQ into shapiq's explainer framework, following the TreeExplainer pattern. Constructs the GraphGame internally and exposes a clean explain(x) API.

Public API Changes

• Yes, Public API changes (Details below)

New shapiq.graph subpackage exposing GraphGame, GraphSHAPIQ, and GraphExplainer.

How Has This Been Tested?

The GraphSHAPIQ algorithm has been thoroughly tested, including correctness against ExactComputer on small graphs, the efficiency axiom, all three GNN architectures (GCN, GIN, GAT), and edge cases (disconnected graphs, single-node graphs, fully connected graphs). GraphGame has also been thoroughly tested. GraphExplainer and the L-Shapley algorithm have been only slightly tested so far. Overall test coverage is above 90%.

Checklist

• The changes have been tested locally.
• Documentation has been updated (if the public API or usage changes).
• An entry has been added to CHANGELOG.md (if relevant for users).
• The code follows the project's style guidelines.
• I have considered the impact of these changes on the public API.

[amndzdzdz]

@mmschlk could you review the changes please? :)

[mmschlk]

@amndzdzdz, I will review/make changes to the methodological aspects of this PR again after the 17th for preparing the final merge into shapiq. :)

[mmschlk]

The graph package is still not getting displayed in the existing documentation. For this you have to change the api reference list for sphinx. Also, there are still no example scripts inside the examples folder.

[mmschlk]

I will be bringing this in for 1.8.0. The next release contains a lot of work on the shapiq.tree side and I do not want to mix concerns.