model-explain 0.5.0
A comprehensive Python package for interpreting and explaining machine learning and deep learning models. Includes support for feature attention mechanisms and integrates popular explanation methods such as LIME, SHAP, Grad-CAM, permutation importance, and saliency maps. Offers a unified interface for tabular, image, and other data types to enhance model transparency and interpretability.
Requires Python: >=3.8

# Model Explain

---

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI version](https://badge.fury.io/py/model-explain.svg)](https://badge.fury.io/py/model-explain)

---

`model_explain` is a Python package for **interpreting** and **explaining** machine learning models. It provides a unified interface for popular explanation techniques, including **LIME**, **SHAP**, and **Grad-CAM** and supports a wide range of models and data types.

## Key Features

- **Unified API** for LIME and SHAP explanations
- **Model-agnostic**: works with any model supporting `predict` or `predict_proba`
- **Tabular, image, and text data** support
- **Visualizations** for both local and global explanations
- **Easy integration** with scikit-learn, XGBoost, LightGBM, and more
- **Feature importance** extraction and plotting
- **Interpretability for individual predictions** and datasets

---

## Installation

Install from PyPI:

```bash
pip install model-explain
```

Or, if you prefer to clone the repository and install manually:

```bash
git clone https://github.com/vaibhav-k/model_explain.git
cd model_explain
pip install .
```

---

## Quick Start

### Tabular Data Example (LIME)

```python
from model_explain.explainers.lime_explainer import lime_explainer

# model: trained scikit-learn model
# X_test: pandas DataFrame of test features

explanation = lime_explainer(model, X_test, instance_index=0)
explanation.show_in_notebook()
```

### Tabular Data Example (SHAP)

```python
import shap
from model_explain.explainers.shap_explainer import shap_explainer

# model: trained machine learning model
# X_test: pandas DataFrame of test features

shap_values = shap_explainer(model, X_test)
shap.summary_plot(shap_values, X_test)

```

### Image Data Example

```python
from model_explain.explainers.grad_cam import GradCAM
import matplotlib.pyplot as plt

# model: your trained CNN model (e.g., from torchvision)
# image: a preprocessed image tensor of shape [1, C, H, W]
# predicted_class: integer index of the predicted class

explainer = GradCAM(model, target_layer_name="layer4")  # specify the last conv layer
heatmap = explainer(image, target_idx=predicted_class)

plt.imshow(heatmap, cmap="jet", alpha=0.5)
plt.title("Grad-CAM Heatmap")
plt.axis("off")
plt.show()
```

### 🕒 TimeSeriesExplainer

#### ✨ Features

- Works with **TensorFlow**/**Keras** and **PyTorch** models
- Computes **per-timestep SHAP attributions**
- Generates:
    - **Temporal heatmaps** of feature contributions
    - **Feature importance over time** plots

```python
from model_explain.explainers.time_series_explainer import TimeSeriesExplainer

# model: your trained time series model
# X: input data of shape (num_samples, timesteps, features)

explainer = TimeSeriesExplainer(model, background_data=X[:5])
shap_values = explainer.explain(X[0])
explainer.plot_heatmap(shap_values, feature_names=[f"f{i}" for i in range(4)])
```

### 📝 Text Data Example

```python
from model_explain.explainers.text_explainer import TextExplainer

# model: your trained text classification model
# class_names: list of class names for the model
# tokenizer: tokenizer for text preprocessing (if needed)

explainer = TextExplainer(model, class_names=["negative", "positive"])
explainer.explain_lime("This movie was surprisingly good!")

# For Transformers
explainer.explain_shap(["I love this movie!"], tokenizer=tokenizer)
```

#### 💡 Quick Tips

- Use LIME when:
    - You’re working with traditional ML models (`TfidfVectorizer`, `CountVectorizer`, etc.).
    - You need fast, approximate local explanations for many samples.

- Use SHAP when:
    - Your model is a **deep Transformer** or you need precise, token-level insight.
    - You want globally consistent attributions (e.g., comparing feature importances across texts).
- For best results, you can combine both:
    - Run **LIME** for a quick sanity check.
    - Use **SHAP** for detailed debugging and deeper interpretability.

---

## Supported Models

- Scikit-learn models
- XGBoost
- LightGBM
- PyTorch models
- Any model with `predict` or `predict_proba` methods

---

## Visualizations

- **SHAP summary plot**: global feature importance (use **plot_feature_importance** for custom bar plots)
- **LIME explanation plot**: local feature contributions (use **plot_feature_importance** for instance-level contributions)
- **Image region importance (Grad-CAM heatmap)**: highlights spatial regions in images that most influence the model's prediction
- **Time-series heatmaps**: Visualize feature contributions over time steps
- **Time-series line plots**: Demonstrate average feature importance across time steps

---

## Use Cases

- Debugging and validating ML models
- Regulatory compliance and transparency
- Feature selection and engineering
- Enhancing trust in AI systems
- Explaining model predictions to stakeholders

---

## Contributing

Contributions are welcome! Please read `CONTRIBUTING.md` for details on how to contribute.

---

## License

This project is licensed under the MIT License - see the `LICENSE` file for details.