Metadata-Version: 2.4
Name: shapley_calculator
Version: 0.2.1
Summary: A library to calculate Shapley values for feature importance in machine learning models.
Home-page: https://github.com/AlekseevDS21/Shapley
Author: Andrew Alexeev
Author-email: andrey.alekseev8996@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.18.0
Requires-Dist: pandas>=1.0.0
Requires-Dist: scikit-learn>=0.22.0
Requires-Dist: matplotlib>=3.1.0
Requires-Dist: tqdm>=4.40.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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

```bash
pip install shapley_calculator
```

## Quick Start

```python
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:
```python
calculator = ShapleyValueCalculator(model, X, n_jobs=4)
```

### Normalization
Ensure Shapley values sum to 100% (or 1.0) for easier interpretation:
```python
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.
