shapley-calculator 0.2.1

A library to calculate Shapley values for feature importance in machine learning models.

Shapley Calculator v0.2.1

A professional Python library to calculate Shapley values for feature importance in machine learning models. Designed for speed, flexibility, and high-quality visualizations in Jupyter Notebooks.

Key Features (v0.2.1)

• 🚀 Parallel Processing: Built-in support for multi-core processing using concurrent.futures. Speed up calculations by up to 10x.
• 🎯 Classification Support: Interpret model probabilities (predict_proba) for binary and multi-class classification.
• 📊 Advanced Visualizations:
  • Summary Plot (Beeswarm): Distribution of feature impacts across the entire dataset.
  • Local Explanation: Detailed breakdown of individual predictions.
• 📝 Automated Reporting: Rich text console reports for quick analysis in terminal or notebooks.
• 🔌 Scikit-learn Compatible: Works with any model following the standard predict/predict_proba interface.

Installation

pip install shapley_calculator

Quick Start

from shapley_calculator.shapley import ShapleyValueCalculator
from sklearn.ensemble import RandomForestClassifier

# Initialize calculator (Parallel processing enabled by default)
calculator = ShapleyValueCalculator(
    model, X_test, 
    model_type='classification', 
    class_idx=1, 
    n_jobs=-1
)

# 1. Get a comprehensive text report
print(calculator.get_summary_report(feature_names=features))

# 2. Visualize global impact distribution
calculator.plot_summary(feature_names=features)

# 3. Analyze a specific prediction
calculator.plot_local(sample_idx=0, feature_names=features)

Advanced Usage

Parallel Execution

Control the number of CPU cores used for calculations:

calculator = ShapleyValueCalculator(model, X, n_jobs=4)

Normalization

Ensure Shapley values sum to 100% (or 1.0) for easier interpretation:

shap_values = calculator.get_shapley_values(normalize=True)

Technical Details

The library uses a sampling-based estimation algorithm for Shapley values, which provides a good balance between calculation speed and estimation accuracy.

• Computational Complexity: O(Samples * Features * num_samples / n_jobs)
• Normalization: Preserves signs while ensuring unit sum.