smx.plotting.zones ================== .. py:module:: smx.plotting.zones .. autoapi-nested-parse:: Plot zone-level ranking overlays on top of a reference spectrum. The main entry point, :func:`plot_zone_ranking_over_spectrum`, accepts either: * a precomputed ranking DataFrame with ``zone`` / ``score`` / ``rank`` columns * an SMX LRC table with ``Zone`` / ``Local_Reaching_Centrality`` columns and writes an HTML Plotly figure where each spectral zone is highlighted as a ranked band over the reference spectrum. Functions --------- .. autoapisummary:: smx.plotting.zones.plot_spectrum_with_zones smx.plotting.zones.plot_zone_ranking_over_spectrum Module Contents --------------- .. py:function:: plot_spectrum_with_zones(spectrum: Union[pandas.Series, pandas.DataFrame, numpy.ndarray], spectral_cuts: Iterable, identified_peaks: Optional[Iterable[int]] = None, identified_minima: Optional[Iterable[int]] = None, output_path: Optional[Union[str, pathlib.Path]] = None, *, title: Optional[str] = None, zone_color: str = 'rgb(173, 216, 230)', background_color: str = 'rgb(0, 34, 75)', width: Optional[int] = 1200, height: Optional[int] = 500, theme: Optional[smx.plotting.theme.SMXTheme] = None, return_df: bool = False) -> Union[None, pandas.DataFrame] Plot a spectrum with spectral zones highlighted in the background. The figure is always displayed; set *return_df=True* to return the normalized cuts DataFrame. Parameters ---------- spectrum : pandas.Series, pandas.DataFrame, or numpy.ndarray Spectrum values. If a DataFrame is provided, the first row is used. spectral_cuts : iterable Zone definitions as ``(label, start, end)`` tuples or dicts. identified_peaks : iterable of int, optional Indices of local maxima to mark on the plot. output_path : str or Path, optional Destination file for the plot (HTML or static image). If omitted, the figure is displayed inline. title : str, optional Plot title. zone_color : str, default "rgb(173, 216, 230)" Light blue fill color for spectral zones. background_color : str, default "rgb(211, 211, 211)" Light gray fill color for background zones. width : int, default 1200 Figure width in pixels for static image export. height : int, default 500 Figure height in pixels for static image export. theme : SMXTheme, optional Visual theme controlling fonts and line styles. return_df : bool, default False If ``True``, return the normalized cuts DataFrame. Returns ------- pd.DataFrame or None Normalized cuts DataFrame when *return_df* is True. .. py:function:: plot_zone_ranking_over_spectrum(zone_ranking_df: pandas.DataFrame, spectral_cuts: Iterable, reference_spectrum: Union[pandas.Series, pandas.DataFrame, Dict[str, pandas.DataFrame]], output_path: Optional[Union[str, pathlib.Path]], *, aggregation: str = 'mean', title: Optional[str] = None, spectrum_name: str = 'Reference spectrum', colorscale: str = 'YlOrRd', annotation_y: float = 1.06, class_spectra: Optional[Dict[str, Union[pandas.Series, pandas.DataFrame, Dict[str, pandas.DataFrame]]]] = None, class_colors: Optional[Dict[str, str]] = None, width: Optional[int] = 1200, height: Optional[int] = 500, theme: Optional[smx.plotting.theme.SMXTheme] = None, return_df: bool = False) -> Union[None, pandas.DataFrame] Save a plot showing ranked zones overlaid on a spectrum. The figure is always displayed; set *return_df=True* to return the normalized ranking DataFrame. The output format is inferred from *output_path*: * ``.html`` — interactive Plotly figure (default, no extra dependency) * ``.png``, ``.svg``, ``.pdf``, ``.jpg`` — static image via ``kaleido`` (install with ``pip install kaleido``) Parameters ---------- zone_ranking_df : pd.DataFrame Either a ranking table with ``zone`` / ``score`` / ``rank`` columns or an SMX LRC table with ``Zone`` / ``Local_Reaching_Centrality``. spectral_cuts : iterable Zone definitions as accepted by :class:`smx.pipeline.SMX`. reference_spectrum : pd.Series, pd.DataFrame, or dict[str, pd.DataFrame] Spectrum used as the background line. If a DataFrame is provided, rows are aggregated with ``aggregation``. If a zone dictionary is provided, each zone is aggregated and stitched back together following ``spectral_cuts`` order. output_path : str or Path, optional Destination file. If ``None``, no file is written. aggregation : {'mean', 'median'}, default 'mean' Aggregation used when *reference_spectrum* is a DataFrame or zone dict. title : str, optional Figure title. spectrum_name : str, default 'Reference spectrum' Legend label for the background spectrum. colorscale : str, default 'YlOrRd' Plotly colorscale name used for zone bands. annotation_y : float, default 1.06 Annotation y-position in paper coordinates. class_spectra : dict[str, Series | DataFrame | dict[str, DataFrame]], optional Per-class spectra to overlay. Keys are class labels; values accept the same forms as *reference_spectrum*. Each class is plotted as a separate colored line using ``aggregation`` to collapse rows. class_colors : dict[str, str], optional Hex/CSS color strings keyed by class label. Missing labels fall back to a built-in palette. width : int, default 1200 Figure width in pixels. Used only for static image exports. height : int, default 500 Figure height in pixels. Used only for static image exports. theme : SMXTheme, optional Visual theme controlling colors, fonts, line styles, and the Plotly template. Defaults to :data:`smx.plotting.theme.DEFAULT_THEME`. Explicit style parameters (``colorscale``, ``class_colors``) take precedence over the theme. return_df : bool, default False If ``True``, return the normalized ranking DataFrame. Returns ------- pd.DataFrame or None Normalized ranking DataFrame when *return_df* is True. Notes ----- A vertical colorbar is rendered on the right side of the figure showing the LRC-score-to-color mapping. Its palette is pre-blended with the plot background so it matches the zone band colors exactly. Tick marks are placed at ``score_min`` and ``score_max`` and labeled accordingly. Returns ------- pd.DataFrame Normalized ranking DataFrame used in the plot.