pyxai 0.8.1

Explaining Machine Learning Classifiers in Python

PyXAI - Python eXplainable AI

PyXAI is a Python library (version 3.6 or later) allowing to bring explanations of various forms from classifiers resulting of machine learning techniques (Decision Tree, Random Forest, Boosted Tree).

More precisely, several types of explanations for the classification task of a given instance X can be computed:

• Abductive explanations for X are intended to explain why X has been classified in the way it has been classified by the ML model (thus, addressing the “Why?” question).
• Contrastive explanations for X is to explain why X has not been classified by the ML model as the user expected it (thus, addressing the “Why not?” question).

In addition to finding explanations, PyXAI also contains methods that perform operations (production, saving, loading) on models and instances. Currently, these helping methods are available using two ML libraries:

• Scikit-learn: a software machine learning library
• XGBoost: an optimized distributed gradient boosting library

Note that it is quite possible to find explanations of models coming from other libraries.

As an illustration, below, you can find an example of use (coming from the documentation):

from pyxai import Learning, Explainer, Tools

MLsolver = Learning.Scikitlearn("../dataset/iris.csv")
model = MLsolver.evaluate(method=Learning.HOLD_OUT, output=Learning.DT)
instance, prediction = MLsolver.get_instances(model, n=1, correct=True, predictions=[0])

explainer = Explainer.initialize(model, instance)
print("instance:", instance)
print("implicant:", explainer.binary_representation)

sufficient_reason = explainer.sufficient_reason(n=1)
print("sufficient_reason:", sufficient_reason)
print("to_features:", explainer.to_features(sufficient_reason))

instance, prediction = MLsolver.get_instances(model, n=1, correct=False)
explainer.set_instance(instance)
contrastive_reason = explainer.contrastive_reason()
print("contrastive reason", contrastive_reason)
print("to_features:", explainer.to_features(contrastive_reason))

Installation

Installation from PyPi

The Python Package Index (PyPi) is the easiest way of installing PyXAI.

Note that you need first Python 3 (version 3.6, or later) to be installed. You can do it, for example, from python.org

Installing PyXAI (Linux)

Check if 'python3-pip' is installed. If it is not the case, execute:

sudo apt install python3-pip

Or check if you have the last installed version:

python3 -m pip install --upgrade pip

Then, install PyXAI with the command 'pip3':

python3 -m pip install pyxai

Installing PyXAI (Mac OS)

PyXAI is currently compatible with Mac OS but without PyPi, see the installation (alternative) by Cloning from GitHub section for more details.

Installing PyXAI (Windows)

PyXAI is currently not compatible with windows (work in progress).

Updating the Version of PyXAI (for PyPi)

For updating your version of PyXAI, simply execute:

For linux/Mac:

python3 -m pip install -U pyxai

Installation (alternative) by Cloning from GitHub

An alternative to PyPi is to clone the code from GitHub.

Here is an illustration for linux. We assume that Python 3 is installed, and consequently 'pip3' is also installed. In a console, type:

git clone https://gitlab.univ-artois.fr/expekctation/software/PyLearningExplanation.git

You may need to update the environment variable 'PYTHONPATH', by typing for example:

export PYTHONPATH="${PYTHONPATH}:${PWD}/.."

Get the last version of pip:

python3 -m pip install --upgrade pip

There are a few packages that PyXAI depends on that must be installed:

python3 -m pip install numpy
python3 -m pip install wheel
python3 -m pip install pandas
python3 -m pip install termcolor
python3 -m pip install shap
python3 -m pip install wordfreq
python3 -m pip install python-sat[pblib,aiger]
python3 -m pip install xgboost
python3 -m pip install lxml
python3 -m pip install pycsp3
python3 -m pip install matplotlib

To compile the c++ code (python C extensions):

python3 setup.py install --user

Of course, for this step, you need a C++ compiler.

Unfortunately, the compiled C extensions are not take into account in a virtual environment, therefore you must type (we consider here that the virtual environment is in the 'env' directory and you are in the 'PyXAI' directory):

cp build/lib.linux-x86_64-3.6/c_explainer.cpython-36m-x86_64-linux-gnu.so env/lib/python3.6/site-packages/.

This last command depend of your python version (here: 3.6).

Finally, you can test an example:

python3 examples/DT/BuilderOrchids.py 

Virtual Environment

Create and activate a new virtual environment:

sudo apt-get install python3.6-venv
python3.6 -m venv env
source env/bin/activate

Update pip:

python3.6 -m pip install -U pip

With this new version of pip, it is possible that you have to clear the pip cache:

python3 -m pip cache purge

Now you can do the "Installation from PyPi" or the "Installation (alternative) by Cloning from GitHub".

Note that if you want install dependencies without internet connection, you can build a requirement.txt file:

python3.6 -m pip freeze > requirements.txt 
python3.6 -m pip download -r requirements.txt -d requirements-download/
pip install -r requirements.txt --find-links=requirements-download --no-index

For deactivating the environment:

deactivate