| Name | openvino-xai JSON |
| Version |
1.1.0
JSON |
| download |
| home_page | None |
| Summary | OpenVINO™ Explainable AI (XAI) Toolkit: Visual Explanation for OpenVINO Models |
| upload_time | 2024-10-02 08:27:22 |
| maintainer | Intel(R) Corporation |
| docs_url | None |
| author | Intel(R) Corporation |
| requires_python | >=3.10 |
| license | Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright (C) 2018-2021 Intel Corporation Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. |
| keywords |
openvino-toolkit
explainable-ai
xai
cnn
transformer
black-box
white-box
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<div align="center">
# OpenVINO™ Explainable AI Toolkit - OpenVINO XAI
---
[Features](#features) •
[Install](#installation) •
[Quick Start](#quick-start) •
[License](#license) •
[Documentation](https://openvinotoolkit.github.io/openvino_xai/releases/1.1.0)
[](https://pypi.org/project/openvino/)
[](https://codecov.io/gh/openvinotoolkit/openvino_xai)
[](https://opensource.org/licenses/Apache-2.0)
[](https://pypi.org/project/openvino_xai)
[](https://pepy.tech/project/openvino_xai)
---
</div>
**OpenVINO™ Explainable AI (XAI) Toolkit** provides a suite of XAI algorithms for visual explanation of
[**OpenVINO™**](https://github.com/openvinotoolkit/openvino) as well as [**PyTorch**](https://pytorch.org) and [**ONNX**](https://onnx.ai/) models.
Given AI models and input images, **OpenVINO XAI** generates **saliency maps**
which highlights regions of the interest in the inputs from the models' perspective
to help users understand the reason why the complex AI models output such responses.
Using this package, you can augment the model analysis & explanation feature
on top of the existing OpenVINO inference pipeline with a few lines of code.
```python
import openvino_xai as xai
explainer = xai.Explainer(model=ov_model, task=xai.Task.CLASSIFICATION)
# Existing inference pipeline
for i, image in enumerate(images):
labels = infer(model=ov_model, image=image)
# Model analysis
explanation = explainer(data=image, targets=labels)
explanation.save(dir_path="./xai", name=str(i))
```
---
## Features
### What's new in v1.1.0
* Support PyTorch models with `insert_xai()` API for saliency map generation on PyTorch / ONNX runtime
* Support OpenVINO IR (.xml) / ONNX (.onnx) model files for `Explainer`
* Enable AISE method: Adaptive Input Sampling for Explanation of Black-box Models
* Add Pointing Game, Insertion-Deletion AUC and ADCC quality metrics for saliency maps
* Upgrade OpenVINO to 2024.4.0
* Add saliency map visualization with explanation.plot()
* Enable flexible naming for saved saliency maps and include confidence scores
Please refer to the [change logs](CHANGELOG.md) for the full release history.
### Supported XAI methods
At the moment, *Image Classification* and *Object Detection* tasks are supported for the *Computer Vision* domain.
*Black-Box* (model agnostic but slow) methods and *White-Box* (model specific but fast) methods are supported:
| Domain | Task | Type | Algorithm | Links |
|-----------------|----------------------|-----------|------------------------|-------|
| Computer Vision | Image Classification | White-Box | ReciproCAM | [arxiv](https://arxiv.org/abs/2209.14074) / [src](openvino_xai/methods/white_box/recipro_cam.py) |
| | | | VITReciproCAM | [arxiv](https://arxiv.org/abs/2310.02588) / [src](openvino_xai/methods/white_box/recipro_cam.py) |
| | | | ActivationMap | experimental / [src](openvino_xai/methods/white_box/activation_map.py) |
| | | Black-Box | AISEClassification | [src](openvino_xai/methods/black_box/aise/classification.py) |
| | | | RISE | [arxiv](https://arxiv.org/abs/1806.07421v3) / [src](openvino_xai/methods/black_box/rise.py) |
| | Object Detection | White-Box | DetClassProbabilityMap | experimental / [src](openvino_xai/methods/white_box/det_class_probability_map.py) |
| | | Black-Box | AISEDetection | [src](openvino_xai/methods/black_box/aise/detection.py) |
See more method comparison at the [User Guide](docs/source/user-guide.md).
### Supported explainable models
Most of CNNs and Transformer models from [Pytorch Image Models (timm)](https://github.com/huggingface/pytorch-image-models) are supported and validated.
Please refer to the following known issues for unsupported models and reasons.
* [Runtime error from ONNX / OpenVINO IR models while conversion or inference for XAI (#29)](https://github.com/openvinotoolkit/openvino_xai/issues/29)
* [Models not supported by white box XAI methods (#30)](https://github.com/openvinotoolkit/openvino_xai/issues/30)
> **_NOTE:_** GenAI / LLMs would be also supported incrementally in the upcoming releases.
---
## Installation
> **_NOTE:_** OpenVINO XAI works on Python 3.10 or higher
<details>
<summary>Set up environment</summary>
```bash
# Create virtual env.
python3.10 -m venv .ovxai
# Activate virtual env.
source .ovxai/bin/activate
```
</details>
Install from PyPI package
```bash
# Base package (for normal use):
pip install openvino_xai
# Dev package (for development):
pip install openvino_xai[dev]
```
<details>
<summary>Install from source</summary>
```bash
# Clone the source repository
git clone https://github.com/openvinotoolkit/openvino_xai.git
cd openvino_xai
# Editable mode (for development):
pip install -e .[dev]
```
</details>
<details>
<summary>(Optional) Enable PyTorch support</summary>
You can enjoy the PyTorch XAI feature if the PyTorch is installed along with the OpenVINO XAI.
```bash
# Install PyTorch (CPU version as example)
pip3 install torch --index-url https://download.pytorch.org/whl/cpu
```
Please refer to the [PyTorch Installation Guide](https://pytorch.org/get-started/locally/) for other options.
</details>
<details>
<summary>Verify installation</summary>
```bash
# Run tests
pytest -v -s ./tests/unit
# Run code quality checks
pre-commit run --all-files
```
</details>
---
## Quick Start
### Hello, OpenVINO XAI
Let's imagine the case that our OpenVINO model is up and running on a inference pipeline.
While watching the outputs, we may want to analyze the model's behavior for debugging or understanding purposes.
By using the **OpenVINO XAI** `Explainer`, we can visualize why the model gives such responses.
In this example, we are trying to know the reason why the model outputs a `cheetah` label for the given input image.
```python
import cv2
import numpy as np
import openvino as ov
import openvino_xai as xai
# Load the model: IR or ONNX
ov_model: ov.Model = ov.Core().read_model("mobilenet_v3.xml")
# Load the image to be analyzed
image: np.ndarray = cv2.imread("tests/assets/cheetah_person.jpg")
image = cv2.resize(image, dsize=(224, 224))
image = np.expand_dims(image, 0)
# Create the Explainer for the model
explainer = xai.Explainer(
model=ov_model, # accepts path arguments "mobilenet_v3.xml" or "mobilenet_v3.onnx" as well
task=xai.Task.CLASSIFICATION,
)
# Generate saliency map for the label of interest
explanation: xai.Explanation = explainer(
data=image,
targets=293, # (cheetah), accepts label indices or actual label names if label_names provided
overlay=True, # saliency map overlay over the input image, defaults to False
)
# Save saliency maps to output directory
explanation.save(dir_path="./output")
```
Original image | Explained image
---------------|----------------
 | 
We can see that model is focusing on the body or skin area of the animals to tell if this image contains actual cheetahs.
### Insert XAI head to your models
Using the `insert_xai` API, we can insert XAI head to existing OpenVINO or PyTorch models directly and get additional "saliency_map" output in the same inference pipeline.
```python
import torch
import timm
# Get a PyTorch model from TIMM
torch_model: torch.nn.Module = timm.create_model("resnet18.a1_in1k", in_chans=3, pretrained=True)
# Insert XAI head
model_xai: torch.nn.Module = xai.insert_xai(torch_model, xai.Task.CLASSIFICATION)
# Torch XAI model inference
model_xai.eval()
with torch.no_grad():
outputs = model_xai(torch.from_numpy(image_norm))
logits = outputs["prediction"] # BxC
saliency_maps = outputs["saliency_map"] # BxCxHxW: per-class saliency map
```
### More advanced use-cases
Users could tweak the basic use-case according to their purpose, which include but not limited to:
* Select XAI mode (White-Box or Black-Box) or even specific method which are automatically decided by default
* Provide custom model pre/post processing functions like resize and normalizations which the model expects
* Customize output image visualization options
* Explain multiple class targets, passing them as label indices or as actual label names
* Call explainer multiple times to explain multiple images or to use different targets
* Insert XAI head to your PyTorch models and export to ONNX format to generate saliency maps on ONNX Runtime
(Refer to the [full example script](./examples/run_torch_onnx.py))
Please find more options and scenarios in the following links:
* [OpenVINO XAI User Guide](docs/source/user-guide.md)
* [OpenVINO Notebook - XAI Basic](https://github.com/openvinotoolkit/openvino_notebooks/blob/latest/notebooks/explainable-ai-1-basic/explainable-ai-1-basic.ipynb)
* [OpenVINO Notebook - XAI Deep Dive](https://github.com/openvinotoolkit/openvino_notebooks/blob/latest/notebooks/explainable-ai-2-deep-dive/explainable-ai-2-deep-dive.ipynb)
* [OpenVINO Notebook - Saliency Map Interpretation](https://github.com/openvinotoolkit/openvino_notebooks/blob/latest/notebooks/explainable-ai-3-map-interpretation/explainable-ai-3-map-interpretation.ipynb)
### Playing with the examples
Please look around the runnable [example scripts](./examples) and play with them to get used to the `Explainer` and `insert_xai` APIs.
```bash
# Prepare models by running tests (need "pip install openvino_xai[dev]" extra option)
# Models are downloaded and stored in .data/otx_models
pytest tests/test_classification.py
# Run a bunch of classification examples
# All outputs will be stored in the corresponding output directory
python examples/run_classification.py .data/otx_models/mlc_mobilenetv3_large_voc.xml \
tests/assets/cheetah_person.jpg --output output
# Run PyTorch and ONNX support example
python examples/run_torch_onnx.py
```
---
## Contributing
For those who would like to contribute to the library, please refer to the [contribution guide](CONTRIBUTING.md) for details.
Please let us know via the [Issues tab](https://github.com/openvinotoolkit/openvino_xai/issues/new) if you have any issues, feature requests, or questions.
Thank you! We appreciate your support!
<a href="https://github.com/openvinotoolkit/openvino_xai/graphs/contributors">
<img src="https://contrib.rocks/image?repo=openvinotoolkit/openvino_xai" />
</a>
---
## License
OpenVINO™ Toolkit is licensed under [Apache License Version 2.0](LICENSE).
By contributing to the project, you agree to the license and copyright terms therein and release your contribution under these terms.
---
## Disclaimer
Intel is committed to respecting human rights and avoiding complicity in human rights abuses.
See Intel's [Global Human Rights Principles](https://www.intel.com/content/www/us/en/policy/policy-human-rights.html).
Intel's products and software are intended only to be used in applications that do not cause or contribute to a violation of an internationally recognized human right.
---
Raw data
{
"_id": null,
"home_page": null,
"name": "openvino-xai",
"maintainer": "Intel(R) Corporation",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "openvino-toolkit, explainable-ai, xai, cnn, transformer, black-box, white-box",
"author": "Intel(R) Corporation",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/34/46/73fa23ba69cab1b9adc279d1f5794526fea3eaf1a7ae25a688ecff9f8d7d/openvino_xai-1.1.0.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n\n# OpenVINO\u2122 Explainable AI Toolkit - OpenVINO XAI\n\n---\n\n[Features](#features) \u2022\n[Install](#installation) \u2022\n[Quick Start](#quick-start) \u2022\n[License](#license) \u2022\n[Documentation](https://openvinotoolkit.github.io/openvino_xai/releases/1.1.0)\n\n\n[](https://pypi.org/project/openvino/)\n[](https://codecov.io/gh/openvinotoolkit/openvino_xai)\n[](https://opensource.org/licenses/Apache-2.0)\n[](https://pypi.org/project/openvino_xai)\n[](https://pepy.tech/project/openvino_xai)\n\n---\n\n</div>\n\n\n\n**OpenVINO\u2122 Explainable AI (XAI) Toolkit** provides a suite of XAI algorithms for visual explanation of\n[**OpenVINO\u2122**](https://github.com/openvinotoolkit/openvino) as well as [**PyTorch**](https://pytorch.org) and [**ONNX**](https://onnx.ai/) models.\n\nGiven AI models and input images, **OpenVINO XAI** generates **saliency maps**\nwhich highlights regions of the interest in the inputs from the models' perspective\nto help users understand the reason why the complex AI models output such responses.\n\nUsing this package, you can augment the model analysis & explanation feature\non top of the existing OpenVINO inference pipeline with a few lines of code.\n\n```python\nimport openvino_xai as xai\n\nexplainer = xai.Explainer(model=ov_model, task=xai.Task.CLASSIFICATION)\n\n# Existing inference pipeline\nfor i, image in enumerate(images):\n labels = infer(model=ov_model, image=image)\n\n # Model analysis\n explanation = explainer(data=image, targets=labels)\n explanation.save(dir_path=\"./xai\", name=str(i))\n```\n\n---\n\n## Features\n\n### What's new in v1.1.0\n\n* Support PyTorch models with `insert_xai()` API for saliency map generation on PyTorch / ONNX runtime\n* Support OpenVINO IR (.xml) / ONNX (.onnx) model files for `Explainer`\n* Enable AISE method: Adaptive Input Sampling for Explanation of Black-box Models\n* Add Pointing Game, Insertion-Deletion AUC and ADCC quality metrics for saliency maps\n* Upgrade OpenVINO to 2024.4.0\n* Add saliency map visualization with explanation.plot()\n* Enable flexible naming for saved saliency maps and include confidence scores\n\nPlease refer to the [change logs](CHANGELOG.md) for the full release history.\n\n### Supported XAI methods\n\nAt the moment, *Image Classification* and *Object Detection* tasks are supported for the *Computer Vision* domain.\n*Black-Box* (model agnostic but slow) methods and *White-Box* (model specific but fast) methods are supported:\n\n| Domain | Task | Type | Algorithm | Links |\n|-----------------|----------------------|-----------|------------------------|-------|\n| Computer Vision | Image Classification | White-Box | ReciproCAM | [arxiv](https://arxiv.org/abs/2209.14074) / [src](openvino_xai/methods/white_box/recipro_cam.py) |\n| | | | VITReciproCAM | [arxiv](https://arxiv.org/abs/2310.02588) / [src](openvino_xai/methods/white_box/recipro_cam.py) |\n| | | | ActivationMap | experimental / [src](openvino_xai/methods/white_box/activation_map.py) |\n| | | Black-Box | AISEClassification | [src](openvino_xai/methods/black_box/aise/classification.py) |\n| | | | RISE | [arxiv](https://arxiv.org/abs/1806.07421v3) / [src](openvino_xai/methods/black_box/rise.py) |\n| | Object Detection | White-Box | DetClassProbabilityMap | experimental / [src](openvino_xai/methods/white_box/det_class_probability_map.py) |\n| | | Black-Box | AISEDetection | [src](openvino_xai/methods/black_box/aise/detection.py) |\n\nSee more method comparison at the [User Guide](docs/source/user-guide.md).\n\n### Supported explainable models\n\nMost of CNNs and Transformer models from [Pytorch Image Models (timm)](https://github.com/huggingface/pytorch-image-models) are supported and validated.\n\nPlease refer to the following known issues for unsupported models and reasons.\n\n* [Runtime error from ONNX / OpenVINO IR models while conversion or inference for XAI (#29)](https://github.com/openvinotoolkit/openvino_xai/issues/29)\n* [Models not supported by white box XAI methods (#30)](https://github.com/openvinotoolkit/openvino_xai/issues/30)\n\n> **_NOTE:_** GenAI / LLMs would be also supported incrementally in the upcoming releases.\n\n---\n\n## Installation\n\n> **_NOTE:_** OpenVINO XAI works on Python 3.10 or higher\n\n<details>\n<summary>Set up environment</summary>\n\n```bash\n# Create virtual env.\npython3.10 -m venv .ovxai\n\n# Activate virtual env.\nsource .ovxai/bin/activate\n```\n</details>\n\nInstall from PyPI package\n\n```bash\n# Base package (for normal use):\npip install openvino_xai\n\n# Dev package (for development):\npip install openvino_xai[dev]\n```\n\n<details>\n<summary>Install from source</summary>\n\n```bash\n# Clone the source repository\ngit clone https://github.com/openvinotoolkit/openvino_xai.git\ncd openvino_xai\n\n# Editable mode (for development):\npip install -e .[dev]\n```\n</details>\n\n<details>\n<summary>(Optional) Enable PyTorch support</summary>\n\nYou can enjoy the PyTorch XAI feature if the PyTorch is installed along with the OpenVINO XAI.\n\n```bash\n# Install PyTorch (CPU version as example)\npip3 install torch --index-url https://download.pytorch.org/whl/cpu\n```\nPlease refer to the [PyTorch Installation Guide](https://pytorch.org/get-started/locally/) for other options.\n</details>\n\n<details>\n<summary>Verify installation</summary>\n\n```bash\n# Run tests\npytest -v -s ./tests/unit\n\n# Run code quality checks\npre-commit run --all-files\n```\n</details>\n\n---\n\n## Quick Start\n\n### Hello, OpenVINO XAI\n\nLet's imagine the case that our OpenVINO model is up and running on a inference pipeline.\nWhile watching the outputs, we may want to analyze the model's behavior for debugging or understanding purposes.\n\nBy using the **OpenVINO XAI** `Explainer`, we can visualize why the model gives such responses.\nIn this example, we are trying to know the reason why the model outputs a `cheetah` label for the given input image.\n\n```python\nimport cv2\nimport numpy as np\nimport openvino as ov\nimport openvino_xai as xai\n\n# Load the model: IR or ONNX\nov_model: ov.Model = ov.Core().read_model(\"mobilenet_v3.xml\")\n\n# Load the image to be analyzed\nimage: np.ndarray = cv2.imread(\"tests/assets/cheetah_person.jpg\")\nimage = cv2.resize(image, dsize=(224, 224))\nimage = np.expand_dims(image, 0)\n\n# Create the Explainer for the model\nexplainer = xai.Explainer(\n model=ov_model, # accepts path arguments \"mobilenet_v3.xml\" or \"mobilenet_v3.onnx\" as well\n task=xai.Task.CLASSIFICATION,\n)\n\n# Generate saliency map for the label of interest\nexplanation: xai.Explanation = explainer(\n data=image,\n targets=293, # (cheetah), accepts label indices or actual label names if label_names provided\n overlay=True, # saliency map overlay over the input image, defaults to False\n)\n\n# Save saliency maps to output directory\nexplanation.save(dir_path=\"./output\")\n```\n\nOriginal image | Explained image\n---------------|----------------\n | \n\nWe can see that model is focusing on the body or skin area of the animals to tell if this image contains actual cheetahs.\n\n### Insert XAI head to your models\n\nUsing the `insert_xai` API, we can insert XAI head to existing OpenVINO or PyTorch models directly and get additional \"saliency_map\" output in the same inference pipeline.\n\n```python\nimport torch\nimport timm\n\n# Get a PyTorch model from TIMM\ntorch_model: torch.nn.Module = timm.create_model(\"resnet18.a1_in1k\", in_chans=3, pretrained=True)\n\n# Insert XAI head\nmodel_xai: torch.nn.Module = xai.insert_xai(torch_model, xai.Task.CLASSIFICATION)\n\n# Torch XAI model inference\nmodel_xai.eval()\nwith torch.no_grad():\n outputs = model_xai(torch.from_numpy(image_norm))\n logits = outputs[\"prediction\"] # BxC\n saliency_maps = outputs[\"saliency_map\"] # BxCxHxW: per-class saliency map\n```\n\n### More advanced use-cases\n\nUsers could tweak the basic use-case according to their purpose, which include but not limited to:\n\n* Select XAI mode (White-Box or Black-Box) or even specific method which are automatically decided by default\n* Provide custom model pre/post processing functions like resize and normalizations which the model expects\n* Customize output image visualization options\n* Explain multiple class targets, passing them as label indices or as actual label names\n* Call explainer multiple times to explain multiple images or to use different targets\n* Insert XAI head to your PyTorch models and export to ONNX format to generate saliency maps on ONNX Runtime\n (Refer to the [full example script](./examples/run_torch_onnx.py))\n\nPlease find more options and scenarios in the following links:\n\n* [OpenVINO XAI User Guide](docs/source/user-guide.md)\n* [OpenVINO Notebook - XAI Basic](https://github.com/openvinotoolkit/openvino_notebooks/blob/latest/notebooks/explainable-ai-1-basic/explainable-ai-1-basic.ipynb)\n* [OpenVINO Notebook - XAI Deep Dive](https://github.com/openvinotoolkit/openvino_notebooks/blob/latest/notebooks/explainable-ai-2-deep-dive/explainable-ai-2-deep-dive.ipynb)\n* [OpenVINO Notebook - Saliency Map Interpretation](https://github.com/openvinotoolkit/openvino_notebooks/blob/latest/notebooks/explainable-ai-3-map-interpretation/explainable-ai-3-map-interpretation.ipynb)\n\n### Playing with the examples\n\nPlease look around the runnable [example scripts](./examples) and play with them to get used to the `Explainer` and `insert_xai` APIs.\n\n```bash\n# Prepare models by running tests (need \"pip install openvino_xai[dev]\" extra option)\n# Models are downloaded and stored in .data/otx_models\npytest tests/test_classification.py\n\n# Run a bunch of classification examples\n# All outputs will be stored in the corresponding output directory\npython examples/run_classification.py .data/otx_models/mlc_mobilenetv3_large_voc.xml \\\ntests/assets/cheetah_person.jpg --output output\n\n# Run PyTorch and ONNX support example\npython examples/run_torch_onnx.py\n```\n\n---\n\n## Contributing\n\nFor those who would like to contribute to the library, please refer to the [contribution guide](CONTRIBUTING.md) for details.\n\nPlease let us know via the [Issues tab](https://github.com/openvinotoolkit/openvino_xai/issues/new) if you have any issues, feature requests, or questions.\n\nThank you! We appreciate your support!\n\n<a href=\"https://github.com/openvinotoolkit/openvino_xai/graphs/contributors\">\n <img src=\"https://contrib.rocks/image?repo=openvinotoolkit/openvino_xai\" />\n</a>\n\n---\n\n## License\n\nOpenVINO\u2122 Toolkit is licensed under [Apache License Version 2.0](LICENSE).\nBy contributing to the project, you agree to the license and copyright terms therein and release your contribution under these terms.\n\n---\n\n## Disclaimer\n\nIntel is committed to respecting human rights and avoiding complicity in human rights abuses.\nSee Intel's [Global Human Rights Principles](https://www.intel.com/content/www/us/en/policy/policy-human-rights.html).\nIntel's products and software are intended only to be used in applications that do not cause or contribute to a violation of an internationally recognized human right.\n\n---\n",
"bugtrack_url": null,
"license": "Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. \"License\" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. \"Licensor\" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. \"Legal Entity\" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, \"control\" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. \"You\" (or \"Your\") shall mean an individual or Legal Entity exercising permissions granted by this License. \"Source\" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. \"Object\" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. \"Work\" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). \"Derivative Works\" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. \"Contribution\" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, \"submitted\" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as \"Not a Contribution.\" \"Contributor\" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a \"NOTICE\" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets \"[]\" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same \"printed page\" as the copyright notice for easier identification within third-party archives. Copyright (C) 2018-2021 Intel Corporation Licensed under the Apache License, Version 2.0 (the \"License\"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ",
"summary": "OpenVINO\u2122 Explainable AI (XAI) Toolkit: Visual Explanation for OpenVINO Models",
"version": "1.1.0",
"project_urls": {
"Documentation": "https://openvinotoolkit.github.io/openvino_xai/",
"Homepage": "https://github.com/openvinotoolkit/openvino_xai",
"Repository": "https://github.com/openvinotoolkit/openvino_xai.git"
},
"split_keywords": [
"openvino-toolkit",
" explainable-ai",
" xai",
" cnn",
" transformer",
" black-box",
" white-box"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d45f9244da2685b64e64843835b74da0353e72f8fd3bc27e14fc069692af0680",
"md5": "7f534da664464417c29735f6180f3da2",
"sha256": "ce5c0529decb0d7fc208b07f0ba48bea16e3851bafc204f19ea7998817834cfd"
},
"downloads": -1,
"filename": "openvino_xai-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7f534da664464417c29735f6180f3da2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 69829,
"upload_time": "2024-10-02T08:27:19",
"upload_time_iso_8601": "2024-10-02T08:27:19.805567Z",
"url": "https://files.pythonhosted.org/packages/d4/5f/9244da2685b64e64843835b74da0353e72f8fd3bc27e14fc069692af0680/openvino_xai-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "344673fa23ba69cab1b9adc279d1f5794526fea3eaf1a7ae25a688ecff9f8d7d",
"md5": "3b93b6857964d4d4fcb4e59df98b2396",
"sha256": "7034a2b86c15eccbc06fd2ca8ca05e1d8f9f71c9bb4b3aa6b4c5a8a11c0ffc5c"
},
"downloads": -1,
"filename": "openvino_xai-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "3b93b6857964d4d4fcb4e59df98b2396",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 54779,
"upload_time": "2024-10-02T08:27:22",
"upload_time_iso_8601": "2024-10-02T08:27:22.365423Z",
"url": "https://files.pythonhosted.org/packages/34/46/73fa23ba69cab1b9adc279d1f5794526fea3eaf1a7ae25a688ecff9f8d7d/openvino_xai-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-02 08:27:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "openvinotoolkit",
"github_project": "openvino_xai",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "openvino-xai"
}
