boolxai 1.0.0

BoolXAI: Explainable AI using expressive Boolean formulas

BoolXAI: Explainable AI using expressive Boolean formulas

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 [e-mail].

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.

Quick Start

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)

Usage Examples

• 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

Installation

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

Requirements

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.

Citation

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}
}

Support

Please submit bug reports, questions, and feature requests as GitHub Issues.

License

BoolXAI is licensed under the Apache License 2.0.