Shapley Value Calculator

A comprehensive Python package for calculating Shapley values in cooperative game theory. Shapley values provide a mathematically principled method for fairly distributing payoffs among players based on their marginal contributions to coalitions.

📖 Table of Contents

Overview
Installation
Quick Start
Usage Examples
API Reference
Features
Performance
Contributing
License

🎯 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 with pre-defined coalition values
Function-based evaluation with custom evaluation functions
Parallel processing support for large-scale computations

🚀 Installation

Install the package using pip:

pip install shapley-value

⚡ Quick Start

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}

📋 Usage Examples

Method 1: Pre-defined Coalition Values

Use this method when you have specific values for each possible coalition:

from shapley_value import ShapleyCombinations

players = ['Player1', 'Player2', 'Player3']
coalition_values = {
    (): 0,
    ('Player1',): 100,
    ('Player2',): 200,
    ('Player3',): 300,
    ('Player1', 'Player2'): 450,
    ('Player1', 'Player3'): 500,
    ('Player2', 'Player3'): 600,
    ('Player1', 'Player2', 'Player3'): 900
}

calculator = ShapleyCombinations(players)
shapley_values = calculator.calculate_shapley_values(coalition_values)
print(f"Shapley values: {shapley_values}")

Method 2: Function-based Evaluation

Use this method when you have a function that can evaluate any coalition:

from shapley_value import ShapleyValueCalculator

# Define an evaluation function
def profit_function(coalition):
    """Calculate the total profit of a coalition"""
    if not coalition:
        return 0
    
    # Example: each player contributes their value, with synergy effects
    base_value = sum(player for player in coalition)
    synergy_bonus = len(coalition) * 10  # Bonus for cooperation
    
    return base_value + synergy_bonus

# Define players with their individual values
players = [100, 200, 300]  # Player values

# Calculate Shapley values
calculator = ShapleyValueCalculator(profit_function, players)
shapley_values = calculator.calculate_shapley_values()
print(f"Shapley values: {shapley_values}")

# Get detailed raw data
raw_data = calculator.get_raw_data()
print(f"Raw coalition data: {raw_data}")

# Save raw data for analysis
calculator.save_raw_data('coalition_analysis.csv')

Method 3: Parallel Processing for Large Games

For games with many players, enable parallel processing:

from shapley_value import ShapleyValueCalculator

def complex_evaluation(coalition):
    """More complex evaluation function"""
    if not coalition:
        return 0
    
    # Simulate complex calculations
    total = sum(player ** 1.5 for player in coalition)
    return total * (1 + 0.1 * len(coalition))

# Large number of players
players = list(range(1, 16))  # 15 players

# Use parallel processing (uses all available CPU cores)
calculator = ShapleyValueCalculator(
    evaluation_function=complex_evaluation,
    players=players,
    num_jobs=-1  # Use all available cores
)

shapley_values = calculator.calculate_shapley_values()
print(f"Shapley values for 15 players: {shapley_values}")

📚 API Reference

`ShapleyCombinations`

For games with pre-defined coalition values.

class ShapleyCombinations:
    def __init__(self, players: List[Any])
    def calculate_shapley_values(self, coalition_values: Dict[Tuple, float]) -> Dict[Any, float]