| Name | bellatrex JSON |
| Version |
0.3.0
JSON |
| download |
| home_page | None |
| Summary | Explaining Random Forest model predictions by Building Explanations through a LocaLly AccuraTe Rule EXtractor |
| upload_time | 2025-07-22 22:40:07 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | <3.13,>=3.9 |
| license | Copyright (c) 2024 Klest Dedja
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
|
| keywords |
explainable ai
rule extraction
random forest
surrogate models
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<a name="logo-anchor"></a>
<p align="center">
<img src="https://github.com/Klest94/Bellatrex/blob/main-dev/app/bellatrex-logo.png?raw=true" alt="Bellatrex Logo" width="60%"/>
</p>
[](https://pypi.org/project/bellatrex/)
[](https://pepy.tech/project/bellatrex)
[](https://github.com/Klest94/Bellatrex/blob/main-dev/LICENSE)
[](https://github.com/Klest94/Bellatrex/actions/workflows/test-windows.yml)
[](https://pypi.org/project/bellatrex/)
# Welcome to Bellatrex!
Random Forest models can be difficult to interpret, and Bellatrex addresses this challenge by generating explanations that are easy to understand, and by providing insights into how the model arrived at its predictions. Bellatrex does so by Building Explanations through a LocalLy AccuraTe Rule EXtractor (hence the name: Bellatrex) for a given test instance, by extracting only a few, diverse rules. See [the published paper](https://ieeexplore.ieee.org/abstract/document/10105927) for more details. The code for reproducing its results is available in a different [GitHub branch](https://github.com/Klest94/Bellatrex/tree/archive/reproduce-Dedja2023).
To illustrate how Bellatrex works, let's consider an example: when a user provides a test instance to Bellatrex, the tool begins by 1) pre-selecting a subset of the rules used to make the prediction; it then creates 2) a vector representation of such rules and 3) projects them to a low-dimensional space; Bellatrex then 4) clusters such representations to pick a rule from each cluster to explain the instance prediction. One rule per cluster is shown to the end user through visually appealing plots, and the tool's GUI allows users to explore similar rules to those extracted.
<table>
<tr>
<td align="center">
<img src="https://github.com/Klest94/Bellatrex/blob/main-dev/app/illustration-Bellatrex.png?raw=true" alt="Bellatrex image" width="90%"/>
</td>
</tr>
<tr>
<td align="left">
<em>Overview of Bellatrex, starting from top left, proceeding clockwise, we reach the output with related explanations on the bottom left. </em>
</td>
</tr>
</table>
Another strength of Bellatrex lies in its ability to handle several prediction tasks within `scikit-learn` implementations of Random Forests. For instance, Bellatrex can generate explanations for binary classification and multi-label predictions tasks with `RandomForestClassifier`, as well as single- or multi-output regression tasks with `RandomForestRegressor`. Moreover, Bellatrex is compatible with scikit-survival's `RandomSurvivalForest`, allowing it to generate explanations for time-to-event predictions in the presence of right-censored data.
This repository contains:
- instructions to run Bellatrex on your machine
- an overview of the datasets used to test the effectiveness of the method
- access to such datasets, as they appear after the pre-processing step.
# Set-up
To install the standard version of Bellatrex, run:
```
pip install bellatrex
```
In case the previous step does not work, then the ``pip`` distribution is not working as expected so please [contact us](https://mail.google.com/mail/u/0/?fs=1&tf=cm&source=mailto&to=daneel.olivaw94@gmail.com), and in the meantime try with a manual [clone](https://github.com/Klest94/Bellatrex) from the repository.
## Enable Graphical User Interface
For an enhanced user experience that includes interactive plots, you can run:
```
pip install bellatrex[gui]
```
or manually install the following packages on top of bellatrex:
```
pip install dearpygui==1.6.2
pip install dearpygui-ext==0.9.5
```
**Note:** When running Bellatrex with the GUI for multiple test samples, the program will generate an interactive window. The process may take a couple of seconds, and the the user has to click at least once within the generated window in order to activate the interactive mode. Once this is done, the user can explore the generated rules by clicking on the corresponding representation. To show the Bellatrex explanation for the next sample, close the interactive window and wait until Bellatrex generates the explanation for the new sample.
# Ready to go!
If you have downloaded the content of this folder and installed the packages successfully, you can dive into [`tutorial.ipynb`](https://github.com/Klest94/Bellatrex/blob/main-dev/tutorial.ipynb) and try Bellatrex yourself.
## Enjoying Bellatrex?
Bellatrex is an open-source project that was initially developed with support from research funding provided by [Flanders AI](https://www.flandersai.be/en). Since the end of that funding period, the project has been maintained through __volunteer__ work, but there is always exiting work ahead: new features, performance improvements, tests for robustness... if you find Bellatrex useful or believe in its goals, there are several meaningful ways you can help support its ongoing development:
### 🐛 Test and Report Issues
Use Bellatrex in your own projects and let us know how it performs. If you encounter any bugs, inconsistencies, open an [issue](https://github.com/Klest94/Bellatrex/issues) and share example code and error traces.
If you find areas for improvement, send us feedback alos by opening an [issue](https://github.com/Klest94/Bellatrex/issues).
### ⭐ Star Bellatrex
Easy: simply add a ⭐ to the project. It will make the project more visible to others and motivate ongoing voluntary development.
Raw data
{
"_id": null,
"home_page": null,
"name": "bellatrex",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.9",
"maintainer_email": null,
"keywords": "explainable AI, rule extraction, random forest, surrogate models",
"author": null,
"author_email": "Klest Dedja <daneel.olivaw94@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/99/cb/13bcea9b7ece7b909fac350d74ec712118fd44f830c28c48b1a9c795958d/bellatrex-0.3.0.tar.gz",
"platform": null,
"description": "<a name=\"logo-anchor\"></a>\n<p align=\"center\">\n<img src=\"https://github.com/Klest94/Bellatrex/blob/main-dev/app/bellatrex-logo.png?raw=true\" alt=\"Bellatrex Logo\" width=\"60%\"/>\n</p>\n\n[](https://pypi.org/project/bellatrex/)\n[](https://pepy.tech/project/bellatrex)\n[](https://github.com/Klest94/Bellatrex/blob/main-dev/LICENSE)\n[](https://github.com/Klest94/Bellatrex/actions/workflows/test-windows.yml)\n[](https://pypi.org/project/bellatrex/)\n\n\n\n# Welcome to Bellatrex!\n\nRandom Forest models can be difficult to interpret, and Bellatrex addresses this challenge by generating explanations that are easy to understand, and by providing insights into how the model arrived at its predictions. Bellatrex does so by Building Explanations through a LocalLy AccuraTe Rule EXtractor (hence the name: Bellatrex) for a given test instance, by extracting only a few, diverse rules. See [the published paper](https://ieeexplore.ieee.org/abstract/document/10105927) for more details. The code for reproducing its results is available in a different [GitHub branch](https://github.com/Klest94/Bellatrex/tree/archive/reproduce-Dedja2023).\n\nTo illustrate how Bellatrex works, let's consider an example: when a user provides a test instance to Bellatrex, the tool begins by 1) pre-selecting a subset of the rules used to make the prediction; it then creates 2) a vector representation of such rules and 3) projects them to a low-dimensional space; Bellatrex then 4) clusters such representations to pick a rule from each cluster to explain the instance prediction. One rule per cluster is shown to the end user through visually appealing plots, and the tool's GUI allows users to explore similar rules to those extracted.\n\n<table>\n <tr>\n <td align=\"center\">\n <img src=\"https://github.com/Klest94/Bellatrex/blob/main-dev/app/illustration-Bellatrex.png?raw=true\" alt=\"Bellatrex image\" width=\"90%\"/>\n </td>\n </tr>\n <tr>\n <td align=\"left\">\n <em>Overview of Bellatrex, starting from top left, proceeding clockwise, we reach the output with related explanations on the bottom left. </em>\n </td>\n </tr>\n</table>\n\n\nAnother strength of Bellatrex lies in its ability to handle several prediction tasks within `scikit-learn` implementations of Random Forests. For instance, Bellatrex can generate explanations for binary classification and multi-label predictions tasks with `RandomForestClassifier`, as well as single- or multi-output regression tasks with `RandomForestRegressor`. Moreover, Bellatrex is compatible with scikit-survival's `RandomSurvivalForest`, allowing it to generate explanations for time-to-event predictions in the presence of right-censored data.\n\n\nThis repository contains:\n- instructions to run Bellatrex on your machine\n- an overview of the datasets used to test the effectiveness of the method\n- access to such datasets, as they appear after the pre-processing step.\n\n# Set-up\n\nTo install the standard version of Bellatrex, run:\n\n```\npip install bellatrex\n```\n\nIn case the previous step does not work, then the ``pip`` distribution is not working as expected so please [contact us](https://mail.google.com/mail/u/0/?fs=1&tf=cm&source=mailto&to=daneel.olivaw94@gmail.com), and in the meantime try with a manual [clone](https://github.com/Klest94/Bellatrex) from the repository.\n\n\n## Enable Graphical User Interface\n\nFor an enhanced user experience that includes interactive plots, you can run: \n```\npip install bellatrex[gui]\n```\n\nor manually install the following packages on top of bellatrex:\n```\npip install dearpygui==1.6.2\npip install dearpygui-ext==0.9.5\n```\n\n**Note:** When running Bellatrex with the GUI for multiple test samples, the program will generate an interactive window. The process may take a couple of seconds, and the the user has to click at least once within the generated window in order to activate the interactive mode. Once this is done, the user can explore the generated rules by clicking on the corresponding representation. To show the Bellatrex explanation for the next sample, close the interactive window and wait until Bellatrex generates the explanation for the new sample.\n\n# Ready to go!\n\nIf you have downloaded the content of this folder and installed the packages successfully, you can dive into [`tutorial.ipynb`](https://github.com/Klest94/Bellatrex/blob/main-dev/tutorial.ipynb) and try Bellatrex yourself.\n\n## Enjoying Bellatrex?\n\nBellatrex is an open-source project that was initially developed with support from research funding provided by [Flanders AI](https://www.flandersai.be/en). Since the end of that funding period, the project has been maintained through __volunteer__ work, but there is always exiting work ahead: new features, performance improvements, tests for robustness... if you find Bellatrex useful or believe in its goals, there are several meaningful ways you can help support its ongoing development:\n\n### \ud83d\udc1b Test and Report Issues\n\nUse Bellatrex in your own projects and let us know how it performs. If you encounter any bugs, inconsistencies, open an [issue](https://github.com/Klest94/Bellatrex/issues) and share example code and error traces.\n\nIf you find areas for improvement, send us feedback alos by opening an [issue](https://github.com/Klest94/Bellatrex/issues).\n\n### \u2b50 Star Bellatrex\n\nEasy: simply add a \u2b50 to the project. It will make the project more visible to others and motivate ongoing voluntary development.\n\n",
"bugtrack_url": null,
"license": "Copyright (c) 2024 Klest Dedja\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "Explaining Random Forest model predictions by Building Explanations through a LocaLly AccuraTe Rule EXtractor",
"version": "0.3.0",
"project_urls": null,
"split_keywords": [
"explainable ai",
" rule extraction",
" random forest",
" surrogate models"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "72c539676f3b5964ad88a3da4ff85cd9666fc403f964769ca30fa71cc51a8b34",
"md5": "dfa4c7d922df3fddc22d5ff1d301d64f",
"sha256": "2fcf2db87400b4d058f9df9b1b19073b83a26cb56014126dd260841bc73786eb"
},
"downloads": -1,
"filename": "bellatrex-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dfa4c7d922df3fddc22d5ff1d301d64f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.9",
"size": 122375,
"upload_time": "2025-07-22T22:40:05",
"upload_time_iso_8601": "2025-07-22T22:40:05.752534Z",
"url": "https://files.pythonhosted.org/packages/72/c5/39676f3b5964ad88a3da4ff85cd9666fc403f964769ca30fa71cc51a8b34/bellatrex-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "99cb13bcea9b7ece7b909fac350d74ec712118fd44f830c28c48b1a9c795958d",
"md5": "6db92d8269e728dc7e0e3b9a9ba27c39",
"sha256": "b01f363e16007e11bd79e3a5c1f1409083f8f8d70219a628977e5edb6e2a02b1"
},
"downloads": -1,
"filename": "bellatrex-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "6db92d8269e728dc7e0e3b9a9ba27c39",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.9",
"size": 120365,
"upload_time": "2025-07-22T22:40:07",
"upload_time_iso_8601": "2025-07-22T22:40:07.051500Z",
"url": "https://files.pythonhosted.org/packages/99/cb/13bcea9b7ece7b909fac350d74ec712118fd44f830c28c48b1a9c795958d/bellatrex-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-22 22:40:07",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "bellatrex"
}
