smx.plotting.summary ==================== .. py:module:: smx.plotting.summary .. autoapi-nested-parse:: 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 --------- .. autoapisummary:: smx.plotting.summary.plot_lrc_bar smx.plotting.summary.plot_predicate_heatmap smx.plotting.summary.plot_zone_scores smx.plotting.summary.plot_all_thresholds_overlay smx.plotting.summary.plot_faithfulness_curve Module Contents --------------- .. py:function:: plot_lrc_bar(zone_ranking_df: pandas.DataFrame, output_path: Optional[Union[str, pathlib.Path]], *, title: Optional[str] = None, colorscale: Optional[str] = None, theme: Optional[smx.plotting.theme.SMXTheme] = None, width: int = 800, height: int = 500, return_df: bool = False) -> Union[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 :func:`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_df : pd.DataFrame LRC table (``Zone`` / ``Local_Reaching_Centrality`` columns) or a pre-normalized ``zone`` / ``score`` / ``rank`` DataFrame. output_path : str or Path, optional Destination file. If ``None``, no file is written. title : str, optional Figure title. colorscale : str, optional Plotly colorscale name. Defaults to ``theme.colorscale``. theme : SMXTheme, optional Visual theme. Defaults to :data:`~smx.plotting.theme.DEFAULT_THEME`. width : int, default 800 Figure width in pixels (static export only). height : int, default 500 Figure height in pixels (static export only). return_df : bool, default False If ``True``, return the normalized ranking DataFrame. Returns ------- pd.DataFrame or None Normalized ``zone / score / rank`` DataFrame when *return_df* is True. .. py:function:: plot_predicate_heatmap(lrc_natural_df: pandas.DataFrame, output_path: Optional[Union[str, pathlib.Path]], *, title: Optional[str] = None, colorscale: Optional[str] = None, theme: Optional[smx.plotting.theme.SMXTheme] = None, width: int = 1000, height: int = 550, return_df: bool = False) -> Union[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_df : pd.DataFrame ``smx.lrc_natural_`` — must contain ``Zone``, ``Operator``, ``Threshold_Natural``, and ``Local_Reaching_Centrality`` columns. output_path : str or Path, optional Destination file. If ``None``, no file is written. title : str, optional Figure title. colorscale : str, optional Plotly colorscale name. Defaults to ``theme.colorscale``. theme : SMXTheme, optional Visual theme. width : int, default 1000 Figure width (static export). height : int, default 550 Figure height (static export). return_df : bool, 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. .. py:function:: plot_zone_scores(zones: Union[pandas.DataFrame, Dict[str, pandas.DataFrame]], y_labels: pandas.Series, output_path: Optional[Union[str, pathlib.Path]], spectral_cuts: Optional[Iterable] = None, *, title: Optional[str] = None, class_colors: Optional[Dict[str, str]] = None, theme: Optional[smx.plotting.theme.SMXTheme] = None, width: int = 1200, height: int = 580, return_df: bool = False) -> Union[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 ---------- zones : pd.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_labels : pd.Series Class labels aligned row-wise with *zones*. output_path : str or Path, optional Destination file. If ``None``, no file is written. spectral_cuts : iterable, optional Zone boundary definitions. Required when *zones* is a DataFrame. title : str, optional Figure title. class_colors : dict[str, str], optional Per-class hex/CSS colors. Defaults to ``theme.class_colors``. theme : SMXTheme, optional Visual theme. width : int, default 1200 Figure width (static export). height : int, default 580 Figure height (static export). return_df : bool, 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. .. py:function:: 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: Optional[Union[str, pathlib.Path]], *, title: Optional[str] = None, class_colors: Optional[Dict[str, str]] = None, theme: Optional[smx.plotting.theme.SMXTheme] = None, width: int = 1200, height: int = 500, return_df: bool = False) -> Union[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_df : pd.DataFrame ``smx.lrc_natural_``. zones_natural : dict[str, pd.DataFrame] ``smx.zones_natural_``. pca_info_natural : dict ``smx.pca_info_natural_``. y_labels : pd.Series Class labels aligned row-wise with the calibration data. spectral_cuts : iterable Zone boundary definitions. output_path : str or Path, optional Destination file. If ``None``, no file is written. title : str, optional Figure title. class_colors : dict[str, str], optional Per-class hex/CSS colors. theme : SMXTheme, optional Visual theme. width : int, default 1200 Figure width (static export). height : int, default 500 Figure height (static export). return_df : bool, 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. .. py:function:: plot_faithfulness_curve(faithfulness_result: Dict, output_path: Optional[Union[str, pathlib.Path]], *, title: Optional[str] = None, theme: Optional[smx.plotting.theme.SMXTheme] = 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) -> Union[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_result : dict Output of :meth:`smx.pipeline.SMX.evaluate_faithfulness`. Must contain ``curve_df`` and is expected to include ``auc``, ``level``, ``null_percentile``, and related summary fields. output_path : str or Path, optional Destination file. If ``None``, no file is written. title : str, optional Figure title. theme : SMXTheme, optional Visual theme. width : int, default 1100 Figure width (static export). height : int, default 560 Figure height (static export). show_percentile : bool, default False Whether to include the random-baseline percentile in the summary box. The value remains available in ``faithfulness_result`` either way. show_faithfulness_level : bool, default True Whether to show the "Faithfulness Level" annotation box. show_summary : bool, default True Whether to show the summary box with AUC and metric info. show_level_intervals : bool, default True Whether to show the "Level intervals" legend box. return_df : bool, default False If ``True``, return the masking-curve DataFrame. Returns ------- pd.DataFrame or None Masking-curve DataFrame when *return_df* is True.