Post-hoc Explainability

Model-agnostic explainability tests exposed by TestSuite.

TestSuite.explain_pfi(dataset: str = 'test', sample_size: int = 5000, n_repeats: int = 10, random_state: int = 0)

Calculate Permutation Feature Importance (PFI) for model features.

PFI measures feature importance by calculating the increase in model prediction error after permuting each feature’s values. A feature is considered important if permuting its values increases model error, indicating the model relied on that feature for prediction.

Parameters:

dataset{“main”, “train”, “test”}, default=”test”

Dataset to use for calculating the explanation results.

sample_sizeint, default=5000

Maximum number of random samples to use for calculation. If the dataset is larger, a random subset of this size will be used to improve computation speed. Set to None to use the entire dataset.

n_repeatsint, default=10

Number of times to repeat the permutation process. Higher values give more reliable importance estimates but increase computation time.

random_stateint, default=0

Random seed for reproducibility of permutations and sampling.

Returns:

ValidationResult

A result object containing:

• key: “explain_pfi”

• data: Name of the dataset used

• model: Name of the model used

• inputs: Input parameters used for the analysis

• value: Dictionary containing:

  • “Name”: List of feature names

  • “Importance”: List of corresponding feature importance values

• table: DataFrame of feature importance results

• options: Dictionary of visualizations configuration for a horizontal bar plot where x-axis is permutation feature importance, and y-axis is the feature name. Run results.plot() to show this plot.

Examples

TestSuite.explain_hstatistic(features: Tuple | List = None, dataset: str = 'test', sample_size: int = 5000, percentiles: Tuple = (0, 1), grid_resolution: int = 10, response_method: str = 'auto', random_state: int = 0)

Calculate H-statistics for all feature pairs to measure feature interactions.

The H-statistic measures the strength of interaction effects between pairs of features by comparing their joint effect to the sum of their individual effects. It quantifies how much of the combined effect of two features comes from their interaction.

1. An H-statistic value of 0 indicates no interaction, meaning the features act independently. Values closer to 1 suggest stronger interaction effects between the features.

2. The statistic can be difficult to compare across feature pairs because the denominator varies depending on the pair, and weak main effects can lead to misleadingly high values.

3. Values greater than 1 are possible but harder to interpret, occurring when the variance of the interaction effect exceeds that of the partial dependence plot.

Parameters:

featurestuple, default=None

List of feature names for calculating the H-statistics. If None, all features will be used.

dataset{“main”, “train”, “test”}, default=”test”

Dataset to use for calculating the explanation results.

sample_sizeint, default=5000

Number of random samples to use for speeding up calculation. If None, all data will be used.

percentilesTuple[float, float], default=(0, 1)

Lower and upper percentiles used to create the extreme values for the grid. Must be in [0, 1].

grid_resolutionint, default=10

Number of equally spaced points on the grid for each target feature.

response_method{“auto”, “decision_function”, “predict_proba”}, default=”auto”

Prediction method to use for binary classification tasks:

• “auto”: Uses ‘predict_proba’ if available, otherwise ‘decision_function’

• “predict_proba”: Probability of the positive class

• “decision_function”: Model’s decision function output

random_stateint, default=0

Random seed for controlling randomness in subsampling.

Returns:

ValidationResult

Object containing:

• key: “explain_hstatistic”

• data: Name of the dataset used

• model: Name of the model used

• inputs: Input parameters used for the analysis

• value: Dictionary containing:

  • “<feature_name>”: Dictionary of H-statistics between this feature to the rest features.

• table: DataFrame of H-statistics for all feature pairs

• options: Dictionary of visualizations configuration for a horizontal bar plot where x-axis is H-statistics, and y-axis is the feature name. Run results.plot() to show this plot.

Examples

TestSuite.explain_pdp(features: str | Tuple[str] = None, dataset: str = 'test', sample_size: int = 5000, percentiles: Tuple = (0, 1), grid_resolution: int = 20, response_method: str = 'auto', random_state: int = 0)

Calculate and visualize Partial Dependence Plot (PDP) for specified model features.

Partial Dependence Plots (PDP) show the marginal effect of one or two features on the predicted outcome of a machine learning model. They illustrate how the model’s predictions change as a feature varies over its range, while averaging out the effects of all other features. This makes PDPs a valuable tool for understanding feature importance and their relationships with the target variable in a model-agnostic way.

Parameters:

featuresstr or tuple of str

Name of single feature or tuple of two feature names to analyze their effects on model output.

• If features=(“X1”, ) or “X1”, visualize the main effect for X1.

• If features=(“X1”, “X2”), visualize the interaction for X1 and X2.

• If features=((“X1”, ), (“X2”, )), visualize the main effect for X1 and X2 separately.

Note: Batch mode for 2D effect plot is not supported. If None, all 1D features will be used.

dataset{“main”, “train”, “test”}, default=”test”

The dataset used for calculating the PDP results.

sample_sizeint, default=5000

Number of random samples to use for speeding up calculation. If None, all data points will be used.

percentilestuple, default=(0, 1)

The lower and upper percentile used to create the extreme values for the grid. Must be in [0, 1].

grid_resolutionint, default=20

The number of equally spaced points on the grid for each target feature.

response_method{“auto”, “decision_function”, “predict_proba”}, default=”auto”

Prediction method to use for binary classification tasks:

• “auto”: Uses ‘predict_proba’ if available, otherwise ‘decision_function’

• “predict_proba”: Probability of the positive class

• “decision_function”: Model’s decision function output

random_stateint, default=0

Random seed for controlling reproducibility in subsampling.

Returns:

ValidationResult

PDP result containing:

• key: “explain_pdp”

• data: Name of the dataset used

• model: Name of the model used

• inputs: Input parameters used for the analysis

• value: Dictionary containing

  • “Value”: X grid values, can be a single 1D-array (1D) or list or 2 1D-arrays (2D);

  • “Effect”: PD values corresponding to grid values, can be a single 1D-array (1D) or 2D-array (2D)

• table: DataFrame of PDP results

• options: Dictionary of visualizations configuration for a line (1D numerical) / bar (1D categorical) / heatmap (2D) effect plot. Run results.plot() to show all plots; To display one preferred plot by results.plot(name=xxx), and the following names are available:

  • None: Effect plots of all effects specified in features.

  • “<effect_name>”: Effect plot of the selected main effect or pairwise interaction.

Notes

For single features, generates a line or bar plot depending on feature type. For two features, generates a heatmap showing the interaction effects.

Examples

TestSuite.explain_ale(features: str | Tuple[str] = None, dataset: str = 'test', sample_size: int = 5000, grid_resolution: int = 20, response_method: str = 'auto', random_state: int = 0)

Calculate Accumulated Local Effects (ALE) plots for one or two features.

ALE plots show how individual features influence model predictions while accounting for feature interactions by measuring effects locally rather than assuming independence across features as in partial dependence.

Parameters:

featuresstr or tuple of str

Feature name(s) to analyze. Use a single feature name for 1D ALE plot or a tuple of two feature names for 2D ALE plot. For 2D ALE, categorical features are not supported.

dataset{“main”, “train”, “test”}, default=”test”

Dataset to use for calculating the explanation results.

sample_sizeint, default=5000

Number of random samples to use for calculation. If None, uses entire dataset. Smaller samples speed up calculation but may reduce accuracy.

grid_resolutionint, default=20

Number of intervals to divide feature range for ALE calculation. Higher values give finer granularity but increase computation time.

response_method{“auto”, “decision_function”, “predict_proba”}, default=”auto”

Prediction method to use for binary classification tasks:

• “auto”: Uses ‘predict_proba’ if available, otherwise ‘decision_function’

• “predict_proba”: Probability of the positive class

• “decision_function”: Model’s decision function output

random_stateint, default=0

Random seed for reproducible sampling when sample_size is specified.

Returns:

ValidationResult

Object containing:

• key: “explain_ale”

• data: Name of the dataset used

• model: Name of the model used

• inputs: Input parameters used for the analysis

• value: Dictionary containing

  • “Value”: X grid values, can be a single 1D-array (1D) or list or 2 1D-arrays (2D);

  • “Effect”: ALE values corresponding to grid values, can be a single 1D-array (1D) or 2D-array (2D)

• table: DataFrame of ALE results

• options: Dictionary of visualizations configuration for a line (1D numerical) / bar (1D categorical) / heatmap (2D) effect plot. Run results.plot() to show all plots; To display one preferred plot by results.plot(name=xxx), and the following names are available:

  • None: Effect plots of all effects specified in features.

  • “<effect_name>”: Effect plot of the selected main effect or pairwise interaction.

Raises:

ValueError

If attempting 2D ALE plot with categorical features.

Notes

For single features, generates a line or bar plot depending on feature type. For two features, generates a heatmap showing the interaction effects.

Examples

TestSuite.explain_lime(dataset: str = 'test', sample_index: int = 0, centered: bool = True, random_state: int = 0)

Generate a LIME (Local Interpretable Model-agnostic Explanations) explanation for a specific sample.

This method provides local feature importance and contribution analysis for a single prediction using the LIME algorithm. It supports both regression and classification tasks.

Parameters:

dataset{“main”, “train”, “test”}, default=”test”

The data set used for calculating the explanation results.

sample_indexint, default=0

The index of the sample in the selected dataset to be explained.

centeredbool, default=True

Whether to center the feature values by subtracting the mean of each feature.

random_stateint, default=0

Random seed for LIME’s perturbation sampling process. Use the same value for reproducible results.

Returns:

ValidationResult

A result object containing:

• key: “explain_lime”

• data: Name of the dataset used

• model: Name of the model used

• inputs: Input parameters used for the analysis

• value: Dictionary containing

  • “Name”: List of feature names;

  • “Value”: List of feature values;

  • “Effect”: List of feature contributions measured by LIME;

  • “Coefficient”: List of feature coefficients measured by LIME.

• value: Dictionary with feature names, values, contributions, and coefficients

• table: DataFrame representation of the explanation

• options: Dictionary of visualizations configuration for a horizontal bar plot where x-axis is LIME value, and y-axis is the feature name. Run results.plot() to show this plot.

Notes

The explanation includes both feature coefficients (importance) and feature contributions (coefficient x feature value). Results are visualized using a stem-and-bar plot showing both the feature values and their contributions.

Examples

TestSuite.explain_shap(dataset: str = 'test', sample_index: int = 0, baseline_dataset: str = 'train', baseline_sample_index: int = None, baseline_sample_size: int = 500, random_state: int = 0)

Generate SHAP (SHapley Additive exPlanations) values for local model explanation.

This method uses either Kernel SHAP or Baseline SHAP to explain model predictions for a specific sample. If baseline_sample_index is provided, Baseline SHAP is used with the specified reference point. Otherwise, Kernel SHAP is used with randomly sampled background data.

Parameters:

dataset{“main”, “train”, “test”}, default=”test”

Dataset containing the sample to be explained.

sample_indexint, default=0

Index of the sample to be explained within the selected dataset.

baseline_dataset{“main”, “train”, “test”}, default=”train”

Dataset to use for background/reference data.

baseline_sample_indexint, optional

Index of the baseline sample to use as reference point. If None, random samples will be drawn as background data.

baseline_sample_sizeint, default=500

Number of background samples to use when baseline_sample_index is None. Controls computation speed vs. accuracy trade-off.

random_stateint, default=0

Random seed for reproducible background sampling.

Returns:

ValidationResult

A result object containing:

• key: “explain_shap”

• data: Name of the dataset used

• model: Name of the model used

• inputs: Input parameters used for the analysis

• value: Dictionary containing

  • “Name”: List of feature names;

  • “Value”: List of feature values;

  • “Effect”: List of feature contributions measured by SHAP.

• value: Contains the core numerical results (feature names, values, and SHAP contributions)

• table: Provides a tabular summary combining all the information

• options: Dictionary of visualizations configuration for a horizontal bar plot where x-axis is SHAP value, and y-axis is the feature name. Run results.plot() to show this plot.

Notes

For classification tasks, SHAP values are computed for the positive class (class 1) probability. For regression tasks, SHAP values are computed for the predicted value.

Examples