LIME

class ordinal_xai.interpretation.lime.LIME(model, X: DataFrame, y: ndarray | None = None, comparison_method: str = 'one_vs_following', model_type: str = 'logistic', kernel_width: float = 0.75, custom_kernel: Callable | None = None, sampling: str = 'permute', max_samples: int = 10000, random_state: int = 42, **surrogate_kwargs)[source]

Bases: BaseInterpretation

Local Interpretable Model-agnostic Explanations for ordinal regression models.

This class implements LIME for ordinal regression models, providing local explanations by fitting interpretable surrogate models to explain individual predictions. The implementation extends standard LIME to handle ordinal data by comparing predictions with adjacent or following classes.

Parameters:

  • model (object) – The trained ordinal regression model. Must implement predict and transform methods.

  • X (pd.DataFrame) – Dataset used for interpretation. Should contain the same features used during model training.

  • y (np.ndarray, optional) – Target labels. Not required for interpretation but useful for reference.

  • comparison_method (str, default='one_vs_following') – Method for comparing classes: - ‘one_vs_next’: Compare with adjacent classes only - ‘one_vs_following’: Compare with all higher/lower classes

  • model_type (str, default='logistic') – Type of surrogate model to use: - ‘logistic’: Logistic regression model - ‘decision_tree’: Decision tree model

  • kernel_width (float, default=0.75) – Width of the exponential kernel for sample weighting. Controls how quickly the weight of samples decreases with distance.

  • custom_kernel (callable, optional) – Custom kernel function for sample weighting. Should take distances as input and return weights.

  • sampling (str, default='permute') – Sampling strategy for generating perturbed samples: - ‘grid’: Generate samples on a grid (for small feature spaces) - ‘uniform’: Sample uniformly from feature ranges - ‘permute’: Permute feature values from the dataset

  • max_samples (int, default=10000) – Maximum number of samples to generate for surrogate model training.

model

The trained ordinal regression model

Type:

object

X

Training data

Type:

pd.DataFrame

y

Target labels

Type:

np.ndarray

comparison_method

Method for comparing classes

Type:

str

model_type

Type of surrogate model

Type:

str

kernel_width

Width of the exponential kernel

Type:

float

custom_kernel

Custom kernel function

Type:

callable

sampling

Sampling strategy

Type:

str

max_samples

Maximum number of samples

Type:

int

Raises:

ValueError – If comparison_method is invalid, kernel_width is non-positive, or sampling strategy is invalid

__init__(model, X: DataFrame, y: ndarray | None = None, comparison_method: str = 'one_vs_following', model_type: str = 'logistic', kernel_width: float = 0.75, custom_kernel: Callable | None = None, sampling: str = 'permute', max_samples: int = 10000, random_state: int = 42, **surrogate_kwargs) → None[source]

Initialize LIME interpretation.

Parameters:

  • model (object) – The trained ordinal regression model

  • X (pd.DataFrame) – Training data

  • y (np.ndarray, optional) – Target labels

  • comparison_method ("one_vs_following" | "one_vs_next", default='one_vs_following') – Method for comparing classes

  • model_type ("logistic" | "decision_tree", default='logistic') – Type of surrogate model to use

  • kernel_width (float, default=0.75) – Width of the exponential kernel

  • custom_kernel (callable, optional) – Custom kernel function

  • sampling ("grid" | "uniform" | "permute", default='permute') – Sampling strategy

  • max_samples (int, default=10000) – Maximum number of samples

Raises:

ValueError – If comparison_method is invalid, kernel_width is non-positive, or sampling strategy is invalid

_compute_weights(samples: DataFrame, observation: Series, kernel: Callable | None = None) → ndarray[source]

Compute sample weights using exponential kernel with Gower’s distance.

This method calculates weights for perturbed samples based on their distance from the observation being explained. It uses Gower’s distance to handle both numerical and categorical features.

Parameters:

  • samples (pd.DataFrame) – DataFrame containing perturbed samples

  • observation (pd.Series) – Series containing the observation to explain

  • kernel (callable, optional) – Custom kernel function for weight calculation

Returns:

Array of weights for each sample

Return type:

np.ndarray

Notes

  • Uses Gower’s distance to handle mixed data types

  • Applies exponential kernel by default

  • Weights decrease exponentially with distance

_get_comparison_labels(pred_class: int, samples_preds: ndarray) → Tuple[ndarray, ndarray][source]

Get binary labels for comparison based on method.

This method creates binary labels for the surrogate model based on the comparison method chosen. It identifies which samples are in higher or lower classes than the prediction.

Parameters:

  • pred_class (int) – Predicted class of the observation

  • samples_preds (np.ndarray) – Array of predictions for all samples

Returns:

Tuple of (higher_mask, lower_mask) arrays indicating which samples are in higher/lower classes than the prediction

Return type:

Tuple[np.ndarray, np.ndarray]

Notes

  • For ‘one_vs_next’, only compares with adjacent classes

  • For ‘one_vs_following’, compares with all higher/lower classes

_plot_coefficients(higher_coef: ndarray | None, lower_coef: ndarray | None, feature_names: List[str], observation_idx: int, observation: Series, pred_class: int, higher_fidelity_in: float | None = None, higher_fidelity_out: float | None = None, lower_fidelity_in: float | None = None, lower_fidelity_out: float | None = None, is_effect: bool = False) → None[source]

Plot horizontal bars for either surrogate coefficients or predictor effects (coefficient × value) for higher / lower class comparisons.

This method creates horizontal bar plots showing the coefficients of the logistic regression surrogate model for both higher and lower class comparisons.

Parameters:

  • higher_coef (np.ndarray, optional) – Coefficients for higher class comparison

  • lower_coef (np.ndarray, optional) – Coefficients for lower class comparison

  • feature_names (List[str]) – List of feature names

  • observation_idx (int) – Index of the observation being explained

  • observation (pd.Series) – The observation being explained

  • pred_class (int) – Predicted class of the observation

Notes

  • Creates separate plots for higher and lower class comparisons

  • Shows feature values in the title

  • Uses blue for higher class and red for lower class

  • Includes observation details in the title

_generate_grid_samples(X: DataFrame) → DataFrame[source]

Generate samples using grid sampling strategy.

This method creates a grid of samples by: 1. Identifying categorical and numerical columns 2. Using all unique values for categorical features 3. Creating evenly spaced points for numerical features 4. Combining all possible combinations

Parameters:

X (pd.DataFrame) – Original dataset

Returns:

DataFrame containing grid samples

Return type:

pd.DataFrame

Raises:

ValueError – If grid size would exceed max_samples

Notes

  • For numerical features, uses linspace between min and max values

  • For categorical features, uses all unique values

  • Caps number of points per numerical feature at 100

  • Samples randomly if grid size exceeds max_samples

_generate_uniform_samples(X: DataFrame) → DataFrame[source]

Generate samples using uniform sampling strategy.

This method creates samples by drawing uniformly from the range of each feature. For numerical features, samples from the min-max range. For categorical features, samples from unique values.

Parameters:

X (pd.DataFrame) – Original dataset

Returns:

DataFrame containing uniformly sampled points

Return type:

pd.DataFrame

Notes

  • Numerical features: uniform sampling between min and max

  • Categorical features: random choice from unique values

  • Number of samples controlled by max_samples parameter

_generate_permute_samples(X: DataFrame) → DataFrame[source]

Generate samples using permutation sampling strategy.

This method creates samples by randomly permuting the values of each feature from the original dataset. This preserves the marginal distribution of each feature.

Parameters:

X (pd.DataFrame) – Original dataset

Returns:

DataFrame containing permuted samples

Return type:

pd.DataFrame

Notes

  • Preserves marginal distributions of features

  • Breaks correlations between features

  • Number of samples controlled by max_samples parameter

_plot_decision_tree(higher_model: DecisionTreeClassifier | None, lower_model: DecisionTreeClassifier | None, feature_names: List[str], observation_idx: int, observation: Series, pred_class: int, higher_fidelity_in: float | None = None, higher_fidelity_out: float | None = None, lower_fidelity_in: float | None = None, lower_fidelity_out: float | None = None, is_effect: bool = False) → None[source]

Plot decision tree surrogate models.

This method creates visualizations of the decision tree surrogate models for both higher and lower class comparisons. The trees show the decision rules learned by the surrogate model.

Parameters:

  • higher_model (DecisionTreeClassifier, optional) – Fitted decision tree model for higher class comparison

  • lower_model (DecisionTreeClassifier, optional) – Fitted decision tree model for lower class comparison

  • feature_names (List[str]) – List of feature names

  • observation_idx (int) – Index of the observation being explained

  • observation (pd.Series) – The observation being explained

  • pred_class (int) – Predicted class of the observation

  • fidelity_in (float, optional) – Fidelity of the model on the training data

  • fidelity_out (float, optional) – Fidelity of the model on the test data

Notes

  • Creates separate plots for higher and lower class comparisons

  • Shows feature values in the title

  • Uses simplified node text for better readability

  • Includes observation details in the title

explain(observation_idx: int | None = None, feature_subset: List[str | int] | None = None, plot: bool = False, show_coefficients: bool = False, **kwargs) → Dict[str, List[str] | ndarray | DecisionTreeClassifier][source]

Generate LIME explanations for a specific observation.

Depending on the show_coefficients flag the horizontal bar plot will display either (a) raw surrogate coefficients or (b) predictor effects defined as coefficient × local feature value for numerical features. Categorical one-hot features always use the raw coefficient value.

This method creates local explanations by: 1. Generating perturbed samples around the observation 2. Computing sample weights based on distance 3. Fitting surrogate models to explain the prediction 4. Visualizing the results if requested

Parameters:

  • observation_idx (int, optional) – Index of the observation to explain

  • feature_subset (List[Union[int, str]], optional) – List of feature indices or names to include

  • plot (bool, default=False) – If True, visualise the explanation.

  • show_coefficients (bool, default=False) – If False (default) plot predictor effects; if True plot raw coefficients. Whether to create visualizations

  • **kwargs (dict) – Additional keyword arguments

Returns:

Dictionary containing: - features: List of feature names - higher_model: Decision tree model for higher class comparison (if model_type=”decision_tree”) - lower_model: Decision tree model for lower class comparison (if model_type=”decision_tree”) - higher_coef: Coefficients for higher class comparison (if model_type=”logistic”) - lower_coef: Coefficients for lower class comparison (if model_type=”logistic”)

Return type:

Dict[str, Union[List[str], np.ndarray, DecisionTreeClassifier]]

Raises:

ValueError – If observation_idx is not specified or model_type is invalid

Notes

  • Requires observation_idx to be specified

  • Supports both logistic regression and decision tree surrogate models

  • Can focus on specific features using feature_subset

  • Provides visualizations of coefficients or decision trees

_abc_impl = <_abc._abc_data object>