# PnPXAI: Plug-and-Play Explainable AI
<div align='center'>
<img src="https://raw.githubusercontent.com/OpenXAIProject/pnpxai/main/assets/pnpxai_logo_horizontal.png">
</div>
[PnPXAI](https://openxaiproject.github.io/pnpxai/) is a Python package that provides a modular and easy-to-use framework for explainable artificial intelligence (XAI). It allows users to apply various XAI methods to their own models and datasets, and visualize the results in an interactive and intuitive way.
## Features
- [**Detector**](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/core/detector): The detector module provides automatic detection of AI models implemented in PyTorch.
- [**Evaluator**](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/evaluator/metrics/): The evaluator module provides various ways to evaluate and compare the performance and explainability of AI models with the categorized evaluation properties of correctness ([fidelity](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/evaluator/metrics/mu_fidelity.py), [area between perturbation curves](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/evaluator/metrics/pixel_flipping.py)), continuity ([sensitivity](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/evaluator/metrics/sensitivity.py)), and compactness ([complexity](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/evaluator/metrics/complexity.py)).
- **Explainers**: The explainers module contains a collection of state-of-the-art XAI methods that can generate global or local explanations for any AI model, such as:
- Perturbation-based ([SHAP](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/explainers/kernel_shap.py), [LIME](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/explainers/lime.py))
- Relevance-based ([IG](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/explainers/integrated_gradients.py), [LRP](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/explainers/lrp.py), [RAP](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/explainers/rap), [GuidedBackprop](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/explainers/guided_backprop.py))
- CAM-based ([GradCAM](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/explainers/grad_cam.py), [Guided GradCAM](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/explainers/guided_grad_cam.py))
- Gradient-based ([SmoothGrad](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/explainers/smooth_grad.py), [VarGrad](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/explainers/var_grad.py), [FullGrad](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/explainers/full_grad.py), [Gradient × Input](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/explainers/grad_x_input.py))
- [**Recommender**](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/core/recommender): The recommender module offers a recommender system that can suggest the most suitable XAI methods for a given model and dataset, based on the user’s preferences and goals.
- [**Optimizer**](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/evaluator/optimizer): The optimizer module is finds the best hyperparameter options, given a user-specified metric.
## Installation
To install `pnpxai` from `pip`, run the following command:
```bash
pip install pnpxai
```
To install `pnpxai` from `GitHub`, run the following commands:
```bash
git clone git@github.com:OpenXAIProject/pnpxai.git
cd pnpxai
pip install -e .
```
## Getting Started
This guide explains how to automatically explain your own models and datasets using the provided Python script. The complete code can be found [here](https://github.com/OpenXAIProject/pnpxai/tree/main/tutorials/auto_explanation_imagenet_example.py).
1. **Setup**: The setup involves setting a random seed for reproducibility and defining the device for computation (CPU or GPU).
```python
import torch
from pnpxai.utils import set_seed
# Set the seed for reproducibility
set_seed(seed=0)
# Determine the device based on the availability
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
```
2. **Create Experiments**: An experiment is an instance for explaining a specific model and dataset. Before creating an experiment, define the model and dataset to be explained.
**Automatic explainer selection**: The `AutoExplanationForImageClassification` method automatically selects the most applicable explainers and metrics based on the model architecture using `pnpxai.XaiRecommender`.
```python
import torch
from torch.utils.data import DataLoader
from pnpxai import AutoExplanationForImageClassification
# Bring your model
model = ...
# Prepare your data
dataset = ...
loader = DataLoader(dataset, batch_size=...)
def input_extractor(x):
...
def target_extractor(x):
...
# Auto-explanation
experiment = AutoExplanationForImageClassification(
model,
loader,
input_extractor=input_extractor,
label_extractor=label_extractor,
target_extractor=target_extractor,
target_labels=False,
)
optimized = experiment.optimize(
data_ids=range(16),
explainer_id=2,
metric_id=1,
direction='maximize', # less is better
sampler='tpe', # Literal['tpe','random']
n_trials=50, # by default, 50 for sampler in ['random', 'tpe'], None for ['grid']
seed=42, # seed for sampler: by default, None
)
```
**Manual explainer selection**: Alternatively, you can manually specify the desired explanation method and evaluation metric using `Experiment`.
```python
from pnpxai.core.modality import ImageModality
from pnpxai.explainers import LRPEpsilonPlus
from pnpxai.evaluator.metrics import MuFidelity
explainer = LRPEpsilonPlus(model)
metric = MuFidelity(model, explainer)
modality = ImageModality()
experiment = Experiment(
model,
loader,
modality,
explainers=[explainer],
metrics=[metric],
input_extractor=input_extractor,
label_extractor=label_extractor,
target_extractor=target_extractor,
)
```
## Tutorials
- [Image Classification](https://github.com/OpenXAIProject/pnpxai/tree/main/tutorials/auto_explanation_imagenet_example.py)
- [Text Classification](https://github.com/OpenXAIProject/pnpxai/tree/main/tutorials/auto_explanation_imdb_example.py)
- [Time Series Classification](https://github.com/OpenXAIProject/pnpxai/tree/main/tutorials/auto_explanation_ts_example.py)
- [Visual Question Answering](https://github.com/OpenXAIProject/pnpxai/tree/main/tutorials/auto_explanation_vqa_example.py)
- [Evaluator](https://github.com/OpenXAIProject/pnpxai/tree/main/tutorials/evaluator.py)
- [ImageNet Example All Explainers](https://github.com/OpenXAIProject/pnpxai/tree/main/tutorials/imagenet_example_all_explainers.md)
- [ImageNet Example All Metrics](https://github.com/OpenXAIProject/pnpxai/tree/main/tutorials/imagenet_example_all_metrics.md)
- [Free MCG](https://github.com/OpenXAIProject/pnpxai/tree/main/tutorials/gfgp_tutorial.py) [[Reference](https://arxiv.org/abs/2411.15265)]
## Use Cases
Medical Domain Explainability
- Counterfactual Explanation ([LEAR (Learn-Explain-Reinforce)](https://github.com/OpenXAIProject/pnpxai/tree/main/tutorials/LEAR_example_all_explainers.md)) for Alzheimer’s Disease Diagnosis, a joint work with Research Task 2 (PI Bohyung Han, Seoul National University) [[Reference](https://ieeexplore.ieee.org/document/9854196)]
- Attribution-based Explanation for [Dysarthria Diagnosis](https://github.com/OpenXAIProject/pnpxai/tree/main/tutorials/xai_ddk_pnpxai_example.md), a joint work with Research Task 3 (PI Myoung-Wan Koo, Sogang University)
LLM Trsutworthiness
- Evaluating the Factuality of Korean Text Generated by LLMs ([KorFactScore (Korean Factual precision in atomicity Score)](https://github.com/OpenXAIProject/pnpxai/tree/main/tutorials/fact_score_example_korfactscore.py)), a joint work with Research Task 4 (PI Kyongman Bae, ETRI)
[[Reference](https://github.com/ETRI-XAINLP/KorFactScore)]
## Documentation
The [Documentation](https://openxaiproject.github.io/pnpxai/) contains the API reference for all of the functionality of the framework. Primarily, high-level modules of the framework include:
- Detector
- Explainer
- Recommender
- Evaluator
- Optimizer
## Acknowledgements
> This research was initiated by KAIST XAI Center and conducted in collaboration with multiple institutions, including Seoul National University, Korea University, Sogang University, and ETRI.
We are grateful for the grant from the Institute of Information & communications Technology Planning & Evaluation (IITP) (No.RS-2022-II220984).
## License
PnP XAI is released under Apache license 2.0. See [LICENSE](https://github.com/OpenXAIProject/pnpxai/tree/main/LICENSE) for additional details.
Raw data
{
"_id": null,
"home_page": "https://github.com/OpenXAIProject/pnpxai",
"name": "pnpxai",
"maintainer": "Team SAIL",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "xai, plug and play, toolkit",
"author": "Team SAIL",
"author_email": "open.xai@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/cf/2e/11a0c6bbff76c1f4106c7d44c478c6805fc2dc96118d3d3bcb411b2d4686/pnpxai-0.1.1.tar.gz",
"platform": "Any",
"description": "# PnPXAI: Plug-and-Play Explainable AI\n\n<div align='center'>\n <img src=\"https://raw.githubusercontent.com/OpenXAIProject/pnpxai/main/assets/pnpxai_logo_horizontal.png\">\n</div>\n\n[PnPXAI](https://openxaiproject.github.io/pnpxai/) is a Python package that provides a modular and easy-to-use framework for explainable artificial intelligence (XAI). It allows users to apply various XAI methods to their own models and datasets, and visualize the results in an interactive and intuitive way.\n\n## Features\n\n- [**Detector**](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/core/detector): The detector module provides automatic detection of AI models implemented in PyTorch.\n- [**Evaluator**](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/evaluator/metrics/): The evaluator module provides various ways to evaluate and compare the performance and explainability of AI models with the categorized evaluation properties of correctness ([fidelity](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/evaluator/metrics/mu_fidelity.py), [area between perturbation curves](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/evaluator/metrics/pixel_flipping.py)), continuity ([sensitivity](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/evaluator/metrics/sensitivity.py)), and compactness ([complexity](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/evaluator/metrics/complexity.py)).\n- **Explainers**: The explainers module contains a collection of state-of-the-art XAI methods that can generate global or local explanations for any AI model, such as:\n\t- Perturbation-based ([SHAP](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/explainers/kernel_shap.py), [LIME](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/explainers/lime.py))\n\t- Relevance-based ([IG](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/explainers/integrated_gradients.py), [LRP](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/explainers/lrp.py), [RAP](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/explainers/rap), [GuidedBackprop](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/explainers/guided_backprop.py))\n\t- CAM-based ([GradCAM](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/explainers/grad_cam.py), [Guided GradCAM](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/explainers/guided_grad_cam.py))\n\t- Gradient-based ([SmoothGrad](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/explainers/smooth_grad.py), [VarGrad](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/explainers/var_grad.py), [FullGrad](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/explainers/full_grad.py), [Gradient × Input](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/explainers/grad_x_input.py))\n- [**Recommender**](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/core/recommender): The recommender module offers a recommender system that can suggest the most suitable XAI methods for a given model and dataset, based on the user\u2019s preferences and goals.\n- [**Optimizer**](https://github.com/OpenXAIProject/pnpxai/tree/main/pnpxai/evaluator/optimizer): The optimizer module is finds the best hyperparameter options, given a user-specified metric.\n\n## Installation\n\nTo install `pnpxai` from `pip`, run the following command:\n\n```bash\npip install pnpxai\n```\n\nTo install `pnpxai` from `GitHub`, run the following commands:\n\n```bash\ngit clone git@github.com:OpenXAIProject/pnpxai.git\ncd pnpxai\npip install -e .\n```\n\n## Getting Started\n\nThis guide explains how to automatically explain your own models and datasets using the provided Python script. The complete code can be found [here](https://github.com/OpenXAIProject/pnpxai/tree/main/tutorials/auto_explanation_imagenet_example.py).\n\n1. **Setup**: The setup involves setting a random seed for reproducibility and defining the device for computation (CPU or GPU). \n \n ```python\n import torch\n from pnpxai.utils import set_seed\n \n # Set the seed for reproducibility\n set_seed(seed=0)\n \n # Determine the device based on the availability\n device = torch.device(\"cuda\" if torch.cuda.is_available() else \"cpu\")\n ```\n \n2. **Create Experiments**: An experiment is an instance for explaining a specific model and dataset. Before creating an experiment, define the model and dataset to be explained.\n\n **Automatic explainer selection**: The `AutoExplanationForImageClassification` method automatically selects the most applicable explainers and metrics based on the model architecture using `pnpxai.XaiRecommender`.\n \n ```python\n import torch\n from torch.utils.data import DataLoader\n\n from pnpxai import AutoExplanationForImageClassification\n\n # Bring your model\n model = ...\n\n # Prepare your data\n dataset = ...\n loader = DataLoader(dataset, batch_size=...)\n def input_extractor(x):\n ...\n def target_extractor(x):\n ...\n\n # Auto-explanation\n experiment = AutoExplanationForImageClassification(\n model,\n loader,\n input_extractor=input_extractor,\n label_extractor=label_extractor,\n target_extractor=target_extractor,\n target_labels=False,\n )\n optimized = experiment.optimize(\n data_ids=range(16),\n explainer_id=2,\n metric_id=1,\n direction='maximize', # less is better\n sampler='tpe', # Literal['tpe','random']\n n_trials=50, # by default, 50 for sampler in ['random', 'tpe'], None for ['grid']\n seed=42, # seed for sampler: by default, None\n )\n ```\n \n **Manual explainer selection**: Alternatively, you can manually specify the desired explanation method and evaluation metric using `Experiment`.\n \n ```python\n from pnpxai.core.modality import ImageModality\n from pnpxai.explainers import LRPEpsilonPlus\n from pnpxai.evaluator.metrics import MuFidelity\n \n explainer = LRPEpsilonPlus(model)\n metric = MuFidelity(model, explainer)\n modality = ImageModality()\n\n experiment = Experiment(\n model,\n loader,\n modality,\n explainers=[explainer],\n metrics=[metric],\n input_extractor=input_extractor,\n label_extractor=label_extractor,\n target_extractor=target_extractor,\n )\n ```\n\n\n## Tutorials\n- [Image Classification](https://github.com/OpenXAIProject/pnpxai/tree/main/tutorials/auto_explanation_imagenet_example.py)\n- [Text Classification](https://github.com/OpenXAIProject/pnpxai/tree/main/tutorials/auto_explanation_imdb_example.py)\n- [Time Series Classification](https://github.com/OpenXAIProject/pnpxai/tree/main/tutorials/auto_explanation_ts_example.py)\n- [Visual Question Answering](https://github.com/OpenXAIProject/pnpxai/tree/main/tutorials/auto_explanation_vqa_example.py)\n- [Evaluator](https://github.com/OpenXAIProject/pnpxai/tree/main/tutorials/evaluator.py)\n- [ImageNet Example All Explainers](https://github.com/OpenXAIProject/pnpxai/tree/main/tutorials/imagenet_example_all_explainers.md)\n- [ImageNet Example All Metrics](https://github.com/OpenXAIProject/pnpxai/tree/main/tutorials/imagenet_example_all_metrics.md)\n- [Free MCG](https://github.com/OpenXAIProject/pnpxai/tree/main/tutorials/gfgp_tutorial.py) [[Reference](https://arxiv.org/abs/2411.15265)] \n\n## Use Cases\n\nMedical Domain Explainability\n\n- Counterfactual Explanation ([LEAR (Learn-Explain-Reinforce)](https://github.com/OpenXAIProject/pnpxai/tree/main/tutorials/LEAR_example_all_explainers.md)) for Alzheimer\u2019s Disease Diagnosis, a joint work with Research Task 2 (PI Bohyung Han, Seoul National University) [[Reference](https://ieeexplore.ieee.org/document/9854196)]\n\n- Attribution-based Explanation for [Dysarthria Diagnosis](https://github.com/OpenXAIProject/pnpxai/tree/main/tutorials/xai_ddk_pnpxai_example.md), a joint work with Research Task 3 (PI Myoung-Wan Koo, Sogang University)\n\n\nLLM Trsutworthiness\n\n- Evaluating the Factuality of Korean Text Generated by LLMs ([KorFactScore (Korean Factual precision in atomicity Score)](https://github.com/OpenXAIProject/pnpxai/tree/main/tutorials/fact_score_example_korfactscore.py)), a joint work with Research Task 4 (PI Kyongman Bae, ETRI)\n [[Reference](https://github.com/ETRI-XAINLP/KorFactScore)]\n\n\n## Documentation\n\nThe [Documentation](https://openxaiproject.github.io/pnpxai/) contains the API reference for all of the functionality of the framework. Primarily, high-level modules of the framework include: \n- Detector\n- Explainer\n- Recommender\n- Evaluator\n- Optimizer\n\n## Acknowledgements\n\n> This research was initiated by KAIST XAI Center and conducted in collaboration with multiple institutions, including Seoul National University, Korea University, Sogang University, and ETRI.\nWe are grateful for the grant from the Institute of Information & communications Technology Planning & Evaluation (IITP) (No.RS-2022-II220984).\n\n## License\n\nPnP XAI is released under Apache license 2.0. See [LICENSE](https://github.com/OpenXAIProject/pnpxai/tree/main/LICENSE) for additional details.\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "XAI Recommendation Toolkit",
"version": "0.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/OpenXAIProject/pnpxai/issues",
"Documentation": "https://github.com/OpenXAIProject/pnpxai",
"Download": "https://github.com/OpenXAIProject/pnpxai",
"Homepage": "https://github.com/OpenXAIProject/pnpxai",
"Source Code": "https://github.com/OpenXAIProject/pnpxai"
},
"split_keywords": [
"xai",
" plug and play",
" toolkit"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e6f9cbcbc79b1267926737cffaec0be69721fe82a4125fd47bbb0443368be0fe",
"md5": "46820e5252676ff41f6b71651c5725a6",
"sha256": "9b72688cc789e5c5b1621e64a927b16e332530eec70fcb244302f525355c15f7"
},
"downloads": -1,
"filename": "pnpxai-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "46820e5252676ff41f6b71651c5725a6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 124530,
"upload_time": "2024-12-27T03:09:54",
"upload_time_iso_8601": "2024-12-27T03:09:54.667907Z",
"url": "https://files.pythonhosted.org/packages/e6/f9/cbcbc79b1267926737cffaec0be69721fe82a4125fd47bbb0443368be0fe/pnpxai-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cf2e11a0c6bbff76c1f4106c7d44c478c6805fc2dc96118d3d3bcb411b2d4686",
"md5": "76c85acb0043f58dee88752a3f82cf6a",
"sha256": "4740d43b4267ecdf689cfb08de4d7c530c5a0bd814bd20e611da3d4d9dc08dbf"
},
"downloads": -1,
"filename": "pnpxai-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "76c85acb0043f58dee88752a3f82cf6a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 95857,
"upload_time": "2024-12-27T03:09:57",
"upload_time_iso_8601": "2024-12-27T03:09:57.830841Z",
"url": "https://files.pythonhosted.org/packages/cf/2e/11a0c6bbff76c1f4106c7d44c478c6805fc2dc96118d3d3bcb411b2d4686/pnpxai-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-27 03:09:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "OpenXAIProject",
"github_project": "pnpxai",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pnpxai"
}
JSON
