omnixai.explainers package

This package contains all the supported explainers. In practice, we recommend using use omnixai.explainers.tabular.TabularExplainer, omnixai.explainers.vision.VisionExplainer, omnixai.explainers.nlp.NLPExplainer, and omnixai.explainers.timeseries.TimeseriesExplainer for tabular, vision, NLP and time series tasks, respectively, and using omnixai.explainers.data.DataAnalyzer and omnixai.explainers.prediction.PredictionAnalyzer for feature analysis and prediction result analysis. To generate explanations, one only needs to specify the ML model, the pre-processing function (converting raw data into the model inputs), the post-processing function (e.g., converting the model outputs into class probabilities, optional), and the explainer names (e.g., lime, shap, gradcam):

explainers = TabularExplainer(
    explainers=["lime", "shap", "mace", "pdp"],        # The explainers to apply
    mode="classification",                             # The task type
    data=data,                                         # The data for initializing the explainers
    model=model,                                       # The ML model to explain
    preprocess=preprocess_function,                    # The preprocessing function
    postprocess=None,                                  # The postprocessing function
    params={
        "lime": {"kernel_width": 3},
        "shap": {"nsamples": 100},
        "mace": {"ignored_features": ["Sex", "Race", "Relationship", "Capital Loss"]}
    }                                                  # Additional parameters
)
local_explanations = explainers.explain(x)             # Generate local explanations given input `x`
global_explanations = explainers.explain_global()      # Generate global explanations

For vision tasks, e.g., image classification, the explanations can be generated in a similar way:

explainer = VisionExplainer(
    explainers=["gradcam", "lime", "ig"],              # The explainers to apply
    mode="classification",                             # The task type
    model=model,                                       # The ML model to explain
    preprocess=preprocess_function,                    # The preprocessing function
    postprocess=postprocess_function,                  # The postprocessing function
    params={"gradcam": {"target_layer": model.layer4[-1]}}  # Additional parameters
)
local_explanations = explainer.explain(img)            # Generate local explanations given input `img`

For a single explainer, its constructor has one of the following two formats:

__init__(self, predict_function, **kwargs): This is for model-agnostic explainers. predict_function is the prediction function of the black-box ML model to explain. The inputs of predict_function are the raw input features, and the outputs of predict_function are the model outputs.
__init__(self, model, preprocess_function, postprocess_function, **kwargs): This is for model-specific explainers. model is the ML model to explain. The model-specific explainers require some information about model, e.g., whether model is differentiable (PyTorch or Tensorflow). preprocess_function is the pre-processing function for model, converting the raw features into the inputs of model, e.g., resizing images to (224, 224) and normalizing pixel values. postprocess_function is the post-processing function for model, which is used to convert the output logits into class probabilities. postprocess_function is mainly used for visualization, e.g., showing the predicted probabilities in the dashboard. We recommend:
- model: It outputs logits for classification or estimated values for regression given the pre-processed inputs.
- preprocess_function: It converts the raw input features into the model inputs.
- postprocess_function: It is ignored in regression tasks or converts logits into class probabilities in classification tasks.

For example, a model-agnostic explainer can be applied as follows:

# Load dataset
data = np.genfromtxt('adult.data', delimiter=', ', dtype=str)
feature_names = [
    "Age", "Workclass", "fnlwgt", "Education",
    "Education-Num", "Marital Status", "Occupation",
    "Relationship", "Race", "Sex", "Capital Gain",
    "Capital Loss", "Hours per week", "Country", "label"
]
tabular_data = Tabular(
    data,
    feature_columns=feature_names,
    categorical_columns=[feature_names[i] for i in [1, 3, 5, 6, 7, 8, 9, 13]],
    target_column='label'
)
# Preprocessing
transformer = TabularTransform().fit(tabular_data)
x = transformer.transform(tabular_data)
# Train an XGBoost model
gbtree = xgboost.XGBClassifier(n_estimators=300, max_depth=5)
gbtree.fit(x[:, :-1], x[:, -1])       # The last column in `x` is the label column

# Construct the prediction function
predict_function=lambda z: gbtree.predict_proba(transformer.transform(z))
# Initialize the SHAP explainer
explainer = ShapTabular(
    training_data=tabular_data,
    predict_function=predict_function
)

For a model-specific explainer, e.g., Grad-CAM, one can apply the followings:

# A ResNet model to explain
model = models.resnet50(pretrained=True)
# Construct the prediction function
transform = transforms.Compose([
    transforms.Resize(256),
    transforms.CenterCrop(224),
    transforms.ToTensor(),
    transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225])
])
preprocess = lambda images: torch.stack([transform(im.to_pil()) for im in images])
# Initialize the Grad-CAM explainer
explainer = GradCAM(
    model=model,
    preprocess_function=preprocess,
    target_layer=model.layer4[-1]
)

More detailed examples can be found in the tutorials.

omnixai.explainers.base module

The base classes for the supported explainers.

class omnixai.explainers.base.ExplainerABCMeta(classname, bases, cls_dict)

Bases: AutodocABCMeta

The meta class for an explainer. It will automatically register an explainer class, i.e., storing it in _EXPLAINERS.

class omnixai.explainers.base.ExplainerBase

Bases: object

The abstract base class for an explainer. If an explainer inherits from this class, it will be registered automatically.

abstract explain(**kwargs)

property explanation_type

Returns: A string indicates the explanation type, e.g., local, global or both

save(directory, filename=None, **kwargs)

Saves the initialized explainer.

Parameters

directory (str) – The folder for the dumped explainer.
filename (Optional[str]) – The filename (the explainer class name if it is None).

classmethod load(directory, filename=None, **kwargs)

Loads the dumped explainer.

Parameters

directory (str) – The folder for the dumped explainer.
filename (Optional[str]) – The filename (the explainer class name if it is None).

class omnixai.explainers.base.AutoExplainerBase(explainers, mode, data, model, preprocess=None, postprocess=None, params=None)

Bases: object

The base class for task-specific explainers. The class derived from AutoExplainerBase acts as a explainer factory and provides a unified interface to create explainers, e.g., allowing users to choose multiple explainers and generate different explanations at the same time.

Parameters

explainers (Collection[str]) – The names or alias of the explainers to use.
mode (str) – The task type, e.g. classification or regression.
data (Data) – The training data used to initialize explainers. For image or text explainers, it can be empty, e.g., data = Image() or data = Text().
model (Any) – The machine learning model to explain, which can be a scikit-learn model, a tensorflow model, a torch model, or a black-box prediction function.
preprocess (Optional[Callable]) – The preprocessing function that converts the raw input features into the inputs of model.
postprocess (Optional[Callable]) – The postprocessing function that transforms the outputs of model to a user-specific form, e.g., the predicted probability for each class.
params (Optional[Dict]) – A dict containing the additional parameters for initializing each explainer, e.g., params[“lime”] = {“param_1”: param_1, …}.

predict(X, **kwargs)

Gets the predictions given input instances.

Returns: The predictions results.
Return type: PredictedResults

explain(X, params=None, run_predict=True)

Generates local explanations for the specific instances.

Parameters

X – The instances to explain.
params – A dict containing the additional parameters for generating explanations, e.g., params[“lime”] = {“param_1”: param_1, …}.
run_predict – Whether to generate prediction results besides explanations.

Returns

A dict of explanation results generated by the explainers that support local explanation, e.g. {“lime”: lime_explanations, “shap”: shap_explanations, …}.

Return type

OrderedDict

explain_global(params=None)

Generates global explanations.

Parameters: params – A dict containing the additional parameters for generating explanations, e.g., params[“pdp”] = {“param_1”: param_1, …}.
Returns: A dict of explanation results generated by the explainers that support global explanation, e.g. {“pdp”: pdp_explanations, …}.
Return type: OrderedDict

property explainer_names

Gets the names of the specified explainers.

Returns: Explainer names.
Return type: Collection

static list_explainers(): List the supported explainers.

save(directory, mode='model_and_data', **kwargs)

Saves the initialized explainers.

Parameters

directory (str) – The folder for the dumped explainer.
mode (str) – How to save the explainers, i.e., “model_and_data” and “individual”. “model_and_data” for saving the model, preprocessing function, postprocessing function and dataset for initialization, or “individual” for saving each initialized explainer in the AutoExplainer. When there is no explainer that needs to train a post-hoc explanation model (e.g., L2X) and the dataset for initialization is not too large, “model_and_data” is a better option. Otherwise, “individual” is a proper option.

classmethod load(directory, **kwargs)

Loads the dumped explainers.

Parameters: directory (str) – The folder for the dumped explainer.

static parse_explanations_from_json(s)

omnixai.explainers package

omnixai.explainers.base module

Explainers for different tasks