Welcome to xMOAI’s documentation!
xMOAI is an open-source package implementing Explainable Artificial Intelligence (XAI) using Multiobjective Optimization (MOO). It is capable of generating a large number of counterfactuals in datasets with several attributes - most of them immutable or very constrained. It supports both regression or classification problems. For classification problems, it does support both problems with trained machine learning models exposing the predicted class probabilities or only the predicted class. It was tested throughly with trained models in scikit-learn, XGBoost, LightGBM and Tensorflow. In practice, it works with any model that exposes an output similar to scikit-learn or Tensorflow predict methods.
Example:
1import numpy as np
2
3from xmoai.setup.configure import generate_counterfactuals_classification_proba
4
5from sklearn.ensemble import RandomForestClassifier
6from sklearn.datasets import load_iris
7from sklearn.model_selection import train_test_split
8
9# seed
10random_state = 0
11
12# getting a dataset
13X, y = load_iris(return_X_y=True)
14X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2,
15 random_state=random_state)
16
17# training a machine learning model
18clf = RandomForestClassifier(max_depth=2, random_state=random_state)
19clf.fit(X_train, y_train)
20
21# getting an individual (X_original), its original prediction (y_original) and
22# the desired output (y_desired)
23index = 0
24X_original = X_test[0,:].reshape(1, -1)
25y_original = clf.predict(X_original)
26y_original_proba = clf.predict_proba(X_original)
27y_desired = 1
28
29print(f'The original prediction was {y_original} with probabilities {y_original_proba}')
30print(f'We will attempt to generate counterfactuals where the outcome is {y_desired}.')
31
32# generating counterfactuals
33immutable_column_indexes = [2] # let's say we can't change the last column
34categorical_columns = {} # there are no categorical columns
35integer_columns = [] # there are no columns that only accept integer values
36y_acceptable_range = [0.5, 1.0] # we will only accept counterfactuals with the predicted prob. in this range
37
38upper_bounds = np.array(X_train.max(axis=0)*0.8) # this is the maximum allowed number per column
39lower_bounds = np.array(X_train.min(axis=0)*0.8) # this is the minimum allowed number per column.
40# you may change the bounds depending on the needs specific to the individual being trained.
41
42# running the counterfactual generation algorithm
43front, X_generated, algorithms = generate_counterfactuals_classification_proba(clf,
44 X_original, y_desired, immutable_column_indexes,
45 y_acceptable_range, upper_bounds, lower_bounds,
46 categorical_columns, integer_columns, n_gen=20,
47 pop_size=30, max_changed_vars=3, verbose=False,
48 seed=random_state)
Features
The documentation as well as the code are part of an ongoing research. Currently, it does support:
Regression problems
Classification problems (probability or single class as outputs)
On the variables, it does support:
Decimal and integer variables as values (such as counts, quantities, etc.)
Ordinally encoded categorical variables (categories encoded as integers)
Setting the upper and lower bounds per variable
Setting which columns are immutable
Setting which categories are bound to be modified (xMOAI is able to understand only the categories 1, 5, 7 and 15 are allowed categories instead of treating it as a numerical range)
Setting the target desired (for regression problems, you can inform the value you want to have as an output; for classification problems, the desired class)
Setting the “allowed output range” (for regression problems, you can inform what values are acceptable as outputs instead of a single value. As an example, for a housing prices dataset you may want to find a counterfactual with an output of $100000.00. However, anything between $99000.00 and $105000.00 could also be good prices for your problem. For a classification problem, it is the percentage of certainity of the predicted class considering your problem).
It does not support at the present moment:
One-hot encoded categories
Models available in hosted servers (i.e. with a REST API endpoint)
Multiple allowed intervals for a single attribute (e.g. for a single column, instead of a range of -10 to +20, two ranges of -10 to 0 and +10 to +20).
Examples
Check out the xMOAI-examples repository for examples using different frameworks available in Python such as LightGBM, XGBoost, scikit-learn and Tensorflow.
Indices and tables
Disclaimer
Logo made by Freepik (http://www.freepik.com/) from https://www.flaticon.com.