OCDocker.OCScore.Analysis.SHAP.Plots module

Reusable SHAP plotting utilities.

Usage:

from OCDocker.OCScore.Analysis.SHAP.Plots import save_shap_plot_suite

OCDocker.OCScore.Analysis.SHAP.Plots.assign_feature_families(feature_names, family_spec=None)[source]

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.Plots.beeswarm(shap_2d, X_eval, out_png, figsize=(10, 6), rng_seed=0)[source]

Wrapper around SHAP beeswarm plotting.

Parameters:

  • shap_2d (np.ndarray) – SHAP values with shape (n_samples, n_features).

  • X_eval (pd.DataFrame) – Evaluation features.

  • out_png (str) – Output PNG path.

  • figsize (tuple[int, int], optional) – Figure size.

  • rng_seed (int | None, optional) – Optional local random seed.

Returns:

Output path.

Return type:

str

OCDocker.OCScore.Analysis.SHAP.Plots.compute_feature_importance_table(shap_values, feature_names=None)[source]

Compute global SHAP feature importance.

Parameters:

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

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

Returns:

Ranked feature-importance table.

Return type:

pd.DataFrame

OCDocker.OCScore.Analysis.SHAP.Plots.compute_family_importance_table(shap_values, feature_names=None, family_spec=None, policy=None)[source]

Compute SHAP importance aggregated by feature family.

Parameters:

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

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

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

  • policy (str | None, optional) – Optional policy label for cross-policy aggregation.

Returns:

Family-importance table.

Return type:

pd.DataFrame

OCDocker.OCScore.Analysis.SHAP.Plots.compute_label_family_distribution_table(shap_values, feature_names, labels, family_spec=None, label_column=None)[source]

Compute sample-level SHAP family scores grouped by labels.

Parameters:

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

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

  • labels (str | Path | sequence | pd.Series | pd.DataFrame) – Sample labels.

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

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

Returns:

Long-form sample-family table.

Return type:

pd.DataFrame

OCDocker.OCScore.Analysis.SHAP.Plots.compute_target_family_shap_table(shap_values, feature_names, sample_metadata, target_column, family_spec=None)[source]

Compute per-target mean absolute SHAP by feature family.

Parameters:

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

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

  • sample_metadata (str | Path | pd.DataFrame) – Sample metadata.

  • target_column (str) – Metadata column containing target IDs.

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

Returns:

Long-form target-family table.

Return type:

pd.DataFrame

OCDocker.OCScore.Analysis.SHAP.Plots.feature_importance_barh(shap_2d, feature_names, out_png, top_k=20, figsize=(10, 6))[source]

Horizontal bar chart of relative SHAP importance per feature.

Parameters:

  • shap_2d (np.ndarray) – SHAP values.

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

  • out_png (str) – Output PNG path.

  • top_k (int, optional) – Number of top features.

  • figsize (tuple[int, int], optional) – Figure size.

Returns:

Output path.

Return type:

str

OCDocker.OCScore.Analysis.SHAP.Plots.load_family_spec(family_spec=None)[source]

Load a feature-family specification.

Parameters:

family_spec (str | Path | mapping | None, optional) – Family specification as a dict, JSON path, YAML path, or None for suggested defaults.

Returns:

Family names mapped to shell-style wildcard patterns.

Return type:

dict[str, list[str]]

OCDocker.OCScore.Analysis.SHAP.Plots.save_beeswarm_plot(shap_values, feature_matrix, feature_names, output_dir, policy, top_n=20, dpi=300, figsize=(10.0, 7.0), rng_seed=0)[source]

Save a SHAP beeswarm plot.

Parameters:

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

  • feature_matrix (str | Path | np.ndarray | pd.DataFrame) – Feature matrix.

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

  • output_dir (str | Path) – Output directory.

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

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

  • dpi (int, optional) – Figure DPI.

  • figsize (tuple[float, float], optional) – Figure size.

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

Returns:

Output artifact paths.

Return type:

dict[str, str]

OCDocker.OCScore.Analysis.SHAP.Plots.save_dependence_plots(shap_values, feature_matrix, feature_names, requested_features, output_dir, policy, dpi=300, figsize=(7.0, 5.0))[source]

Save SHAP dependence plots for requested features.

Parameters:

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

  • feature_matrix (str | Path | np.ndarray | pd.DataFrame) – Feature matrix.

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

  • requested_features (sequence[str]) – Features to plot.

  • output_dir (str | Path) – Output directory.

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

  • dpi (int, optional) – Figure DPI.

  • figsize (tuple[float, float], optional) – Figure size.

Returns:

Written dependence plots and skipped features.

Return type:

dict[str, Any]

OCDocker.OCScore.Analysis.SHAP.Plots.save_family_importance_plot(shap_values, feature_names, output_dir, policy, family_spec=None, dpi=300, figsize=None, include_log_plot=True, filter_zero_rows_log=True)[source]

Save feature-family SHAP aggregation plot and CSV files.

Parameters:

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

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

  • output_dir (str | Path) – Output directory.

  • policy (str) – Policy label.

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

  • dpi (int, optional) – Figure DPI.

  • figsize (tuple[float, float] | None, optional) – Figure size.

  • include_log_plot (bool, optional) – Save a log-scale companion plot when True.

  • 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, str]

OCDocker.OCScore.Analysis.SHAP.Plots.save_global_feature_importance_plot(shap_values, feature_names, output_dir, policy, top_n=20, dpi=300, figsize=None, include_log_plot=True, filter_zero_rows_log=True)[source]

Save a global SHAP feature-importance plot and CSV.

Parameters:

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

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

  • output_dir (str | Path) – Output directory.

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

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

  • dpi (int, optional) – Figure DPI.

  • figsize (tuple[float, float] | None, optional) – Figure size.

  • include_log_plot (bool, optional) – Save a log-scale companion plot when True.

  • 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, str]

OCDocker.OCScore.Analysis.SHAP.Plots.save_label_family_distribution_plot(shap_values, feature_names, labels, output_dir, policy, family_spec=None, label_column=None, dpi=300, figsize=None)[source]

Save active-vs-decoy SHAP family distribution plot and CSV.

Parameters:

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

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

  • labels (str | Path | sequence | pd.Series | pd.DataFrame) – Sample labels.

  • output_dir (str | Path) – Output directory.

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

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

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

  • dpi (int, optional) – Figure DPI.

  • figsize (tuple[float, float] | None, optional) – Figure size.

Returns:

Output artifact paths.

Return type:

dict[str, str]

OCDocker.OCScore.Analysis.SHAP.Plots.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)[source]

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.Plots.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)[source]

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]

OCDocker.OCScore.Analysis.SHAP.Plots.save_target_family_heatmap(shap_values, feature_names, sample_metadata, target_column, output_dir, policy, family_spec=None, dpi=300, figsize=None, include_log_plot=True, filter_zero_rows_log=True)[source]

Save a per-target SHAP family heatmap and CSV.

Parameters:

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

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

  • sample_metadata (str | Path | pd.DataFrame) – Sample metadata.

  • target_column (str) – Metadata column containing target IDs.

  • output_dir (str | Path) – Output directory.

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

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

  • dpi (int, optional) – Figure DPI.

  • figsize (tuple[float, float] | None, optional) – Figure size.

  • include_log_plot (bool, optional) – Save a log-color companion heatmap when True.

  • filter_zero_rows_log (bool, optional) – Remove all-zero rows and columns from log-color heatmaps when True. When False, zero cells are plotted with a small positive floor.

Returns:

Output artifact paths.

Return type:

dict[str, str]

OCDocker.OCScore.Analysis.SHAP.Plots.shap_correlation_heatmap(shap_values, out_png, feature_names=None, figsize=(12, 10))[source]

Plot a heatmap of SHAP value correlations across features.

Parameters:

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

  • out_png (str) – Output PNG path.

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

  • figsize (tuple[int, int], optional) – Figure size.

Returns:

Output path.

Return type:

str