bellatrex 0.3.1

Explaining Random Forest model predictions by Building Explanations through a LocaLly AccuraTe Rule EXtractor

Bellatrex: Explain your Random Forest predictions

Bellatrex is a Python library designed to generate concise, interpretable, and visually appealing explanations for predictions made by Random Forest models. The name says it all: Bellatrex stands for Building Explanations through a LocalLy AccuraTe Rule EXtractor.

Curious about the details and inner mechanisms of Bellatrex? Check out our paper and jump into the reproducibility branch to dive into the experiments.

How Bellatrex works

When explaining a prediction for a specific test instance, Bellatrex:

1. pre-selects a subset of the rules used to make the prediction;
2. creates a vector representation of such rules and (optionally) projects them into a low-dimensional space
3. clusters such representations to pick a rule from each cluster to explain the instance prediction.
4. Shows the selected rule through visually appealing plots, and the tool's GUI allows users to explore similar rules to those extracted.

Overview of Bellatrex, starting from top left, proceeding clockwise, we reach the output with related explanations on the bottom left.

Supported models and tasks

The current support of Bellatrex focuses on Random Forest models implemented via scikit-learn and scikit-survival:

• Classification tasks and multi-label classification via RandomForestClassifier
• Regression tasks and multi-target regression via RandomForestRegressor
• Survival Analysis (time-to-event predictions with censoring) via RandomSurvivalForest

Set-up

To install the standard version of Bellatrex (without an interacting GUI), run:

pip install bellatrex

If this step fails and you don't find a solution immediately, please open an issue. In the meantime, you can also try to clone the repository manually.

Interactive GUI mode

For an enhanced user experience that includes interactive plots, you can run:

pip install bellatrex[gui]

or manually install the following additional packages:

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 might have 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? Quickstart tutorial

If you have downloaded the content of this folder and installed the packages successfully, you can dive into tutorial.ipynb and try Bellatrex yourself.

Support and Contributions

Bellatrex is an open-source project that was initially developed from research funding by Flanders AI. 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: if you encounter any bugs, inconsistencies, or simply find areas for improvement, open an issue and share example code and error traces.
• ⭐ Give a star Bellatrex: it will make the project more visible to others and motivate ongoing voluntary development.

Refrences

Please cite the following paper if you are using Bellatrex:

Dedja, K., Nakano, F.K., Pliakos, K. and Vens, C., 2023. BELLATREX: Building explanations through a locally accurate rule extractor. Ieee Access, 11, pp.41348-41367.

@article{dedja2023bellatrex,
  title={BELLATREX: Building explanations through a locally accurate rule extractor},
  author={Dedja, Klest and Nakano, Felipe Kenji and Pliakos, Konstantinos and Vens, Celine},
  journal={Ieee Access},
  volume={11},
  pages={41348--41367},
  year={2023},
  publisher={IEEE}
}