🎯 Overview
The Shapley value is a solution concept from cooperative game theory that assigns a unique distribution (among the players) of a total surplus generated by the coalition of all players. This package provides multiple approaches to calculate Shapley values:
Direct Calculation
Calculate Shapley values with pre-defined coalition values for exact game scenarios.
Function-Based Evaluation
Use custom evaluation functions to dynamically compute coalition values.
Parallel Processing
Automatic parallelization for large-scale games with 10+ players.
🚀 Installation
Install the package using pip:
pip install shapley-value
⚡ Quick Start
Get started with a simple example:
from shapley_value import ShapleyCombinations
# Define players and coalition values
players = ['Alice', 'Bob', 'Charlie']
coalition_values = {
(): 0,
('Alice',): 10,
('Bob',): 20,
('Charlie',): 30,
('Alice', 'Bob'): 50,
('Alice', 'Charlie'): 60,
('Bob', 'Charlie'): 70,
('Alice', 'Bob', 'Charlie'): 100
}
# Calculate Shapley values
calculator = ShapleyCombinations(players)
shapley_values = calculator.calculate_shapley_values(coalition_values)
print(shapley_values)
# Output: {'Alice': 16.67, 'Bob': 33.33, 'Charlie': 50.0}
✨ Key Features
- Multiple Calculation Methods: Support for both pre-defined coalition values and evaluation functions
- Parallel Processing: Automatic parallelization for large games (>10 players)
- Data Export: Save raw coalition data to CSV for further analysis
- Type Flexibility: Works with any hashable player types (strings, numbers, objects)
- Memory Efficient: Optimized algorithms for handling large coalition spaces
- Comprehensive Documentation: Detailed examples and API documentation
📊 Performance
The package delivers excellent performance through intelligent optimization strategies:
| Players | Coalitions | Sequential | Parallel | Speedup |
|---|---|---|---|---|
| 5 | 32 | <0.001s | <0.001s | 1.0x |
| 10 | 1,024 | 6.6s | 1.1s | 5.8x |
| 12 | 4,096 | 31s | 2.6s | 12.0x |
| 15 | 32,768 | ~4min | 0.2s | ~1200x |
| 16 | 65,536 | ~15min | 0.5s | ~1800x |
📚 Use Cases
Economics & Finance
Fair profit distribution among business partners and stakeholders.
Machine Learning
Feature importance and model explainability (SHAP values).
Game Theory
Coalition formation and cooperative game analysis.
🔗 Links
- GitHub Repository - Source code and development
- PyPI Package - Install and package information
- Documentation - Full documentation and API reference
- Examples - Code examples and use cases
- Learn More - About Shapley values on Wikipedia
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
📝 Citation
If you use this package in your research or project, please cite it as:
BibTeX Format:
@software{song2024shapley,
author = {Song, Bowen},
title = {Shapley Value Calculator},
year = {2024},
publisher = {GitHub},
url = {https://github.com/Bowenislandsong/shapley-value},
version = {0.0.6}
}
APA Format:
Song, B. (2024). Shapley Value Calculator (Version 0.0.6) [Computer software].
https://github.com/Bowenislandsong/shapley-value
MLA Format:
Song, Bowen. Shapley Value Calculator. Version 0.0.6, GitHub, 2024,
github.com/Bowenislandsong/shapley-value.
For more citation formats, see the CITATION.cff file in the repository.