This repo is being made available as a static archive. It has been released by Fidelity Investments under the Apache 2.0 license, and will not receive updates. If you have questions, please contact opensource@fidelity.com.
BoolXAI (MAKE'23, ArXiv'23) is a research library for Explainable AI (XAI) based on expressive Boolean formulas that allow And, Or, Choose(k), AtMost(k), and AtLeast(k) operators.
The Boolean formula defines a rule with tunable complexity (or interpretability), according to which input data are classified. Such a formula can include any operator that can be applied to one or more Boolean variables, thus providing higher expressiveness compared to more rigid rule-based and tree-based approaches. The classifier is trained using native local optimization techniques, efficiently searching the space of feasible formulas. For a high-level introduction, see the Fidelity blogpost, and for a technical introduction, see the Amazon AWS blogpost.
BoolXAI is developed by Amazon Quantum Solutions Lab, the FCAT Quantum and Future Computing Incubator, and the AI Center of Excellence at Fidelity Investments. Documentation is available at fidelity.github.io/boolxai.
The heart of BoolXAI is the rule classifier (BoolXAI.RuleClassifier), which can be
used as an interpretable ML model for binary classification. Note that the input data
must be binarized. Here's a simple example showing the basic usage. For additional
examples, including advanced usage, see the Usage Examples.
import numpy as np
from sklearn.metrics import balanced_accuracy_score
from boolxai import BoolXAI, Operator
# Create random toy data for binary classification. X and y must be binary!
rng = np.random.default_rng(seed=42)
X = rng.choice([0, 1], size=(100, 10))
y = rng.choice([0, 1], size=100)
# Rule classifier with maximum depth, complexity, possible operators
rule_classifier = BoolXAI.RuleClassifier(max_depth=3,
max_complexity=6,
operators=[Operator.And, Operator.Or, Operator.Choose, Operator.AtMost, Operator.AtLeast],
random_state=42)
# Learn the best rule
rule_classifier.fit(X, y)
# Best rule and best score
best_rule = rule_classifier.best_rule_
best_score = rule_classifier.best_score_
print(f"{best_rule=} {best_score=:.2f}")
# The depth of a rule is the number of edges in the longest path from the root to any leaf/literal.
# The complexity of a rule is the total number of operators and literals.
print(f"depth={best_rule.depth()} complexity={best_rule.complexity()}")
# Predict and score
y_pred = rule_classifier.predict(X)
score = balanced_accuracy_score(y, y_pred)
print(f"{score=:.2f}")
# It is also possible to plot the best rule --requires installing plot dependencies
best_rule.plot()
# or get a networkx.DiGraph representation of the rule --requires installing plot dependencies
G = best_rule.to_graph()
print(G)- Training a rule classifier
- Interpreting and visualizing the rules
- Number of starts (num_starts)
- Bagging (max_samples)
- Parallelization (num_jobs)
- Cross-Validation
- Pareto frontier (max_complexity)
- Boolean operators
- Custom operators
- Partial optimization (base_rule)
- Boosting
- Multi-label classification
- Multi-class classification
We recommend installing BoolXAI in a virtual environment.
It can be installed from PyPI using:
pip install boolxai
Alternatively, clone this repo and use:
pip install -e .
In order to plot the best rule and get its networkx graph, additional dependencies are required, which can be installed using:
pip install boolxai[plot]
In order to run the Notebook Usage Examples, additional dependencies are required, which can be installed using:
pip install -r notebooks/requirements.txt
Note that it's recommended to create a Jupyter notebook kernel for this repository and run the notebooks using it, for example:
python3 -m ipykernel install --user --name boolxai
This library requires Python 3.8+.
See requirements.txt for dependencies. For plotting, see requirements_plot.txt and graphviz must be installed separately (see instructions) - it cannot be installed using pip.
If you use BoolXAI in a publication, please cite it as:
@Article{boolxai2023,
AUTHOR = {Rosenberg, Gili and Brubaker, John Kyle and Schuetz, Martin J. A. and Salton, Grant and Zhu, Zhihuai and Zhu, Elton Yechao and Kadıoğlu, Serdar and Borujeni, Sima E. and Katzgraber, Helmut G.},
TITLE = {Explainable Artificial Intelligence Using Expressive Boolean Formulas},
JOURNAL = {Machine Learning and Knowledge Extraction},
VOLUME = {5},
YEAR = {2023},
NUMBER = {4},
PAGES = {1760--1795},
URL = {https://www.mdpi.com/2504-4990/5/4/86},
ISSN = {2504-4990},
DOI = {10.3390/make5040086}
}Please submit bug reports, questions, and feature requests as GitHub Issues.
BoolXAI is licensed under the Apache License 2.0.