xailib.explainers package

Submodules

xailib.explainers.abele_explainer module

xailib.explainers.gradcam_explainer module

xailib.explainers.intgrad_explainer module

xailib.explainers.lasts_explainer module

xailib.explainers.lime_explainer module

LIME (Local Interpretable Model-agnostic Explanations) implementation for XAI-Lib.

This module provides LIME explainers for tabular, image, and text data. LIME is a popular explanation method that approximates the behavior of a black-box model locally using an interpretable surrogate model.

LIME works by:

Generating a neighborhood of perturbed samples around the instance to explain
Getting predictions for these samples from the black-box model
Training an interpretable model (e.g., linear model) on the neighborhood
Using the interpretable model to explain the prediction

Classes:

LimeXAITabularExplanation: Explanation class for LIME tabular explanations. LimeXAITabularExplainer: LIME explainer for tabular data. LimeXAIImageExplainer: LIME explainer for image data. LimeXAITextExplainer: LIME explainer for text data.

References

Ribeiro, M. T., Singh, S., & Guestrin, C. (2016). “Why Should I Trust You?”: Explaining the Predictions of Any Classifier. KDD 2016.

Example

Using LIME for tabular data:

from xailib.explainers.lime_explainer import LimeXAITabularExplainer
from xailib.models.sklearn_classifier_wrapper import sklearn_classifier_wrapper

bb = sklearn_classifier_wrapper(trained_model)
explainer = LimeXAITabularExplainer(bb)
explainer.fit(df, 'target', config={'discretize_continuous': True})
explanation = explainer.explain(instance)
explanation.plot_features_importance()

See also

lime: The underlying LIME library. xailib.explainers.shap_explainer_tab.ShapXAITabularExplainer: Alternative explanation method.

class xailib.explainers.lime_explainer.LimeXAIImageExplainer(bb: AbstractBBox)[source]

Bases: ImageExplainer

LIME explainer for image data.

This explainer uses LIME to explain image classification predictions by segmenting the image and determining which segments are most important for the prediction.

Parameters:: bb (AbstractBBox) – The black-box model wrapper to explain.

bb: The black-box model wrapper.

lime_explainer: The underlying LimeImageExplainer (after fitting).

explain(image, classifier_fn=None, segmentation_fn=None, top_labels=5, num_samples=1000)[source]

Generate a LIME explanation for an image.

Parameters:

image – Query image to explain as a numpy array.
classifier_fn (callable, optional) – Function that takes images and returns predictions. If None, uses black_box.predict.
segmentation_fn (callable, optional) – Function to segment the image. If None, uses quickshift segmentation.
top_labels (int) – Number of top labels to explain. Defaults to 5.
num_samples (int) – Number of perturbed images to generate. Defaults to 1000.

Returns:

LIME ImageExplanation object with superpixel importance values.

fit(verbose=False)[source]

Initialize the LIME image explainer.

Parameters:: verbose (bool) – Whether to print verbose output. Defaults to False.
Returns:: None. The explainer is initialized in-place.

lime_explainer = None

plot_lime_values(image, explanation, figsize=(15, 5))[source]

Plot a visualization of the LIME image explanation.

Creates a three-panel figure showing:

The original query image
A heatmap of superpixel importance
An overlay of the heatmap on the original image

Parameters:

image – The original image used in the explain function.
explanation – LIME explanation object returned by explain().
figsize (tuple) – Figure size as (width, height). Defaults to (15, 5).

Returns:

None. Displays the matplotlib figure.

class xailib.explainers.lime_explainer.LimeXAITabularExplainer(bb: AbstractBBox)[source]

Bases: TabularExplainer

LIME explainer for tabular data.

This explainer uses LIME (Local Interpretable Model-agnostic Explanations) to explain predictions on tabular data by training a local linear model.

Parameters:: bb (AbstractBBox) – The black-box model wrapper to explain.

bb: The black-box model wrapper.

lime_explainer: The underlying LimeTabularExplainer (after fitting).

Example

>>> explainer = LimeXAITabularExplainer(model_wrapper)
>>> explainer.fit(df, 'target', config={
...     'discretize_continuous': True,
...     'feature_selection': 'auto'
... })
>>> explanation = explainer.explain(instance, num_samples=1000)

explain(x, classifier_fn=None, num_samples=1000, top_labels=5)[source]

Generate a LIME explanation for a tabular instance.

Parameters:

x – Instance to explain as a numpy array.
classifier_fn (callable, optional) – Custom prediction function. If None, uses the black-box model’s predict_proba.
num_samples (int) – Number of samples in the neighborhood. Defaults to 1000.
top_labels (int) – Number of top labels to explain. Defaults to 5.

Returns:

Explanation object with feature weights.

Return type:

LimeXAITabularExplanation

fit(_df: DataFrame, class_name, config)[source]

Fit the LIME explainer to the training data.

Parameters:

_df (pd.DataFrame) – Training DataFrame with features and target.
class_name (str) – Name of the target column.
config (dict) – Configuration dictionary with optional parameters: - ‘feature_selection’: Feature selection method (‘auto’, ‘forward’, etc.) - ‘discretize_continuous’ (bool): Whether to discretize continuous features - ‘discretizer’: Discretizer type (‘quartile’ or ‘decile’) - ‘sample_around_instance’ (bool): Sampling strategy - ‘kernel_width’: Width of the kernel for weighting - ‘kernel’: Custom kernel function

Returns:

None. The explainer is fitted in-place.

lime_explainer = None

plot_lime_values(exp, range_start, range_end)[source]

Plot LIME feature importance values as a bar chart.

Parameters:

exp – LIME explanation (list of (feature, weight) tuples).
range_start (int) – Start index for features to display.
range_end (int) – End index for features to display.

Returns:

None. Displays the matplotlib figure.

class xailib.explainers.lime_explainer.LimeXAITabularExplanation(lime_exp)[source]

Bases: TabularExplanation

Explanation class for LIME tabular explanations.

This class wraps the LIME explanation result and provides methods to access feature importance and visualize the explanation.

Parameters:: lime_exp – The raw LIME explanation object.

exp: The underlying LIME explanation object.

Example

>>> explanation = explainer.explain(instance)
>>> importance = explanation.getFeaturesImportance()
>>> explanation.plot_features_importance()

getCounterExemplars()[source]

Get counter-exemplar instances.

Note

LIME does not provide counter-exemplars.

Returns:: Not available for LIME.
Return type:: None

getCounterfactualRules()[source]

Get counterfactual rules.

Note

LIME does not provide counterfactual rules.

Returns:: Not available for LIME.
Return type:: None

getExemplars()[source]

Get exemplar instances.

Note

LIME does not provide exemplars.

Returns:: Not available for LIME.
Return type:: None

getFeaturesImportance()[source]

Get feature importance as a list of (feature, weight) tuples.

Returns:

List of tuples (feature_description, weight) showing: how each feature contributed to the prediction.

Return type:

list

getRules()[source]

Get decision rules.

Note

LIME provides feature weights, not explicit rules. Use getFeaturesImportance() instead.

Returns:: Not available for LIME.
Return type:: None

plot_features_importance(fontDimension=10)[source]

Plot an interactive visualization of feature importance.

Creates an Altair chart showing feature weights with an interactive slider to filter by importance threshold.

Parameters:: fontDimension (int, optional) – Base font size for the chart. Defaults to 10.
Returns:: None. Displays the chart using IPython display.

class xailib.explainers.lime_explainer.LimeXAITextExplainer(bb: AbstractBBox)[source]

Bases: TextExplainer

LIME explainer for text data.

This explainer uses LIME to explain text classification predictions by perturbing words in the text and measuring their impact on predictions.

Parameters:: bb (AbstractBBox) – The black-box model wrapper to explain.

bb: The black-box model wrapper.

lime_explainer: The underlying LimeTextExplainer (after fitting).

explain(sentence, classifier_fn=None, num_samples=1000, plot=False)[source]

Generate a LIME explanation for a text sentence.

Parameters:

sentence (str) – Query text to explain.
classifier_fn (callable, optional) – Function that takes text and returns predictions. If None, uses black_box.predict.
num_samples (int) – Number of perturbed texts to generate. Defaults to 1000.
plot (bool) – Whether to display a matplotlib plot of the explanation. Defaults to False.

Returns:

LIME TextExplanation object with word importance values.

fit(class_names=None, verbose=False)[source]

Initialize the LIME text explainer.

Parameters:

class_names (list, optional) – List of class names ordered according to the classifier output. If None, class names will be ‘0’, ‘1’, etc.
verbose (bool) – Whether to print verbose output. Defaults to False.

Returns:

None. The explainer is initialized in-place.

lime_explainer = None

xailib.explainers.lore_explainer module

class xailib.explainers.lore_explainer.LoreTabularExplainer(bb: AbstractBBox)[source]

Bases: TabularExplainer

bb = None

explain(x)[source]

Generate an explanation for a tabular data instance.

Parameters:

b – Black-box model or prediction function (depends on implementation).
x – Instance to explain as a numpy array or pandas Series.

Returns:

An explanation object containing feature importance,: rules, or other explanation information.

Return type:

TabularExplanation

fit(_df: DataFrame, class_name, config)[source]

Fit the explainer to the tabular training data.

Parameters:

X (pd.DataFrame) – Training data as a pandas DataFrame.
y – Target column name (str) or target values.
config (dict) –
Configuration dictionary with method-specific parameters. Common keys include:
- ’feature_selection’: Feature selection method
- ’discretize_continuous’: Whether to discretize continuous features
- ’sample_around_instance’: Sampling strategy
- Additional method-specific parameters

Returns:

None. The explainer is fitted in-place.

lore_explainer = None

random_state = 0

class xailib.explainers.lore_explainer.LoreTabularExplanation(lore_exp)[source]

Bases: TabularExplanation

getCounterExemplars()[source]

Get counter-exemplar instances with different predictions.

Returns:: Counter-exemplar instances, or None if not supported by this explanation method.

getCounterfactualRules()[source]

Get counterfactual rules for alternative outcomes.

Returns:: Counterfactual rules describing how to change the prediction, or None if not supported by this explanation method.

getExemplars()[source]

Get exemplar instances similar to the explained instance.

Returns:: Exemplar instances with the same prediction, or None if not supported by this explanation method.

getFeaturesImportance()[source]

Get feature importance values for the explained instance.

Returns:: Feature importance as a list of tuples, numpy array, or pandas DataFrame. The exact format depends on the explanation method. Returns None if feature importance is not available.

getRules()[source]

Get decision rules explaining the prediction.

Returns:: Decision rules as a dictionary or list, or None if not supported by this explanation method.

plotCounterfactualRules()[source]

plotRules()[source]

xailib.explainers.nam_explainer_tab module

xailib.explainers.rise_explainer module

class xailib.explainers.rise_explainer.RiseXAIImageExplainer(bb: AbstractBBox)[source]

Bases: ImageExplainer

explain(inp, batch_size=100)[source]

Generate an explanation for an image instance.

Parameters:

b – Black-box model or prediction function.
x – Image to explain as a numpy array.

Returns:

Explanation output, typically a heatmap or saliency map as a numpy array with the same spatial dimensions as the input.

fit(N, s, p1)[source]

Fit the explainer to the image training data.

For most image explainers, this method sets up the necessary components for generating explanations (e.g., target layers for GradCAM, mask generation for RISE).

Parameters:

X – Training images or configuration parameters. The exact format depends on the specific method.
y – Training labels or additional configuration.

Returns:

None. The explainer is fitted in-place.

xailib.explainers.shap_explainer_tab module

exception xailib.explainers.shap_explainer_tab.NoExplainerFound(name)[source]: Bases: Exception

class xailib.explainers.shap_explainer_tab.ShapXAITabularExplainer(bb: AbstractBBox, feature_names: list)[source]

Bases: TabularExplainer

expected_value(val)[source]

explain(x)[source]

Generate an explanation for a tabular data instance.

Parameters:

b – Black-box model or prediction function (depends on implementation).
x – Instance to explain as a numpy array or pandas Series.

Returns:

An explanation object containing feature importance,: rules, or other explanation information.

Return type:

TabularExplanation

fit(config)[source]

Fit the explainer to the tabular training data.

Parameters:

X (pd.DataFrame) – Training data as a pandas DataFrame.
y – Target column name (str) or target values.
config (dict) –
Configuration dictionary with method-specific parameters. Common keys include:
- ’feature_selection’: Feature selection method
- ’discretize_continuous’: Whether to discretize continuous features
- ’sample_around_instance’: Sampling strategy
- Additional method-specific parameters

Returns:

None. The explainer is fitted in-place.

plot_shap_values(feature_names, exp, range_start, range_end)[source]

shap_explainer = None

class xailib.explainers.shap_explainer_tab.ShapXAITabularExplanation(shap_exp, feature_names: list)[source]

Bases: TabularExplanation

getCounterExemplars()[source]

Get counter-exemplar instances with different predictions.

Returns:: Counter-exemplar instances, or None if not supported by this explanation method.

getCounterfactualRules()[source]

Get counterfactual rules for alternative outcomes.

Returns:: Counterfactual rules describing how to change the prediction, or None if not supported by this explanation method.

getExemplars()[source]

Get exemplar instances similar to the explained instance.

Returns:: Exemplar instances with the same prediction, or None if not supported by this explanation method.

getFeaturesImportance()[source]

Get feature importance values for the explained instance.

Returns:: Feature importance as a list of tuples, numpy array, or pandas DataFrame. The exact format depends on the explanation method. Returns None if feature importance is not available.

getRules()[source]

Get decision rules explaining the prediction.

Returns:: Decision rules as a dictionary or list, or None if not supported by this explanation method.

plot_features_importance(fontDimension=10)[source]

Module contents

Explainer implementations for XAI-Lib.

This subpackage contains implementations of various explanation methods for different data types (tabular, image, text, time series).

Tabular Data Explainers

LimeXAITabularExplainer: LIME (Local Interpretable Model-agnostic Explanations) for tabular data.
ShapXAITabularExplainer: SHAP (SHapley Additive exPlanations) for tabular data.
LoreTabularExplainer: LORE (LOcal Rule-based Explanations) for tabular data.

Image Data Explainers

LimeXAIImageExplainer: LIME for image data.
GradCAMImageExplainer: GradCAM (Gradient-weighted Class Activation Mapping) for images.
GradCAMPlusPlusImageExplainer: GradCAM++ for improved image explanations.
RiseXAIImageExplainer: RISE (Randomized Input Sampling for Explanation) for images.
IntgradImageExplainer: Integrated Gradients for image explanations.
abele_explainer: ABELE (Adversarial Black-box Explainer) for images.

Text Data Explainers

LimeXAITextExplainer: LIME for text data.

Time Series Explainers

lasts_explainer: LASTS for time series explanations.

Transparent-by-Design Models

nam_explainer_tab: Neural Additive Models for interpretable predictions.

Example

>>> from xailib.explainers.lime_explainer import LimeXAITabularExplainer
>>> from xailib.models.sklearn_classifier_wrapper import sklearn_classifier_wrapper
>>>
>>> bb = sklearn_classifier_wrapper(trained_model)
>>> explainer = LimeXAITabularExplainer(bb)
>>> explainer.fit(df, 'target', config={})
>>> explanation = explainer.explain(instance)