OCDocker.OCScore.Analysis.Impact package

Summarize and visualize feature impact using Net Benefit Score (NBS) and related statistics.

Usage:

import OCDocker.OCScore.Analysis.Impact as ocimpact

It exposes high-level functions:

  • build_impact_overview: build a table with NBS, direction, strength and stats

  • plot_impact_arrows_inline_labels: render arrow plot with inline labels

  • get_neutral_features: list neutral features by Normalized Binding Score < tau or Direction == ‘neutral’

OCDocker.OCScore.Analysis.Impact.build_impact_overview(chi_df, contingency_dict, metric, presence_level=1, beneficial_custom=None, tau=0.05)[source]

Build a clear impact table with NBS, direction, strength and stats.

Parameters:

  • chi_df (pd.DataFrame) – DataFrame with chi-square outcomes, requires at least columns [‘Feature’, “Cramér’s V”, ‘Chi2 Statistic’, ‘p-value’].

  • contingency_dict (dict[str, pd.DataFrame]) – Mapping from feature -> contingency table with rows as presence (0/1) and columns as ordered categories (strings).

  • metric (str) – Metric name used to identify beneficial categories (‘AUC’ or ‘RMSE’).

  • presence_level (Union[int, str], optional) – Row key considered as presence (default: 1). If not found, falls back.

  • beneficial_custom (Optional[Iterable[str]], optional) – Explicit set of beneficial categories to use instead of defaults.

  • tau (float, optional) – Tolerance to classify neutral direction by Normalized Binding Score < tau (default: 0.05).

Returns:

Sorted DataFrame with columns: ‘Feature’, ‘NBS’, ‘Direction’, ‘Strength’, ‘Chi2’, ‘p-value’, ‘CramersV’, ‘FavoredCategory’, ‘HurtCategory’, ‘Normalized Binding Score’, ‘NegLog10P’.

Return type:

pd.DataFrame

OCDocker.OCScore.Analysis.Impact.get_neutral_features(impact_df, tau=0.05)[source]

Return a sorted list of neutral features by Direction or Normalized Binding Score < tau.

Parameters:

  • impact_df (pd.DataFrame) – DataFrame returned by build_impact_overview, with ‘NBS’ and ‘Direction’.

  • tau (float, optional) – Neutrality threshold on original NBS scale (default: 0.05).

Returns:

Sorted list of neutral feature names.

Return type:

list[str]

OCDocker.OCScore.Analysis.Impact.plot_impact_arrows_inline_labels(impact_df, title, outpath=None, tau=0.05, thresholds=(0.1, 0.2, 0.35), xpad=0.025, height_per_feature=0.42, max_height=28.0, font_size=10)[source]

Render an arrow plot with inline feature labels based on NBS.

Parameters:

  • impact_df (pd.DataFrame) – DataFrame with columns [‘Feature’,’NBS’] and optionally ‘Direction’.

  • title (str) – Plot title.

  • outpath (Optional[str], optional) – Output image path. If None, the figure is not saved to disk.

  • tau (float, optional) – Neutrality threshold on original NBS scale (default: 0.05).

  • thresholds (Sequence[float], optional) – Thresholds for marker strength derived from Normalized Binding Score (scaled) (default: 0.10, 0.20, 0.35).

  • xpad (float, optional) – Horizontal text offset relative to marker (default: 0.025).

  • height_per_feature (float, optional) – Figure height contribution per feature (default: 0.42).

  • max_height (float, optional) – Maximum figure height (default: 28.0).

  • font_size (int, optional) – Font size for labels (default: 10).

Return type:

None