OCDocker.OCScore.Analysis.Plotting.ImpactPlots

Plotting utilities for feature impact analysis (2xK contingencies, residuals, chi-square share).

Usage:

import OCDocker.OCScore.Analysis.Plotting.ImpactPlots as ocimpactplots

This module complements OCDocker.OCScore.Analysis.Impact with visual summaries: - Proportion deltas across categories - Residuals lollipop for presence row only - Per-category chi-square contribution bars - Composite report (2x2 panel) - Residuals matrix heatmap across features

OCDocker.OCScore.Analysis.Plotting.ImpactPlots.feature_report_2xk(feature, contingency, residuals_df, p_value=None, outpath='feature_report.png')[source]

Compose a 2x2 figure for a single feature.

Layout:

[0,0] proportion delta; [0,1] residual lollipop; [1,0] chi2 contribution; [1,1] legend/text box.

Parameters:

  • feature (str) – Feature name for titles.

  • contingency (pd.DataFrame) – 2xK contingency table.

  • residuals_df (pd.DataFrame) – Residuals table compatible with the contingency categories.

  • p_value (float | None, optional) – Optional p-value to include in the text box.

  • outpath (str, optional) – Output image path (default ‘feature_report.png’).

Return type:

None

OCDocker.OCScore.Analysis.Plotting.ImpactPlots.plot_chi2_contrib(contingency, feature_name, presence_level=1, title=None, outpath=None)[source]

Bar plot of per-category chi-square contributions for the presence row only.

Contribution = (O-E)^2 / E ; normalized to percentage.

Parameters:

  • contingency (pd.DataFrame) – 2xK contingency table.

  • feature_name (str) – Feature name for the plot title.

  • presence_level (int | str, optional) – Row key for presence (default 1). Falls back to last row if not found.

  • title (str | None, optional) – Title override. If None, an informative default is used.

  • outpath (str | None, optional) – If provided, saves the figure to this path.

Return type:

None

OCDocker.OCScore.Analysis.Plotting.ImpactPlots.plot_prop_delta(contingency, title='Proportion delta (1 - 0)', outpath=None)[source]

Diverging bar chart of proportion deltas across metric categories.

Parameters:

  • contingency (pd.DataFrame) – 2xK contingency table.

  • title (str, optional) – Plot title. Default is ‘Proportion delta (1 - 0)’.

  • outpath (str | None, optional) – If provided, saves the figure to this path.

Return type:

None

OCDocker.OCScore.Analysis.Plotting.ImpactPlots.plot_residuals_lollipop(residuals_df, feature_name, presence_level=1, title_suffix='Standardized residuals (feature=1)', outpath=None)[source]

Lollipop plot of standardized residuals for the ‘presence’ row only.

Draw reference lines at ±2 and ±3.

Parameters:

  • residuals_df (pd.DataFrame) – Contingency residuals table (rows correspond to presence/absence).

  • feature_name (str) – Feature name for the plot title.

  • presence_level (int | str, optional) – Row key for presence (default 1). Falls back to last row if not found.

  • title_suffix (str, optional) – Suffix to include in the plot title.

  • outpath (str | None, optional) – If provided, saves the figure to this path.

Return type:

None

OCDocker.OCScore.Analysis.Plotting.ImpactPlots.plot_residuals_matrix(residuals_dict, presence_level=1, order_by='maxabs', outpath='residuals_matrix.png')[source]

Heatmap of features (rows) vs metric categories (columns), values = residuals (feature=1).

Parameters:

  • residuals_dict (dict[str, pd.DataFrame]) – Mapping feature -> residuals DataFrame.

  • presence_level (int | str, optional) – Row key for presence (default 1).

  • order_by (str, optional) – How to order features. Options: ‘maxabs’ (default) or ‘chi2’ (reserved for future use).

  • outpath (str, optional) – Output image path (default ‘residuals_matrix.png’).

Return type:

None

OCDocker.OCScore.Analysis.Plotting.ImpactPlots.prop_delta_2xk(contingency)[source]

For a 2xK contingency table, return per-category proportion deltas.

delta = prop(feature==1) - prop(feature==0)

Parameters:

contingency (pd.DataFrame) – 2xK contingency table with rows representing feature absence/presence (0/1) and columns representing metric categories.

Returns:

Two-column DataFrame with [‘MetricCategory’, ‘prop_delta’].

Return type:

pd.DataFrame

OCDocker.OCScore.Analysis.Plotting.ImpactPlots.residuals_matrix_from_dict(residuals_dict, presence_level=1)[source]

Build a matrix (features x categories) with residuals for presence row only.

Parameters:

  • residuals_dict (dict[str, pd.DataFrame]) – Mapping feature -> residuals DataFrame (rows=presence/absence; cols=categories).

  • presence_level (int | str, optional) – Row key for presence (default 1). Falls back to last row if not found.

Returns:

Matrix with features as rows and categories as columns.

Return type:

pd.DataFrame