smx.plotting.summary

Summary and diagnostic plots for SMX explanation results.

Functions

plot_lrc_bar

Horizontal bar chart of LRC scores per zone.

plot_predicate_heatmap

Zone × predicate heatmap of LRC scores.

plot_zone_scores

Split-violin of PC1 scores per zone by class.

plot_all_thresholds_overlay

Full-spectrum overlay of top-predicate threshold per zone.

plot_faithfulness_curve

Progressive masking curve with shaded AUC and summary annotations.

Functions

plot_lrc_bar(→ Union[None, pandas.DataFrame])	Horizontal bar chart of LRC scores per zone.
plot_predicate_heatmap(→ Union[None, pandas.DataFrame])	Heatmap of LRC scores across zones and predicate thresholds.
plot_zone_scores(→ Union[None, pandas.DataFrame])	Split-violin plot of PC1 scores per spectral zone, split by class.
plot_all_thresholds_overlay(→ Union[None, ...)	Full-spectrum overlay of the top-ranked threshold per zone.
plot_faithfulness_curve(→ Union[None, pandas.DataFrame])	Plot the progressive masking faithfulness curve and its AUC.

Module Contents

smx.plotting.summary.plot_lrc_bar(zone_ranking_df: pandas.DataFrame, output_path: str | pathlib.Path | None, *, title: str | None = None, colorscale: str | None = None, theme: smx.plotting.theme.SMXTheme | None = None, width: int = 800, height: int = 500, return_df: bool = False) → None | pandas.DataFrame

Horizontal bar chart of LRC scores per zone.

Each bar represents a spectral zone and is colored according to the same LRC-score colorscale used in plot_zone_ranking_over_spectrum(), making the two plots directly comparable. The figure is always displayed; set return_df=True to return the normalized ranking DataFrame.

Parameters

zone_ranking_dfpd.DataFrame

LRC table (Zone / Local_Reaching_Centrality columns) or a pre-normalized zone / score / rank DataFrame.

output_pathstr or Path, optional

Destination file. If None, no file is written.

titlestr, optional

Figure title.

colorscalestr, optional

Plotly colorscale name. Defaults to theme.colorscale.

themeSMXTheme, optional

Visual theme. Defaults to DEFAULT_THEME.

widthint, default 800

Figure width in pixels (static export only).

heightint, default 500

Figure height in pixels (static export only).

return_dfbool, default False

If True, return the normalized ranking DataFrame.

Returns

pd.DataFrame or None

Normalized zone / score / rank DataFrame when return_df is True.

smx.plotting.summary.plot_predicate_heatmap(lrc_natural_df: pandas.DataFrame, output_path: str | pathlib.Path | None, *, title: str | None = None, colorscale: str | None = None, theme: smx.plotting.theme.SMXTheme | None = None, width: int = 1000, height: int = 550, return_df: bool = False) → None | pandas.DataFrame

Heatmap of LRC scores across zones and predicate thresholds.

Rows are spectral zones (sorted by maximum LRC, highest at top). Columns are predicates within each zone, grouped by operator (≤ then >) and sorted by threshold rank within each group. Cell color encodes LRC score on the same colorscale as the bar chart and zone-ranking plot. The figure is always displayed; set return_df=True to return the pivot DataFrame.

Parameters

lrc_natural_dfpd.DataFrame

smx.lrc_natural_ — must contain Zone, Operator, Threshold_Natural, and Local_Reaching_Centrality columns.

output_pathstr or Path, optional

Destination file. If None, no file is written.

titlestr, optional

Figure title.

colorscalestr, optional

Plotly colorscale name. Defaults to theme.colorscale.

themeSMXTheme, optional

Visual theme.

widthint, default 1000

Figure width (static export).

heightint, default 550

Figure height (static export).

return_dfbool, default False

If True, return the pivot DataFrame (zones × predicate labels).

Returns

pd.DataFrame or None

Pivot DataFrame (zones × predicate labels → LRC score) when return_df is True.

smx.plotting.summary.plot_zone_scores(zones: pandas.DataFrame | Dict[str, pandas.DataFrame], y_labels: pandas.Series, output_path: str | pathlib.Path | None, spectral_cuts: Iterable | None = None, *, title: str | None = None, class_colors: Dict[str, str] | None = None, theme: smx.plotting.theme.SMXTheme | None = None, width: int = 1200, height: int = 580, return_df: bool = False) → None | pandas.DataFrame

Split-violin plot of PC1 scores per spectral zone, split by class.

When exactly two classes are present the violins are mirrored (split). For three or more classes, separate overlapping violins are drawn. The figure is always displayed; set return_df=True to return the zone scores DataFrame.

Parameters

zonespd.DataFrame or dict[str, pd.DataFrame]

Either the full calibration DataFrame (requires spectral_cuts) or a pre-extracted zone dict such as smx.zones_natural_.

y_labelspd.Series

Class labels aligned row-wise with zones.

output_pathstr or Path, optional

Destination file. If None, no file is written.

spectral_cutsiterable, optional

Zone boundary definitions. Required when zones is a DataFrame.

titlestr, optional

Figure title.

class_colorsdict[str, str], optional

Per-class hex/CSS colors. Defaults to theme.class_colors.

themeSMXTheme, optional

Visual theme.

widthint, default 1200

Figure width (static export).

heightint, default 580

Figure height (static export).

return_dfbool, default False

If True, return the zone PC1 scores DataFrame.

Returns

pd.DataFrame or None

Zone PC1 score DataFrame (samples × zones) when return_df is True.

smx.plotting.summary.plot_all_thresholds_overlay(lrc_natural_df: pandas.DataFrame, zones_natural: Dict[str, pandas.DataFrame], pca_info_natural: Dict, y_labels: pandas.Series, spectral_cuts: Iterable, output_path: str | pathlib.Path | None, *, title: str | None = None, class_colors: Dict[str, str] | None = None, theme: smx.plotting.theme.SMXTheme | None = None, width: int = 1200, height: int = 500, return_df: bool = False) → None | pandas.DataFrame

Full-spectrum overlay of the top-ranked threshold per zone.

Mean class spectra are drawn as solid lines across the full spectral axis. The top-ranked predicate threshold for each zone is reconstructed from PCA space and overlaid as a dashed line within its zone’s x-range. Threshold line colors follow the LRC-score colorscale so the most influential zones stand out visually. The figure is always displayed; set return_df=True to return the top-predicate-per-zone DataFrame.

Parameters

lrc_natural_dfpd.DataFrame

smx.lrc_natural_.

zones_naturaldict[str, pd.DataFrame]

smx.zones_natural_.

pca_info_naturaldict

smx.pca_info_natural_.

y_labelspd.Series

Class labels aligned row-wise with the calibration data.

spectral_cutsiterable

Zone boundary definitions.

output_pathstr or Path, optional

Destination file. If None, no file is written.

titlestr, optional

Figure title.

class_colorsdict[str, str], optional

Per-class hex/CSS colors.

themeSMXTheme, optional

Visual theme.

widthint, default 1200

Figure width (static export).

heightint, default 500

Figure height (static export).

return_dfbool, default False

If True, return the top-predicate-per-zone DataFrame.

Returns

pd.DataFrame or None

Top-predicate-per-zone DataFrame when return_df is True.

smx.plotting.summary.plot_faithfulness_curve(faithfulness_result: Dict, output_path: str | pathlib.Path | None, *, title: str | None = None, theme: smx.plotting.theme.SMXTheme | None = None, width: int = 1100, height: int = 560, show_percentile: bool = False, show_faithfulness_level: bool = True, show_summary: bool = True, show_level_intervals: bool = True, return_df: bool = False) → None | pandas.DataFrame

Plot the progressive masking faithfulness curve and its AUC.

The figure is always displayed; set return_df=True to return the masking-curve DataFrame.

Parameters

faithfulness_resultdict

Output of smx.pipeline.SMX.evaluate_faithfulness(). Must contain curve_df and is expected to include auc, level, null_percentile, and related summary fields.

output_pathstr or Path, optional

Destination file. If None, no file is written.

titlestr, optional

Figure title.

themeSMXTheme, optional

Visual theme.

widthint, default 1100

Figure width (static export).

heightint, default 560

Figure height (static export).

show_percentilebool, default False

Whether to include the random-baseline percentile in the summary box. The value remains available in faithfulness_result either way.

show_faithfulness_levelbool, default True

Whether to show the “Faithfulness Level” annotation box.

show_summarybool, default True

Whether to show the summary box with AUC and metric info.

show_level_intervalsbool, default True

Whether to show the “Level intervals” legend box.

return_dfbool, default False

If True, return the masking-curve DataFrame.

Returns

pd.DataFrame or None

Masking-curve DataFrame when return_df is True.