OCDocker.OCScore.Analysis.SHAP.ExportRunner module

SHAP analysis for exported best_model/ bundles from the staged pipeline.

Usage:

from OCDocker.OCScore.Analysis.SHAP.ExportRunner import run_export_shap_analysis

OCDocker.OCScore.Analysis.SHAP.ExportRunner.run_export_shap_analysis(export_dir, dataframe, out_dir, device=None, background_size=None, eval_size=None, explainer='gradient', stratify_by=None, seed=0, save_csv=True, policy='policy', top_n=20, family_spec=None, dependence_features=None, sample_metadata=None, target_column=None, labels=None, label_column=None, eval_split='validation', include_log_importance_plots=True, filter_zero_rows_log=True)[source]

Run SHAP on an exported staged-model bundle.

Uses validation rows for the SHAP background and validation rows for evaluation, matching the saved split_indices.npz from export.

Parameters:

  • export_dir (str | Path) – Exported best_model/ directory.

  • dataframe (pd.DataFrame) – Task-filtered reduced dataframe containing selected_features columns.

  • out_dir (str | Path) – Directory for SHAP artifacts.

  • device (str | torch.device | None, optional) – Torch device for model loading and SHAP, by default export CPU.

  • background_size (int | None, optional) – Subsample size for validation background.

  • eval_size (int | None, optional) – Subsample size for the selected SHAP evaluation split.

  • explainer (str, optional) – gradient, deep, kernel, or permutation SHAP explainer, by default gradient.

  • stratify_by (list[str] | None, optional) – Optional dataframe columns for stratified subsampling.

  • seed (int, optional) – Random seed for subsampling, by default 0.

  • save_csv (bool, optional) – Write shap_values.csv when True, by default True.

  • policy (str, optional) – File-name policy prefix for reusable SHAP plots, by default “policy”.

  • top_n (int, optional) – Number of visible features in global plots, by default 20.

  • family_spec (str | Path | mapping | None, optional) – Feature-family specification.

  • dependence_features (sequence[str] | None, optional) – Features for dependence plots.

  • sample_metadata (str | Path | pd.DataFrame | None, optional) – Sample metadata for target-family heatmap.

  • target_column (str | None, optional) – Target column in sample metadata.

  • labels (str | Path | sequence | pd.Series | pd.DataFrame | None, optional) – Labels for active-vs-decoy family distribution.

  • label_column (str | None, optional) – Label column when labels are provided as a table.

  • eval_split (str, optional) – Split to explain with SHAP. Supported values are validation and test. Default is validation.

  • include_log_importance_plots (bool, optional) – Save log-scale feature and family importance companion plots.

  • filter_zero_rows_log (bool, optional) – Remove zero rows from log-scale plots when True. When False, zero rows are plotted with a small positive floor.

Returns:

Paths to generated SHAP artifacts.

Return type:

OutputPaths

Pipeline-native SHAP for exported best_model/ bundles. Use ocdocker ocscore shap for new runs.

OutputPaths is re-exported from Paths via __all__ for convenience; it’s excluded above to avoid documenting it twice under two module paths.