<div align="center">
# Easy Explain
[![GitHub][github_badge]][github_link]
[![PyPI][pypi_badge]][pypi_link]
[![Test][test_passing_badge]][test_passing_badge]
[![Licence][licence_badge]][licence_link]
[![Download][download_badge]][download_link]
[![Download][total_download_badge]][download_link]
[](#supported-python-versions)
[](https://github.com/psf/black)
**Simplify the Explanation of AI Models**
</div>
Unlock the "why" behind your AI models' decisions with `easy-explain`, a Python package designed to democratize access to advanced XAI algorithms. By integrating state-of-the-art explanation techniques with minimal code, we make AI transparency accessible to developers and researchers alike.
> [!IMPORTANT]
> The new versions of `easy-explain` after 0.4.3 have breaking changes. We have changed the logic of different imports to support more models like YoloV8. Have a look at the provided [examples](https://github.com/stavrostheocharis/easy_explain/tree/main/examples).
## Requirements
### Python Versions Supported
- **Primary**: `3.11`
- **Also Supported**: `3.9`, `3.10`
Ensure one of these Python versions is installed on your system to use `easy-explain`.
### Install Environment & Dependencies
`easy-explain` can be seamlessly integrated into your projects with a straightforward installation process:
#### Installation as a Package
To incorporate `easy-explain` into your project as a dependency, execute the following command in your terminal:
```bash
pip install easy-explain
```
## Features and Functionality
`easy-explain` uses under the hood different packages based on the model to be used. [Captum](https://captum.ai/) is used for classification models and it aids to comprehend how the data properties impact the model predictions or neuron activations, offering insights on how the model performs. Captum comes together with [Pytorch library](https://pytorch.org/).
There are also other algorithms supported like GradCam or customade algorithms to support other models like the LRP implementation for YoloV8.
Currently, `easy-explain` specializes in specific cutting-edge XAI methodologies for images:
- Occlusion: For deep insight into classification model decisions.
- Cam: SmoothGradCAMpp & LayerCAM for explainability on image classification models.
- Layer-wise Relevance Propagation (LRP): Specifically tailored for YoloV8 models, unveiling the decision-making process in object detection tasks.
## Quick Start
To begin unraveling the intricacies of your model's decisions, import and utilize the corresponding classes as follows:
```python
from easy_explain import OcclusionExplain
model = 'your-model'
occlusion_explain = OcclusionExplain(model=model)
vis_types=[["blended_heat_map", "original_image"]]
vis_signs = [["positive","all"]]
occlusion_explain.generate_explanation(image_url="your-image",total_preds=5,vis_types = vis_types, vis_signs = vis_signs, labels_path="your-labels-path")
```
```python
from easy_explain import YOLOv8LRP
model = 'your-model'
image = 'your-image'
lrp = YOLOv8LRP(model, power=2, eps=1, device='cpu')
explanation_lrp = lrp.explain(image, cls='your-class', contrastive=False).cpu()
lrp.plot_explanation(frame=image, explanation = explanation_lrp, contrastive=True, cmap='seismic', title='Explanation for your class"')
```
```python
from easy_explain import YOLOv8LRP
model = 'your-model'
image = 'your-image'
trans_params = {"ImageNet_transformation":
{"Resize": {"h": 224,"w": 224},
"Normalize": {"mean": [0.485, 0.456, 0.406], "std": [0.229, 0.224, 0.225]}}}
explainer = CAMExplain(model)
input_tensor = explainer.transform_image(img, trans_params["ImageNet_transformation"])
explainer.generate_explanation(img, input_tensor, multiple_layers=["a_layer", "another_layer", "another_layer"])
```
For more information about how to begin have a look at the [examples notebooks](https://github.com/stavrostheocharis/easy_explain/tree/main/examples).
## Examples
Explore how `easy-explain` can be applied in various scenarios:
## How to contribute?
`easy-explain` thrives on community contributions, from feature requests and bug reports to code submissions. We encourage you to share your insights, improvements, and use cases to foster a collaborative environment for advancing XAI.
### Getting Involved
Submit Issues: Encounter a bug or have a feature idea? Let us know through our [issues page](https://github.com/stavrostheocharis/easy_explain/issues).
Code Contributions: Interested in contributing code? Please refer to our [`CONTRIBUTING`](https://github.com/stavrostheocharis/easy_explain/blob/main/CONTRIBUTING.md) guidelines for more information on how to get started..
Join us in making AI models more interpretable, transparent, and trustworthy with `easy-explain`.
[github_badge]: https://badgen.net/badge/icon/GitHub?icon=github&color=black&label
[github_link]: https://github.com/stavrostheocharis/easy_explain
[pypi_badge]: https://badge.fury.io/py/easy-explain.svg
[pypi_link]: https://pypi.org/project/easy-explain/
[download_badge]: https://static.pepy.tech/personalized-badge/easy-explain?period=month&units=international_system&left_color=grey&right_color=green&left_text=Monthly%20Downloads
[test_passing_badge]: https://github.com/stavrostheocharis/easy_explain/actions/workflows/python-app.yml/badge.svg
[total_download_badge]: https://static.pepy.tech/personalized-badge/easy-explain?period=total&units=international_system&left_color=grey&right_color=green&left_text=Total%20Downloads
[download_link]: https://pypi.org/project/easy-explain/#files
[licence_badge]: https://img.shields.io/github/license/stavrostheocharis/easy_explain
[licence_link]: LICENSE
Raw data
{
"_id": null,
"home_page": "https://github.com/stavrostheocharis/stavrostheocharis",
"name": "easy-explain",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "explainable ai,xai,easy explain",
"author": "Stavros Theocharis",
"author_email": "stavrostheocharis@yahoo.gr",
"download_url": "https://files.pythonhosted.org/packages/04/bc/b3669e176c79d69b6e24c770dd5735ed4c814425a7215641d2006a7b7f26/easy_explain-0.5.0.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n \n# Easy Explain\n\n\n[![GitHub][github_badge]][github_link]\n[![PyPI][pypi_badge]][pypi_link]\n[![Test][test_passing_badge]][test_passing_badge]\n[![Licence][licence_badge]][licence_link] \n[![Download][download_badge]][download_link]\n[![Download][total_download_badge]][download_link]\n[](#supported-python-versions)\n[](https://github.com/psf/black) \n\n**Simplify the Explanation of AI Models**\n \n</div>\n\nUnlock the \"why\" behind your AI models' decisions with `easy-explain`, a Python package designed to democratize access to advanced XAI algorithms. By integrating state-of-the-art explanation techniques with minimal code, we make AI transparency accessible to developers and researchers alike.\n\n> [!IMPORTANT]\n> The new versions of `easy-explain` after 0.4.3 have breaking changes. We have changed the logic of different imports to support more models like YoloV8. Have a look at the provided [examples](https://github.com/stavrostheocharis/easy_explain/tree/main/examples).\n\n\n## Requirements\n\n### Python Versions Supported\n- **Primary**: `3.11`\n- **Also Supported**: `3.9`, `3.10`\n\nEnsure one of these Python versions is installed on your system to use `easy-explain`.\n\n\n### Install Environment & Dependencies\n\n`easy-explain` can be seamlessly integrated into your projects with a straightforward installation process:\n\n\n#### Installation as a Package\n\nTo incorporate `easy-explain` into your project as a dependency, execute the following command in your terminal:\n\n\n```bash\npip install easy-explain\n```\n\n## Features and Functionality\n\n`easy-explain` uses under the hood different packages based on the model to be used. [Captum](https://captum.ai/) is used for classification models and it aids to\u00a0comprehend\u00a0how the data properties impact the\u00a0model predictions or neuron activations, offering insights on how the model performs. Captum comes together with [Pytorch library](https://pytorch.org/).\nThere are also other algorithms supported like GradCam or customade algorithms to support other models like the LRP implementation for YoloV8.\n\n\nCurrently, `easy-explain` specializes in specific cutting-edge XAI methodologies for images:\n\n- Occlusion: For deep insight into classification model decisions.\n- Cam: SmoothGradCAMpp & LayerCAM for explainability on image classification models.\n- Layer-wise Relevance Propagation (LRP): Specifically tailored for YoloV8 models, unveiling the decision-making process in object detection tasks.\n\n## Quick Start\n\nTo begin unraveling the intricacies of your model's decisions, import and utilize the corresponding classes as follows:\n\n```python\nfrom easy_explain import OcclusionExplain\n\nmodel = 'your-model'\n\nocclusion_explain = OcclusionExplain(model=model)\nvis_types=[[\"blended_heat_map\", \"original_image\"]]\nvis_signs = [[\"positive\",\"all\"]]\n\nocclusion_explain.generate_explanation(image_url=\"your-image\",total_preds=5,vis_types = vis_types, vis_signs = vis_signs, labels_path=\"your-labels-path\")\n\n```\n\n```python\nfrom easy_explain import YOLOv8LRP\n\nmodel = 'your-model'\nimage = 'your-image'\n\nlrp = YOLOv8LRP(model, power=2, eps=1, device='cpu')\n\nexplanation_lrp = lrp.explain(image, cls='your-class', contrastive=False).cpu()\n\nlrp.plot_explanation(frame=image, explanation = explanation_lrp, contrastive=True, cmap='seismic', title='Explanation for your class\"')\n```\n\n```python\nfrom easy_explain import YOLOv8LRP\n\nmodel = 'your-model'\nimage = 'your-image'\n\ntrans_params = {\"ImageNet_transformation\":\n {\"Resize\": {\"h\": 224,\"w\": 224},\n \"Normalize\": {\"mean\": [0.485, 0.456, 0.406], \"std\": [0.229, 0.224, 0.225]}}}\n\nexplainer = CAMExplain(model) \n\ninput_tensor = explainer.transform_image(img, trans_params[\"ImageNet_transformation\"])\n\nexplainer.generate_explanation(img, input_tensor, multiple_layers=[\"a_layer\", \"another_layer\", \"another_layer\"])\n```\n\nFor more information about how to begin have a look at the [examples notebooks](https://github.com/stavrostheocharis/easy_explain/tree/main/examples).\n\n## Examples\n\nExplore how `easy-explain` can be applied in various scenarios:\n\n\n\n![Use Case Example](easy_explain/images/lion-heat-map.png \"Use Case Example\")\n\n![Use Case Example](easy_explain/images/siberian-positive.png \"Use Case Example\")\n\n![Use Case Example](easy_explain/images/jiraffe-cam-method.png \"Use Case Example\")\n\n![Use Case Example](easy_explain/images/class-traffic.png \"Use Case Example\")\n\n## How to contribute?\n\n`easy-explain` thrives on community contributions, from feature requests and bug reports to code submissions. We encourage you to share your insights, improvements, and use cases to foster a collaborative environment for advancing XAI.\n\n### Getting Involved\n\nSubmit Issues: Encounter a bug or have a feature idea? Let us know through our [issues page](https://github.com/stavrostheocharis/easy_explain/issues).\n\nCode Contributions: Interested in contributing code? Please refer to our [`CONTRIBUTING`](https://github.com/stavrostheocharis/easy_explain/blob/main/CONTRIBUTING.md) guidelines for more information on how to get started..\n\nJoin us in making AI models more interpretable, transparent, and trustworthy with `easy-explain`.\n\n\n[github_badge]: https://badgen.net/badge/icon/GitHub?icon=github&color=black&label\n\n[github_link]: https://github.com/stavrostheocharis/easy_explain\n\n[pypi_badge]: https://badge.fury.io/py/easy-explain.svg\n\n[pypi_link]: https://pypi.org/project/easy-explain/\n\n[download_badge]: https://static.pepy.tech/personalized-badge/easy-explain?period=month&units=international_system&left_color=grey&right_color=green&left_text=Monthly%20Downloads\n\n[test_passing_badge]: https://github.com/stavrostheocharis/easy_explain/actions/workflows/python-app.yml/badge.svg\n\n[total_download_badge]: https://static.pepy.tech/personalized-badge/easy-explain?period=total&units=international_system&left_color=grey&right_color=green&left_text=Total%20Downloads\n\n[download_link]: https://pypi.org/project/easy-explain/#files\n\n[licence_badge]: https://img.shields.io/github/license/stavrostheocharis/easy_explain\n\n[licence_link]: LICENSE\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A library that helps to explain AI models in a really quick & easy way",
"version": "0.5.0",
"project_urls": {
"Download": "https://github.com/stavrostheocharis/easy_explain/archive/refs/tags/v0.5.0.tar.gz",
"Homepage": "https://github.com/stavrostheocharis/stavrostheocharis"
},
"split_keywords": [
"explainable ai",
"xai",
"easy explain"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "04bcb3669e176c79d69b6e24c770dd5735ed4c814425a7215641d2006a7b7f26",
"md5": "5930762d111a280adaf45029f660d339",
"sha256": "b7643fe3b893aa09fe8847a9d4e6e701abe437472e9efd3d420d46281cd2d665"
},
"downloads": -1,
"filename": "easy_explain-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "5930762d111a280adaf45029f660d339",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 26924,
"upload_time": "2024-02-12T14:27:32",
"upload_time_iso_8601": "2024-02-12T14:27:32.176278Z",
"url": "https://files.pythonhosted.org/packages/04/bc/b3669e176c79d69b6e24c770dd5735ed4c814425a7215641d2006a7b7f26/easy_explain-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-12 14:27:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "stavrostheocharis",
"github_project": "stavrostheocharis",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "easy-explain"
}
JSON
