shapiq.vision Sub-package for Image Classification

[S2k-1]

Motivation and Context

The current shapiq package does not support explaining image models, except for code inside benchmark games, where logic is hardcoded per model, which is not flexible for users who whant to explain their own models.

This PR introduces a new subpackage shapiq.vision for explaining image classification models with Shapley values and interactions. Its shapiq.vision.ImageExplainer and shapiq.vision.ImageImputer work with provided model callables like CNNs and vision transformers, and any supported approximator from shapiq.approximator, covering first-order and higher-order interaction indices. The package fits into the existing shapiq framework of using Explainer, Game and Imputer classes, and adds new functionality for image players and masking strategies.

In general, we provide the following new modules and functionalities:

• shapiq.vision.architecture: Model-architecture-specific logic for image models, including default player/masking strategies and value functions.
  • Supports a wide range of classifiers via two extensible classes: ClassifierArchitecture (flexible, runs arbitrary callables with players/masks defined in pixel space) and ViTArchitecture (Hugging Face ViTs only, supports masking in latent/token space).
• shapiq.vision.custom_types: Custom protocols and type aliases for image inputs and model callables.
• shapiq.vision.explainer: Explains image classification models by passing a model callable, and configure the explanation as usual in the shapiq package
• shapiq.vision.imputer: Imputes absent players in a coalition, providing batched evaluation of coalitions
• shapiq.vision.masking: Implements different masking strategies for image models depending on a domain (pixel space or latent space)
• shapiq.vision.players: Implements different player strategies for image models, depending on a domain (pixel space or latent space)
• shapiq.vision.utils: Utility functions for image models, including e.g. transforming images to and from torch tensors, extracting logits.
• shapiq.vision.validation: Validation functions for e.g. checking model is callable or has certain attributes.

Additionally:

• Dispatch from shapiq.Explainer to shapiq.vision.ImageExplainer if a shapiq.vision.ModelArchitecture is passed in as the modelargument.
• Plot image interactions with shapiq.vision.plot_image_attributions(), as a heatmap plot and optionally interaction values next to it.

The design of shapiq.vision follows the pattern of existing shapiq subpackages like shapiq.tree, separating the concerns of image players, masking strategies, and model-callable logic into dedicated modules distinct from shapiq's core logic, since these concerns are specific to image models. This isolation also makes it easier to define distinct supported model types and behaviors without needing to provide an universal extension to the core package. Keeping the image logic contained in a single subpackage also keeps the core shapiq package lightweight and avoids introducing optional dependencies like torch or scikit-image into the base install.
We therefore introduce a new optional dependency group vision for the new subpackage, which can be installed with pip install shapiq[vision].

---

Public API Changes

• No Public API changes
• Yes, Public API changes (Details below)

We add a new subpackage shapiq.vision with its own public API, documented and provided with examples in examples/vision. We thus also added dispatching to shapiq.vision.ImageExplainer if a shapiq.vision.ModelArchitecture is passed in as the model argument to shapiq.Explainer. Apart from that we did not change the public API of shapiq and only added new functionality for image models.

To showcase the new functionality, see the following simple example:

from shapiq.vision import ImageExplainer, ClassificationArchitecture, ViTClassificationArchitecture

# --- CNN - resnet example ---
arch = ClassificationArchitecture(model=resnet)
explainer = ImageExplainer(model=arch, data=my_image)
iv = explainer.explain_function(x=None, budget=64)

# --- ViT ---
arch = ViTClassificationArchitecture(model=my_vit, vit_processor=processor)
explainer = ImageExplainer(model=arch, data=my_image)
iv = explainer.explain_function(x=None, budget=64)

# interaction plot
iv.plot_image_attributions(image=my_image, player_masks=explainer.imputer.player_masks)

Notes: We explicitly choose to use a model argument in ImageExplainer that currently only takes subclasses of shapiq.vision.ModelArchitecture instead of a callable model. We did not rename that to architecture, to be consistent with the existing shapiq.Explainer API and to allow for future dispatching of a callable model to a shapiq.vision.ModelArchitecture if the model is recognized as a supported image model. We explored on that in our own repository using forward passes to determine the model type, because there is no distinct way to determine if a model is a vision transformer or CNN from protocols or attributes. We decided to not include that in the final PR, as this might require additional refactoring and enforces a model call at every instantiation of the ImageExplainer, which is not necessary for all use cases. We thus leave it to the user to pass in a shapiq.vision.ModelArchitecture subclass, which is also more explicit, but still allows for more flexibility in the future. We have also added image support for the upset plot in our repository.

---

How Has This Been Tested?

We provide a test suite for our new shapiq.vision subpackage covering unit tests for individual components and integration tests for the end-to-end explanation pipeline.
All tests are included in tests/test_unit/tests_vision, covering the individual player and masking strategies, batching, explainer and imputer logic, and validation logic for model callables and configuration of players, masking, and model input.

Not covered in the test suite:

• Benchmarking against real pretrained models is done separately in the efficiency benchmarks (not included in this PR)

• Benchmarking the performance of shapiq.vision against commonly used methods for explaining image models (like captum) is not included in this PR

• GPU-specific device-handling paths are tested only on CPU in CI; manual GPU testing was done locally.

---

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.

---

[mmschlk]

Hello, thank you for your PR already! Please ping me here as soon as you want a PR review. :)

Note however, that for a review, the CI pipeline should really be green first (all tests pass, the code-quality checks are okay, and the docs building pipeline compiles). Otherwise it's hard for me to give you good feedback. :)

I can also approve the workflows from time to time if you ping me.

[S2k-1]

@mmschlk ty/ruff errors fixed. CI workflow on our fork only got errors for codecov upload. (expected due to missing token)
Please approve the workflow here :)

[t-muras]

We also added two examples to the documentation to showcase how to interact with the vision subpackage and how to define different player strategies. These are kept rather simple until now, we'll extend them after we decided how to refactor the architectures (after the feedback).

We also now copied the behavior from ShaplEIG and SPEX approximators in defining optional dependencies for the vision package.

[t-muras]

@mmschlk Could you approve the workflow, so we can verify the full pipeline runs successfully?

[S2k-1]

@Advueu963 could you please approve the workflow or ping @mmschlk

[codecov]

Codecov Report

❌ Patch coverage is 97.04918% with 27 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/shapiq/vision/__init__.py	64.00%	9 Missing ⚠️
src/shapiq/vision/imputer.py	91.22%	5 Missing ⚠️
src/shapiq/vision/masking.py	97.81%	4 Missing ⚠️
src/shapiq/vision/architecture.py	98.51%	3 Missing ⚠️
src/shapiq/vision/players.py	98.38%	3 Missing ⚠️
src/shapiq/vision/utils.py	97.05%	3 Missing ⚠️

📢 Thoughts on this report? Let us know!

[mmschlk]

Thank you already for your pull request and all of your work already on this matter!! :) I only had some minor comments (see individually). It's already pretty nice!

The only "major-ish" thing I have is also a bit of a question. Did we decided not to wirre ImageExplainer into the Explainer dispatching logic? So, we said we do not expect users to do

explainer = Explainer(image_model, ...)

and expect explainer to be ImageExplainer? Because I think this is not possible, yet. I would however, like to know weather it would be easy to allow users to call

explainer = Explainer(CNNArchitecture(model), ...)

and then get ImageExplainer. But then only these special architectures would work in the dispatching. Is this doable?

Thank you already!

[mmschlk]

we actually went to "SV" as default in v1.5.0 and order 1.

[mmschlk]

A few parameters are out of step with our other explainers and I'd like parity before we can merge:

• budget is read from kwargs here instead of being an explicit argument (compare TabularExplainer.explain_function(x, budget=...)). Please make it a real signature parameter so it shows up in the docs/IDE.
• no random_state is this not also necessary here?

[mmschlk]

This hard-codes a 3x3 grid, but PatchStrategy.init requires grid_size % sqrt(n_players) == 0. For one of the most common ViT, vit-base-patch16-224, the grid_size is 224/16 = 14 and 14 % 3 != 0, so this raises ValueError on construction and the default path crashes for the standard model. The examples only work because they use patch32-384 (grid 12). Please make the default adapt to grid_size (pick a perfect square whose root divides the grid), and add a regression test against a 14x14 grid so this can't silently come back.

[mmschlk]

Heads-up, and this one isn't really your fault as we already have the same pattern in ShaplEIG. This eager from .architecture import ... pulls architecture.py (and its top-level import torch) at import-shapiq time, so even a tabular-only user pays ~0.5s of torch import. The try/except guards graceful failure but not laziness. Please defer this with a module-level getattr (PEP 562) so torch is only imported when ImageExplainer is actually used. Soon I will open a matching issue against ShaplEIG so we fix both consistently then.

[t-muras]

@mmschlk: Thank you for your feedback! We have implemented the requested changes. Could you approve the workflow again and check if the changes match your expectation?
Just as a note: we are still working on including protocols to improve typing and then also include validation functions to ensure proper error messages raise, if players/masking do not match the model architecture.

[mmschlk]

Got it! I approved the runs. There are now some issues with the current main branch after I merged a few things in. Mea culpa 😇

[t-muras]

@mmschlk: Resolved already 😊, thanks!

[mmschlk]

I already went through the current state and my comments seemed to be all resolved now, apart from the "typing" model definition in the explainer (such that ImageExplainer can be also called without a specific strategy in mind). I think you awyways are still cooking something up there, right? :)

[t-muras]

@mmschlk: We just submitted our final version for the practical, pipeline ran without errors in our forked repo !

If we need to make further changes so that we can merge this, just ping us :)