smx.plotting.zones#

Plot zone-level ranking overlays on top of a reference spectrum.

The main entry point, 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#

plot_spectrum_with_zones(→ Union[None, pandas.DataFrame])

Plot a spectrum with spectral zones highlighted in the background.

plot_zone_ranking_over_spectrum(→ Union[None, ...)

Save a plot showing ranked zones overlaid on a spectrum.

Module Contents#

smx.plotting.zones.plot_spectrum_with_zones(spectrum: pandas.Series | pandas.DataFrame | numpy.ndarray, spectral_cuts: Iterable, identified_peaks: Iterable[int] | None = None, identified_minima: Iterable[int] | None = None, output_path: str | pathlib.Path | None = None, *, title: str | None = None, zone_color: str = 'rgb(173, 216, 230)', background_color: str = 'rgb(0, 34, 75)', width: int | None = 1200, height: int | None = 500, theme: smx.plotting.theme.SMXTheme | None = None, return_df: bool = False) → None | pandas.DataFrame[source]#

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#

spectrumpandas.Series, pandas.DataFrame, or numpy.ndarray

Spectrum values. If a DataFrame is provided, the first row is used.

spectral_cutsiterable

Zone definitions as (label, start, end) tuples or dicts.

identified_peaksiterable of int, optional

Indices of local maxima to mark on the plot.

output_pathstr or Path, optional

Destination file for the plot (HTML or static image). If omitted, the figure is displayed inline.

titlestr, optional

Plot title.

zone_colorstr, default “rgb(173, 216, 230)”

Light blue fill color for spectral zones.

background_colorstr, default “rgb(211, 211, 211)”

Light gray fill color for background zones.

widthint, default 1200

Figure width in pixels for static image export.

heightint, default 500

Figure height in pixels for static image export.

themeSMXTheme, optional

Visual theme controlling fonts and line styles.

return_dfbool, default False

If True, return the normalized cuts DataFrame.

Returns#

pd.DataFrame or None

Normalized cuts DataFrame when return_df is True.

smx.plotting.zones.plot_zone_ranking_over_spectrum(zone_ranking_df: pandas.DataFrame, spectral_cuts: Iterable, reference_spectrum: pandas.Series | pandas.DataFrame | Dict[str, pandas.DataFrame], output_path: str | pathlib.Path | None, *, aggregation: str = 'mean', title: str | None = None, spectrum_name: str = 'Reference spectrum', colorscale: str = 'YlOrRd', annotation_y: float = 1.06, class_spectra: Dict[str, pandas.Series | pandas.DataFrame | Dict[str, pandas.DataFrame]] | None = None, class_colors: Dict[str, str] | None = None, width: int | None = 1200, height: int | None = 500, theme: smx.plotting.theme.SMXTheme | None = None, return_df: bool = False) → None | pandas.DataFrame[source]#

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_dfpd.DataFrame

Either a ranking table with zone / score / rank columns or an SMX LRC table with Zone / Local_Reaching_Centrality.

spectral_cutsiterable

Zone definitions as accepted by smx.pipeline.SMX.

reference_spectrumpd.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_pathstr 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.

titlestr, optional

Figure title.

spectrum_namestr, default ‘Reference spectrum’

Legend label for the background spectrum.

colorscalestr, default ‘YlOrRd’

Plotly colorscale name used for zone bands.

annotation_yfloat, default 1.06

Annotation y-position in paper coordinates.

class_spectradict[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_colorsdict[str, str], optional

Hex/CSS color strings keyed by class label. Missing labels fall back to a built-in palette.

widthint, default 1200

Figure width in pixels. Used only for static image exports.

heightint, default 500

Figure height in pixels. Used only for static image exports.

themeSMXTheme, optional

Visual theme controlling colors, fonts, line styles, and the Plotly template. Defaults to smx.plotting.theme.DEFAULT_THEME. Explicit style parameters (colorscale, class_colors) take precedence over the theme.

return_dfbool, 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.