nirs4all.pipeline.explainer module

Pipeline explainer - Handles SHAP explanation generation.

This module provides the Explainer class for generating model explanations using SHAP (SHapley Additive exPlanations) on trained pipelines.

Supports the same prediction sources as the Predictor: prediction dicts, folder paths, artifact IDs, bundles, and trace IDs are resolved via PredictionResolver.

class nirs4all.pipeline.explainer.Explainer(runner: PipelineRunner)[source]

Bases: object

Handles SHAP explanation generation for trained models.

This class manages the explanation workflow: resolving a prediction source via PredictionResolver, replaying the pipeline to capture the trained model, and generating SHAP explanations with visualizations.

Variables:

  • runner – Parent PipelineRunner instance.

  • pipeline_uid – Unique identifier for the pipeline.

  • artifact_loader – Loader for trained model artifacts.

  • config_path – Path to the pipeline configuration.

  • target_model – Metadata for the target model.

  • captured_model – Tuple of (model, controller) captured during replay.

capture_model(model: Any, controller: Any) → None[source]

Capture a model during pipeline execution for SHAP analysis.

This method is called by the model controller during explain mode to capture the trained model instance.

Parameters:

  • model – Trained model instance.

  • controller – Controller that trained the model.

explain(prediction_obj: dict[str, Any] | str, dataset: DatasetConfigs | SpectroDataset | ndarray | tuple[ndarray, ...] | dict | list[dict] | str | list[str], dataset_name: str = 'explain_dataset', shap_params: dict[str, Any] | None = None, verbose: int = 0, plots_visible: bool = True) → tuple[dict[str, Any], str][source]

Generate SHAP explanations for a saved model.

Parameters:

  • prediction_obj – Model identifier (dict with config_path or prediction ID).

  • dataset – Dataset to explain on.

  • dataset_name – Name for the dataset.

  • shap_params – SHAP configuration parameters.

  • verbose – Verbosity level.

  • plots_visible – Whether to display plots interactively.

Returns:

Tuple of (shap_results_dict, output_directory_path).

Example

>>> explainer = Explainer(runner)
>>> shap_results, out_dir = explainer.explain(
...     {"config_path": "0001_abc123"},
...     X_test,
...     shap_params={"n_samples": 200, "visualizations": ["spectral", "summary"]},
... )