teex 1.0.0

A Toolbox for the Evaluation of Explanations

teex

A Python Toolbox for the Evaluation of machine learning Explanations.

This project aims to provide a simple way of evaluating individual black box explanations. Moreover, it contains a collection of easy-to-access datasets with available ground truth explanations.

Installation

The teex package is on PyPI. To install it, simply run

pip install teex

teex is compatible with Python >= 3.6.

Usage overview

teex is divided into subpackages, one for each explanation type. Each subpackage contains two modules:

• eval: contains evaluation methods for that particular explanation type. For every subpackage, there is one high-level functions to easily compute all the available metrics.
• data: contains data classes with available g.t. explanations of that particular explanation type, both synthetic and real. All of them are objects that need to be instanced and, when sliced, will return the data, the target and the ground truth explanations, respectively.

Feature Importance

In teex, feature importance vectors are a universal representation: we can 'translate' all other explanation types to feature importance vectors.

What are feature importance vectors? They are vectors with one entry per feature. Each entry contains a weight that represents a feature's importance for the observation's outcome. Weights are usually in the range [-1, 1].

Fig. 1 SHAP values, each representing impact on model output of each feature.

Popular feature importance model-agnostic explainers are, for example, SHAP or LIME. Because weights in each method represent slighlty different things, we make the assumption that they all mean roughly the same if they are in the same range (if we want to compare methods). teex performs this mapping automatically if necessary.

from teex.featureImportance.data import SenecaFI
from teex.featureImportance.eval import feature_importance_scores
from sklearn import DecisionTreeClassifier
import shap

# generate artificial data
X, y, exps = SenecaFI(nSamples=500, nFeatures=5)[:]

# instance and train the model
model = DecisionTreeClassifier()
model.fit(X, y)

# predict individual feature importance explanations
explainer = shap.Explainer(model)
predictedSHAPs = explainer(X).values

# evaluate predicted explanations againsy ground truths (implicit range mappings)
feature_importance_scores(exps, predictedSHAPs, metrics=['fscore', 'cs', 'rec'])

Saliency Maps

A saliency map is an image that shows each pixel's unique quality. In our context, each pixel (feature) contains a score (in the ranges [-1, 1] or [0, 1] as before) that represents a likelihood or probability of belonging to a particular class. For example:

Fig. 2 Input image and saliency map for the prediction of the class "dog" overlayed on top of the original image. It tells us where the model "looks" when issuing the prediction. source

teex contains artificial and real-life datasets for saliency map explanations:

Fig. 3 The Kahikatea dataset. Contains aerial images with the task of identifying whether there are Kahikatea trees (a species endemic to New Zealand) in the area or not. Observation on the left, ground truth explanation on the right.

Fig. 4 Artificial image dataset with g.t. saliency map explanations.

A basic usage example of teex with saliency maps simulating perfect predicted explanations:

from teex.saliencyMap.data import Kahikatea
from teex.saliencyMap.eval import saliency_map_scores

X, y, exps = Kahikatea()[:]
saliency_map_scores(exps[y == 1], exps[y == 1], metrics=['fscore', 'auc'])

Decision Rules

WIP!

Word Importance

WIP!

Tutorials and API

The full API documentation can be found on Read The Docs.

Here are some sample notebooks with examples:

• Generating image data with g.t. saliency map explanations

Contributing

Before contributing to teex, please take a moment to read the manual.

Acknowledgements

This work has been made possible by the University of Waikato under the scope of the TAIAO project.