OCDocker.OCScore.Analysis.SHAP package

Submodules

• OCDocker.OCScore.Analysis.SHAP.ExportRunner module
  • run_export_shap_analysis()
• OCDocker.OCScore.Analysis.SHAP.Explain module
  • compute_shap_values()
• OCDocker.OCScore.Analysis.SHAP.Plots module
  • assign_feature_families()
  • beeswarm()
  • compute_feature_importance_table()
  • compute_family_importance_table()
  • compute_label_family_distribution_table()
  • compute_target_family_shap_table()
  • feature_importance_barh()
  • load_family_spec()
  • save_beeswarm_plot()
  • save_dependence_plots()
  • save_family_importance_plot()
  • save_global_feature_importance_plot()
  • save_label_family_distribution_plot()
  • save_shap_plot_suite()
  • save_shap_plot_suite_from_paths()
  • save_target_family_heatmap()
  • shap_correlation_heatmap()
• OCDocker.OCScore.Analysis.SHAP.Paths module
  • OutputPaths

Module contents

Pipeline-native SHAP for exported best_model/ bundles.

class OCDocker.OCScore.Analysis.SHAP.OutputPaths(out_dir, feature_importance_png, beeswarm_png, shap_values_npy, shap_values_csv=None, artifacts=<factory>)

Bases: object

Container for SHAP analysis output file paths.

Parameters:

• out_dir (str)

• feature_importance_png (str)

• beeswarm_png (str)

• shap_values_npy (str)

• shap_values_csv (str | None)

• artifacts (dict[str, Any])

out_dir: str

feature_importance_png: str

beeswarm_png: str

shap_values_npy: str

shap_values_csv: str | None = None

artifacts: dict[str, Any]

OCDocker.OCScore.Analysis.SHAP.assign_feature_families(feature_names, family_spec=None)

Assign features to configurable families.

Parameters:

• feature_names (sequence[str]) – Feature names.

• family_spec (str | Path | mapping | None, optional) – Family specification.

Returns:

Table with feature and family columns.

Return type:

pd.DataFrame

OCDocker.OCScore.Analysis.SHAP.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)

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

OCDocker.OCScore.Analysis.SHAP.save_shap_plot_suite(shap_values, feature_names, output_dir, policy='policy', feature_matrix=None, dependence_features=None, family_spec=None, sample_metadata=None, target_column=None, labels=None, label_column=None, top_n=20, dpi=300, rng_seed=0, include_log_importance_plots=True, filter_zero_rows_log=True)

Save reusable SHAP plots for a policy.

Parameters:

• shap_values (np.ndarray | pd.DataFrame) – SHAP values.

• feature_names (sequence[str] | None) – Feature names.

• output_dir (str | Path) – Output directory.

• policy (str, optional) – File-name policy prefix.

• feature_matrix (str | Path | np.ndarray | pd.DataFrame | None, optional) – Feature matrix for beeswarm and dependence plots.

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

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

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

• target_column (str | None, optional) – Metadata target column.

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

• label_column (str | None, optional) – Label column for table labels.

• top_n (int, optional) – Number of visible features.

• dpi (int, optional) – Figure DPI.

• rng_seed (int | None, optional) – Optional local random seed for SHAP versions that support it.

• 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:

Output artifact paths.

Return type:

dict[str, Any]

OCDocker.OCScore.Analysis.SHAP.save_shap_plot_suite_from_paths(shap_values_path, output_dir, policy='policy', feature_names_path=None, feature_matrix_path=None, dependence_features=None, family_spec=None, sample_metadata_path=None, target_column=None, labels_path=None, label_column=None, top_n=20, dpi=300, rng_seed=0, include_log_importance_plots=True, filter_zero_rows_log=True)

Save reusable SHAP plots from explicit input paths.

Parameters:

• shap_values_path (str | Path) – SHAP values CSV or NPY path.

• output_dir (str | Path) – Output directory.

• policy (str, optional) – File-name policy prefix.

• feature_names_path (str | Path | None, optional) – Feature-name source for NPY SHAP values.

• feature_matrix_path (str | Path | None, optional) – Feature matrix CSV path.

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

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

• sample_metadata_path (str | Path | None, optional) – Sample metadata CSV path.

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

• labels_path (str | Path | None, optional) – Label CSV path.

• label_column (str | None, optional) – Label column.

• top_n (int, optional) – Number of visible features.

• dpi (int, optional) – Figure DPI.

• rng_seed (int | None, optional) – Optional local random seed for SHAP versions that support it.

• 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:

Output artifact paths.

Return type:

dict[str, Any]

Export-bundle SHAP for staged best_model/ artifacts (ocdocker ocscore shap).