Merge pull request #1 from automl/dev

Initial version of HyperSHAP in a usable state

Author: mwever

.github/workflows/main.yml

@@ -29,7 +29,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.11", "3.12", "3.13"]
       fail-fast: false
     defaults:
       run:
@@ -47,7 +47,7 @@ jobs:
         run: uv run python -m pytest tests --cov --cov-config=pyproject.toml --cov-report=xml
 
       - name: Check typing
-        run: uv run mypy
+        run: uv run pyright
 
 
       - name: Upload coverage reports to Codecov with GitHub Action on Python 3.11

.github/workflows/on-release-main.yml

@@ -64,4 +64,3 @@ jobs:
 
       - name: Deploy documentation
         run: uv run mkdocs gh-deploy --force
-

.gitignore

@@ -209,3 +209,6 @@ cython_debug/
 marimo/_static/
 marimo/_lsp/
 __marimo__/
+
+# IDE project files
+.idea

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# Contributing to `hypershap`
+# Contributing to `HyperSHAP`
 
 Contributions are welcome, and they are greatly appreciated!
 Every little bit helps, and credit will always be given.
@@ -9,7 +9,7 @@ You can contribute in many ways:
 
 ## Report Bugs
 
-Report bugs at https://github.com/mwever/hypershap/issues
+Report bugs at https://github.com/automl/HyperSHAP/issues
 
 If you are reporting a bug, please include:
 
@@ -29,11 +29,11 @@ Anything tagged with "enhancement" and "help wanted" is open to whoever wants to
 
 ## Write Documentation
 
-hypershap could always use more documentation, whether as part of the official docs, in docstrings, or even on the web in blog posts, articles, and such.
+HyperSHAP could always use more documentation, whether as part of the official docs, in docstrings, or even on the web in blog posts, articles, and such.
 
 ## Submit Feedback
 
-The best way to send feedback is to file an issue at https://github.com/mwever/hypershap/issues.
+The best way to send feedback is to file an issue at https://github.com/automl/HyperSHAP/issues.
 
 If you are proposing a new feature:
 
@@ -44,22 +44,22 @@ If you are proposing a new feature:
 
 # Get Started!
 
-Ready to contribute? Here's how to set up `hypershap` for local development.
+Ready to contribute? Here's how to set up `HyperSHAP` for local development.
 Please note this documentation assumes you already have `uv` and `Git` installed and ready to go.
 
-1. Fork the `hypershap` repo on GitHub.
+1. Fork the `HyperSHAP` repo on GitHub.
 
 2. Clone your fork locally:
 
 ```bash
 cd <directory_in_which_repo_should_be_created>
-git clone git@github.com:YOUR_NAME/hypershap.git
+git clone git@github.com:YOUR_NAME/HyperSHAP.git
 ```
 
 3. Now we need to install the environment. Navigate into the directory
 
 ```bash
-cd hypershap
+cd HyperSHAP
 ```
 
 Then, install and activate the environment with:

Makefile

@@ -10,8 +10,8 @@ check: ## Run code quality tools.
 	@uv lock --locked
 	@echo "🚀 Linting code: Running pre-commit"
 	@uv run pre-commit run -a
-	@echo "🚀 Static type checking: Running mypy"
-	@uv run mypy
+	@echo "🚀 Static type checking: Running pyright"
+	@uv run pyright
 	@echo "🚀 Checking for obsolete dependencies: Running deptry"
 	@uv run deptry src
 

README.md

@@ -1,74 +1,143 @@
-# hypershap
+# HyperSHAP
 
 [![Release](https://img.shields.io/github/v/release/mwever/hypershap)](https://img.shields.io/github/v/release/mwever/hypershap)
 [![Build status](https://img.shields.io/github/actions/workflow/status/mwever/hypershap/main.yml?branch=main)](https://github.com/mwever/hypershap/actions/workflows/main.yml?query=branch%3Amain)
 [![codecov](https://codecov.io/gh/mwever/hypershap/branch/main/graph/badge.svg)](https://codecov.io/gh/mwever/hypershap)
 [![Commit activity](https://img.shields.io/github/commit-activity/m/mwever/hypershap)](https://img.shields.io/github/commit-activity/m/mwever/hypershap)
 [![License](https://img.shields.io/github/license/mwever/hypershap)](https://img.shields.io/github/license/mwever/hypershap)
 
-HyperSHAP is a post-hoc explanation method for hyperparameter optimization.
+HyperSHAP – a game‑theoretic Python library for explaining Hyperparameter Optimization (HPO). It uses Shapley values and interaction indices to provide both local and global insights into how individual hyper‑parameters (and their interactions) affect a model’s performance.
 
-- **Github repository**: <https://github.com/mwever/hypershap/>
-- **Documentation** <https://mwever.github.io/hypershap/>
+- **Github repository**: <https://github.com/automl/hypershap/>
+- **Documentation** <https://automl.github.io/hypershap/>
 
-## Getting started with your project
 
-### 1. Create a New Repository
+## Table of Contents
+- [Features](#features)
+- [Installation](#installation)
+- [Getting Started](#getting-started)
+- [API Overview](#api-overview)
+- [Example Notebook](#example-notebook)
+- [Citation](#citation)
+- [Contributing](#contributing)
+- [License](#license)
 
-First, create a repository on GitHub with the same name as this project, and then run the following commands:
+---
 
-```bash
-git init -b main
-git add .
-git commit -m "init commit"
-git remote add origin git@github.com:mwever/hypershap.git
-git push -u origin main
-```
+## Features
+- **Additive Shapley decomposition** of any performance metric across hyper‑parameters.
+- **Interaction analysis** via the Faithful Shapley Interaction Index (FSII).
+- Ready‑made explanation tasks for **Ablation**, **Tunability**, and **Optimizer Bias** studies.
+- Integrated **visualisation** (SI‑graph) for interaction effects.
+- Works with any surrogate model that follows the `ExplanationTask` interface.
 
-### 2. Set Up Your Development Environment
+---
 
-Then, install the environment and the pre-commit hooks with
+## Installation
 
-```bash
-make install
+```sh
+$ make install
 ```
 
-This will also generate your `uv.lock` file
+## Getting Started
+Given an existing setup with a ConfigurationSpace from the [ConfigSpace package](https://github.com/automl/ConfigSpace) and black-box function as follows:
+```Python
+from ConfigSpace import ConfigurationSpace, Configuration
 
-### 3. Run the pre-commit hooks
+# ConfigurationSpace describing the hyperparameter space
+cs = ConfigurationSpace()
+  ...
 
-Initially, the CI/CD pipeline might be failing due to formatting issues. To resolve those run:
+# A black-box function, evaluating ConfigSpace.Configuration objects
+def blackbox_function(cfg: Configuration) -> float:
+  ...
+```
+
+You can use HyperSHAP as follows:
+```Python
+from hypershap import ExplanationTask, HyperSHAP
 
-```bash
-uv run pre-commit run -a
+# Instantiate HyperSHAP
+hypershap = HyperSHAP(ExplanationTask.from_function(config_space=cs,function=blackbox_function))
+# Conduct tunability analysis
+hypershap.tunability(baseline_config=cs.get_default_configuration())
+# Plot results as a Shapley Interaction graph
+hypershap.plot_si_graph()
 ```
 
-### 4. Commit the changes
+The example demonstrates how to:
+1. Wrap a black-box function in an explanation task.
+2. Use `HyperSHAP` to obtain interaction values for the **tunability** game.
+3. Plot the corresponding SI-graph.
 
-Lastly, commit the changes made by the two steps above to your repository.
+---
+
+## API Overview
+
+| Method | Purpose | Key Arguments |
+|--------|---------|---------------|
+| `HyperSHAP(explanation_task)` | Initialise the explainer with a generic `ExplanationTask`. |
+| `ablation(config_of_interest, baseline_config, index="FSII", order=2)` | Explain the contribution of each hyperparameter value (and interactions) when moving from a baseline to a specific configuration. |
+| `tunability(baseline_config=None, index="FSII", order=2, n_samples=10_000)` | Quantify how much performance can be gained by tuning subsets of hyper‑parameters. |
+| `optimizer_bias(optimizer_of_interest, optimizer_ensemble, index="FSII", order=2)` | Attribute performance differences to a particular optimizer vs. an ensemble of optimizers. |
+| `plot_si_graph(interaction_values=None, save_path=None)` | Plot the Shapley Interaction (SI) graph; uses the most recent interaction values if none are supplied. |
+| `ExplanationTask.get_hyperparameter_names()` | Helper to retrieve ordered hyper‑parameter names (used for visualisation). |
+
+All methods return an `InteractionValues` object (from **shapiq**) that can be inspected, saved, or passed to the visualisation routine.
+
+---
 
-```bash
-git add .
-git commit -m 'Fix formatting issues'
-git push origin main
+## Example Notebooks
+Full Jupyter notebooks illustrating all three explanation tasks (ablation, tunability, optimizer bias) are included in the repository under `examples/`. The notebookts walk through:
+
+- Building a mockup environment
+- Creating the corresponding explanation task
+- Loading explanation tasks from different setups: data, black-box function, and existing surrogate model.
+- Computing interaction values with HyperSHAP
+- Visualizing results with `plot_si_graph`
+
+---
+
+## Citation
+If you use HyperSHAP in your research, please cite the original paper:
+
+```bibtex
+@article{wever-arxiv25,
+  author       = {Marcel Wever and
+                  Maximilian Muschalik and
+                  Fabian Fumagalli and
+                  Marius Lindauer},
+  title        = {HyperSHAP: Shapley Values and Interactions for Hyperparameter Importance},
+  journal      = {CoRR},
+  volume       = {abs/2502.01276},
+  year         = {2025},
+  doi          = {10.48550/ARXIV.2502.01276},
+}
 ```
 
-You are now ready to start development on your project!
-The CI/CD pipeline will be triggered when you open a pull request, merge to main, or when you create a new release.
+The paper introduces the underlying game-theoretic framework and demonstrates its usefulness for HPO explainability.
+
+## Contributing
 
-To finalize the set-up for publishing to PyPI, see [here](https://fpgmaas.github.io/cookiecutter-uv/features/publishing/#set-up-for-pypi).
-For activating the automatic documentation with MkDocs, see [here](https://fpgmaas.github.io/cookiecutter-uv/features/mkdocs/#enabling-the-documentation-on-github).
-To enable the code coverage reports, see [here](https://fpgmaas.github.io/cookiecutter-uv/features/codecov/).
+Contributions are welcome! Please follow these steps:
 
-## Releasing a new version
+     Fork the repo and create a feature branch (git checkout -b feat/your-feature).
+     Write tests (the project uses pytest).
+     Ensure all tests pass (pytest).
+     Update documentation if you add new functionality.
+     Submit a Pull Request with a clear description of the changes.
 
-- Create an API Token on [PyPI](https://pypi.org/).
-- Add the API Token to your projects secrets with the name `PYPI_TOKEN` by visiting [this page](https://github.com/mwever/hypershap/settings/secrets/actions/new).
-- Create a [new release](https://github.com/mwever/hypershap/releases/new) on Github.
-- Create a new tag in the form `*.*.*`.
 
-For more details, see [here](https://fpgmaas.github.io/cookiecutter-uv/features/cicd/#how-to-trigger-a-release).
+See CONTRIBUTING.md for detailed guidelines.
 
 ---
 
+## License
+HyperSHAP is released under the BSD 3-Clause License. See the `LICENSE` file for full terms.
+
+---
+
+**Enjoy exploring your HPO pipelines with HyperSHAP!** 🎉
+
+---
 Repository initiated with [fpgmaas/cookiecutter-uv](https://github.com/fpgmaas/cookiecutter-uv).

docs/modules.md

@@ -1 +1,16 @@
-::: hypershap.foo
+# API Reference
+
+## HyperSHAP
+::: hypershap.hypershap
+
+## Explanation Task
+::: hypershap.task
+
+## Surrogate Model
+::: hypershap.surrogate_model
+
+## Games
+::: hypershap.games
+
+## Utils
+::: hypershap.utils