ExplainabilityHelper Module¶

Contains tools for model explainability and interpretability in machine learning workflows.

class HMB.ExplainabilityHelper.OptunaMLPipelineSHAPExplainer(baseDir, experimentFolderName, testFilename, targetColumn, pickleFilePath, shapStorageKeyword, csvName='Optuna_Best_Params.csv', dpi=1080)[source]¶

Bases: object

A class to perform SHAP (SHapley Additive exPlanations) analysis on a trained machine learning model.

This class provides a pipeline for loading a trained model and its associated data, preparing the test set to match the training pipeline (including feature selection and scaling), computing SHAP values for model interpretability, and generating a variety of SHAP-based visual explanations (waterfall, force, bar, beeswarm, scatter, and summary plots).

SHAP is a unified approach to explain the output of any machine learning model. It connects game theory with local explanations, providing both global and local interpretability.

Variables:

baseDir (str) – Base directory containing data and results.
experimentFolderName (str) – Name of the folder containing model storage files.
testFilename (str) – Filename of the test dataset.
targetColumn (str) – Name of the target column in the dataset.
pickleFilePath (str) – Path to the pickled model/storage file.
shapStorageKeyword (str) – Keyword for the storage path where SHAP results will be saved.
dpi (int) – Dots per inch for saving plots.
storagePath (str) – Full path for saving SHAP visualizations.
objects (dict) – Loaded model objects (model, scaler, etc.).
testData (pd.DataFrame) – Loaded test data.
XTest (pd.DataFrame) – Test features.
yTest (pd.Series) – Test target.
model – Trained model.
explainer – SHAP explainer object.
shapValues – Computed SHAP values.
yPred – Model predictions.
yPredDecoded – Decoded predictions.

Example

import HMB.ExplainabilityHelper as eh

explainer = eh.SHAPExplainer(
  baseDir="path/to/baseDir",
  experimentFolderName="Experiment1",
  testFilename="test_data.csv",
  targetColumn="target",
  pickleFilePath=None,
  shapStorageKeyword="SHAP_Results",
  dpi=1080,
  csvName="Optuna_Best_Params.csv"
)
explainer.LoadModelAndData(maxNoRecords=100)
explainer.ComputeShapValues()
explainer.MakePredictions()
explainer.VisualizeExplanations(
  instanceIndex=0,
  categoryToExplain="all",
  noOfRecords=150,
  noOfFeatures=5
)

Notes

SHAP visualizations are saved as PNG and PDF files in the specified storage directory. The class supports both global and local interpretability visualizations. For more information about SHAP and its visualization techniques, see: https://shap.readthedocs.io/en/latest/index.html

Initialize the SHAPExplainer object with file paths and configuration.

Parameters:

baseDir (str) – Base directory containing data and results.
experimentFolderName (str) – Name of the folder containing model storage files.
testFilename (str) – Filename of the test dataset.
targetColumn (str) – Name of the target column in the dataset.
pickleFilePath (str) – Path to the pickled model/storage file (if not provided, it will be constructed).
shapStorageKeyword (str) – Keyword for the storage path where SHAP results will be saved.
csvName (str, optional) – Filename for the CSV containing Optuna’s best parameters (default: “Optuna_Best_Params.csv”).
dpi (int, optional) – Dots per inch for saving plots (default: 1080).

Notes

The storage directory for SHAP results will be created if it does not exist.
All attributes are initialized to None except for configuration parameters.

__init__(baseDir, experimentFolderName, testFilename, targetColumn, pickleFilePath, shapStorageKeyword, csvName='Optuna_Best_Params.csv', dpi=1080)[source]¶

Initialize the SHAPExplainer object with file paths and configuration.

Parameters:

baseDir (str) – Base directory containing data and results.
experimentFolderName (str) – Name of the folder containing model storage files.
testFilename (str) – Filename of the test dataset.
targetColumn (str) – Name of the target column in the dataset.
pickleFilePath (str) – Path to the pickled model/storage file (if not provided, it will be constructed).
shapStorageKeyword (str) – Keyword for the storage path where SHAP results will be saved.
csvName (str, optional) – Filename for the CSV containing Optuna’s best parameters (default: “Optuna_Best_Params.csv”).
dpi (int, optional) – Dots per inch for saving plots (default: 1080).

Notes

The storage directory for SHAP results will be created if it does not exist.
All attributes are initialized to None except for configuration parameters.

LoadModelAndData(maxNoRecords=10)[source]¶

Load the trained model objects and the test dataset from files, and prepare the test data.

This method loads the model, scaler, feature selector, and other objects from a pickle file, reads the test dataset, applies the same preprocessing pipeline as used during training (feature selection, scaling), and limits the number of records if specified.

Refer to the class “OptunaTuning” documentation in the “MachineLearningHelper” module for details on how the model and preprocessing objects are stored.

Parameters:: maxNoRecords (int, optional) – Maximum number of records to limit the test dataset to (default: 10).

Notes

Ensures that the test data columns match those used during training.
Applies the same scaler and feature selector as in the training pipeline.
If maxNoRecords is set, randomly samples up to that number of records from the test set.
Prints the Optuna’s best parameters and columns used during training.

ComputeShapValues(maxEvals=None)[source]¶

Initialize the SHAP explainer and compute SHAP values for the test set.

This method creates a SHAP explainer object using the trained model and the prepared test features, then computes SHAP values for the test set to explain model predictions.

Parameters:: maxEvals (int, optional) – Maximum number of evaluations for the SHAP explainer (default: None, which means noOfFeatures * 2 + 1).

Notes

The computed SHAP values are stored in self.shapValues.
Prints the shape of the computed SHAP values.
The SHAP explainer is stored in self.explainer.

MakePredictions()[source]¶

Make predictions on the test set using the loaded model and decode them.

This method uses the trained model to predict on the prepared test features, and decodes the predicted labels back to their original form using the stored label encoder.

Notes

The predictions are stored in self.yPred.
The decoded predictions are stored in self.yPredDecoded.

VisualizeComparativeFeatureImportance(noOfFeatures=10)[source]¶

Generate a comparative bar plot showing SHAP feature importance across AMD categories.

This method computes mean absolute SHAP values per feature for each diagnostic category and visualizes them in a grouped bar chart for direct comparison.

Parameters:: noOfFeatures (int, optional) – Number of top features to display (default: 10).

VisualizeDependenceWithAnnotations(topFeatures=None)[source]¶

Generate SHAP dependence plots for specified top features with automatic interaction detection.

Parameters:: topFeatures (list of str, optional) – List of feature names to generate dependence plots for. If None, the top 4 features by mean absolute SHAP value will be selected automatically.

VisualizeClassStratifiedBeeswarm(noOfFeatures=15)[source]¶

Generate class-stratified SHAP beeswarm plots for the top features. This method creates separate SHAP beeswarm plots for each diagnostic category in the test set, allowing for visual comparison of feature importance distributions across classes.

Parameters:: noOfFeatures (int, optional) – Number of top features to display in the beeswarm plot (default: 15).

VisualizeErrorAnalysis(maxErrors=5)[source]¶

Generate SHAP waterfall plots for misclassified instances in the test set. This method identifies misclassified samples based on the model’s predictions and the true labels, then generates SHAP waterfall plots for a specified number of these error cases, providing insights into the feature contributions that led to the misclassification.

Parameters:: maxErrors (int, optional) – Maximum number of misclassified instances to visualize (default: 5).

VisualizeDecisionPlot(noOfInstances=500, noOfFeatures=20, classLabel=None)[source]¶

Generate a SHAP decision plot showing cumulative feature contributions across multiple instances.

This method creates a decision plot where each line represents one test sample, showing how SHAP values for top features accumulate to produce the final model output. Color-coding by class label enables visual assessment of class separation.

Parameters:

noOfInstances (int, optional) – Number of instances to display (default: 500).
noOfFeatures (int, optional) – Number of top features to include (default: 20).
classLabel (int | str | None, optional) – Specific class to filter; None shows all classes.

VisualizeExplanations(instanceIndex=None, categoryToExplain='all', noOfRecords=150, noOfFeatures=5)[source]¶

Generate and save various SHAP visualizations for model interpretability.

This method produces and saves the following SHAP plots:

Waterfall plot for a specific instance’s prediction.
Force plot for a specific instance’s prediction.
Bar plot (global feature importance).
Beeswarm plot (global feature importance).
Scatter and summary plots for the test set, optionally filtered by class/category.

Parameters:

instanceIndex (int, optional) – Index of the specific instance to explain. If None, a random index is chosen.
categoryToExplain (int | str, optional) – The class label for reference in plots (e.g., 0 for Negative Label = 0). If “all”, plots are generated for all classes.
noOfRecords (int, optional) – Number of records to consider for summary/scatter plots.
noOfFeatures (int, optional) – Number of top features to display in plots.

Notes

All plots are saved as both PNG and PDF files in the storage directory.
If categoryToExplain is “all”, plots are generated for each unique class in the target variable.
Prints a message when visualizations are saved.
Uses SHAP’s built-in plotting functions for visualization.

class HMB.ExplainabilityHelper.CAMExplainerPyTorch(torchModel=None, yoloModel=None, device='cpu', camType='gradcam', imgSize=640, alpha=0.45, outputBase=None, figsize=(14, 12), dpi=300, fontSize=14, topN=20, debug=False)[source]¶

Bases: object

A convenience wrapper to run CAM / attribution methods on a torch model and save results.

This class provides a compact, self-contained interface for computing a wide set of class-discriminative and gradient-based attribution maps (Grad-CAM family, Layer-CAM, Score-CAM, Ablation-CAM) and classic attribution techniques (saliency, SmoothGrad, Integrated Gradients, Occlusion, Grad x Input). The implementation prefers the instance-level implementations when available and falls back to module-level helper functions present in the same module.

The class is intended to be used in explainability pipelines where a trained PyTorch classification model (or a YOLO classification wrapper) is available and a human-readable visualization (heatmap overlay and annotated figure) is required.

Variables:

torchModel (torch.nn.Module | None) – The underlying PyTorch model used for inference and gradients.
yoloModel (object | None) – Optional Ultralytics YOLO wrapper from which a torch model may be extracted.
device (torch.device) – Device where model and tensors are executed.
camType (str) – Selected CAM / attribution method name (lowercase key used by dispatch map).
imgSize (int) – Default square input size for preprocessing images.
alpha (float) – Default overlay transparency when blending heatmaps with the image.
outputBase (Path | None) – Optional base path where outputs (Overlays, Heatmaps) are saved.
figsize (tuple) – Default figure size used by annotated visualizations.
dpi (int) – Default DPI used to render annotated images.
fontSize (int) – Base font size used in annotations.
topN (int) – Top-N value used for uncertainty/confidence tracking.
debug (bool) – Enable verbose debug prints if True.
targetLayer (torch.nn.Module | None) – Default convolutional layer chosen as target for CAM computations.

Example

import torch
import numpy as np
from PIL import Image
from HMB.ExplainabilityHelper import CAMExplainerPyTorch

# Create a tiny dummy model for a quick smoke test.
model = torch.nn.Sequential(
  torch.nn.Conv2d(3, 8, kernel_size=3, padding=1),
  torch.nn.ReLU(),
  torch.nn.AdaptiveAvgPool2d((8, 8)),
  torch.nn.Flatten(),
  torch.nn.Linear(8 * 8 * 8, 10)
)

explainer = CAMExplainerPyTorch(
  torchModel=model,
  device="cpu",
  camType="gradcam",
  imgSize=224,
  outputBase="./ExplainabilityOut",
  debug=True
)

# Process a single image and save overlay/annotated outputs.
img = Image.fromarray((np.random.rand(224, 224, 3) * 255).astype("uint8"))
tmpPath = Path("./tempSampleImage.png")
img.save(tmpPath)
result = explainer.ProcessImage(tmpPath, classNames={i: str(i) for i in range(10)})
print(result)

Notes

The class-level implementations are intended to be self-sufficient; if a module-level helper function exists with the same name the instance will prefer the instance method first and fall back to the module function.
Some CAMs (Score-CAM, Ablation-CAM) are computationally heavy for large models or high-resolution inputs; tune top-K and sample counts accordingly.
Removed methods: RISE, GuidedGradCam, GuidedBackprop, GradientShap and DeepLift are intentionally not supported at the class-level and will raise a RuntimeError if requested via the class dispatch. Module-level helpers (if present) remain unchanged and can be invoked directly.
Naming conventions: method names use CamelCase and variables use camelCase.

Initialize the CAMExplainerPyTorch with model, device and visualization settings.

Parameters:

torchModel (torch.nn.Module | None) – The underlying PyTorch model used for inference and gradients.
yoloModel (object | None) – Optional Ultralytics YOLO wrapper from which a torch model may be extracted.
device (str) – Device where model and tensors are executed (“cpu” or “cuda”).
camType (str) – Selected CAM / attribution method name (lowercase key used by dispatch map).
imgSize (int) – Default square input size for preprocessing images.
alpha (float) – Default overlay transparency when blending heatmaps with the image.
outputBase (Path | None) – Optional base path where outputs (Overlays, Heatmaps) are saved.
figsize (tuple) – Default figure size used by annotated visualizations.
dpi (int) – Default DPI used to render annotated images.
fontSize (int) – Base font size used in annotations.
topN (int) – Top-N value used for uncertainty/confidence tracking.
debug (bool) – Enable verbose debug prints if True.

Notes

If both torchModel and yoloModel are provided, torchModel takes precedence.
If no torchModel is provided but a yoloModel is, the underlying torch model is extracted automatically.

AVAILABLE_CAM_METHODS = {'ablationcam', 'eigencam', 'gradcam', 'gradcampp', 'gradxinput', 'integratedgradients', 'layercam', 'occlusion', 'saliency', 'scorecam', 'smoothgrad', 'smoothgradcampp', 'xgradcam'}¶

__init__(torchModel=None, yoloModel=None, device='cpu', camType='gradcam', imgSize=640, alpha=0.45, outputBase=None, figsize=(14, 12), dpi=300, fontSize=14, topN=20, debug=False)[source]¶

Initialize the CAMExplainerPyTorch with model, device and visualization settings.

Parameters:

torchModel (torch.nn.Module | None) – The underlying PyTorch model used for inference and gradients.
yoloModel (object | None) – Optional Ultralytics YOLO wrapper from which a torch model may be extracted.
device (str) – Device where model and tensors are executed (“cpu” or “cuda”).
camType (str) – Selected CAM / attribution method name (lowercase key used by dispatch map).
imgSize (int) – Default square input size for preprocessing images.
alpha (float) – Default overlay transparency when blending heatmaps with the image.
outputBase (Path | None) – Optional base path where outputs (Overlays, Heatmaps) are saved.
figsize (tuple) – Default figure size used by annotated visualizations.
dpi (int) – Default DPI used to render annotated images.
fontSize (int) – Base font size used in annotations.
topN (int) – Top-N value used for uncertainty/confidence tracking.
debug (bool) – Enable verbose debug prints if True.

Notes

If both torchModel and yoloModel are provided, torchModel takes precedence.
If no torchModel is provided but a yoloModel is, the underlying torch model is extracted automatically.

ExtractModel(yoloModel)[source]¶

Extract torch model from a YOLO wrapper or return the same model.

Parameters:: yoloModel (object | None) – Ultralytics YOLO wrapper or a torch.nn.Module.
Returns:: Extracted underlying torch model when possible, otherwise returns the provided object or None if input is None.
Return type:: torch.nn.Module | object | None

Notes

This mirrors the module-level helper but lives on the instance so it is always available. It tolerates wrappers that nest a .model attribute.

GetLastConvLayer(model)[source]¶

Find the last Conv2d layer to target for Grad-CAM.

Parameters:: model (torch.nn.Module | None) – PyTorch model to inspect.
Returns:: The last torch.nn.Conv2d module found in the model or None if no Conv2d layer is present.
Return type:: torch.nn.Module | None

Notes

Traverses the module tree and returns the deepest Conv2d instance. This method is safe to call with None and will return None in that case.

NormalizeHeatmap(heatmap)[source]¶

Normalize and enhance heatmap contrast to the [0,1] range.

Parameters:: heatmap (numpy.ndarray) – Raw heatmap array with arbitrary range.
Returns:: Normalized and smoothed heatmap clipped to [0,1].
Return type:: numpy.ndarray

Notes

Applies clipping, percentile-based contrast stretching, Gaussian blur and a mild gamma correction to improve visual contrast.

ApplyHeatmapOverlay(imageRgb, heatmap, alpha=None)[source]¶

Blend heatmap onto an RGB image and return uint8 RGB result.

Parameters:

imageRgb (numpy.ndarray) – Original RGB image array (H, W, 3) in uint8 or float.
heatmap (numpy.ndarray) – Heatmap normalized to [0,1] with shape (H, W).
alpha (float | None) – Blend factor for overlay. If None uses instance alpha.

Returns:

Blended RGB image as uint8.

Return type: