gsplot.cmap_legend#

cmap_legend(ax: Axes, *, cmap: str | Colormap = 'viridis', label: str | None = None, stripes: int = 8, norm: tuple[float, float] | _NormalizeProtocol | None = None, reverse: bool = False, replace: bool = False, props: Mapping[str, Any] | None = None, **kwargs: Any) → Legend#
cmap_legend(ax: Axes, *, cmap: str | Colormap | Sequence[str | Colormap] = 'viridis', label: str | Sequence[str] | None = None, stripes: int | Sequence[int] = 8, norm: tuple[float, float] | _NormalizeProtocol | None = None, reverse: bool | Sequence[bool] = False, replace: bool = False, props: Mapping[str, Any] | None = None, **kwargs: Any) → Legend

Create native Legend entries containing horizontal color gradients.

Parameters:
  • ax (Axes) – Explicit target Axes.

  • cmap (str | Colormap | Sequence[str | Colormap]) – Colormap name or native Colormap object, shared by every row or supplied once per row.

  • label (str | Sequence[str] | None) – Label for one gradient entry, or one label per row. None creates an empty native Legend and does not render a gradient.

  • stripes (int | Sequence[int]) – Positive requested stripe count, shared by every row or supplied once per row. Counts above 256 are clamped to 256 before sampling and rendering.

  • norm (tuple[float, float] | _NormalizeProtocol | None) – Optional normalizer shared by every row. It is applied to linspace(0, 1, N_effective) with clip=True. A pair is interpreted as (vmin, vmax) for a read-only Normalize operation; it is not a legacy raw-value alias.

  • reverse (bool | Sequence[bool]) – Reverse the final sampled RGBA sequence from left to right, shared by every row or supplied once per row.

  • replace (bool) – Reset to the requested entries only when explicitly set to True. Without it, a repeated labeled call appends its rows to the existing canonical colormap Legend in call order. Appended calls accept no legend properties.

  • props (Mapping[str, Any] | None) – Optional finite Matplotlib Legend constructor properties.

  • **kwargs (Any) – Optional direct Matplotlib Legend constructor properties. Direct keyword arguments are merged with and take precedence over props.

Returns:

The native local Legend.

Return type:

matplotlib.legend.Legend

Raises:

PlotError – If colormap, normalization, stripe count, target, replacement, or properties are invalid. Row sequences with different lengths, an empty row sequence, or row sequences combined with label=None raise LayoutError.

Notes

Each row adds one gradient entry with its own module-level local handler and proxy handle. It does not modify Matplotlib’s default handler map or add a colormap proxy to the Axes. Without replace, a repeated labeled call appends to the existing canonical colormap Legend: recorded entries keep their colors and order, recorded properties are preserved, and the combined Legend replaces the previous one transactionally. Presentation properties belong to the first call: passing props or keyword arguments on an appended call raises LayoutError. An existing foreign Legend, multiple existing Legends, an ordinary Legend created by legend, or label=None still raise LayoutError; write cmap_legend calls before legend, or use replace=True. With replace=True, any existing Legend is replaced transactionally. A repeated or merged Legend replaces the previous one, so previously returned Legend objects on that Axes are detached; measure and move only the newly returned object.

Examples

>>> import gsplot as gs
>>> figure, ax = gs.subplots()
>>> item = gs.cmap_legend(ax, label="intensity")
>>> item.axes is ax
True
>>> multi = gs.cmap_legend(
...     ax,
...     label=["4.7 K", "4.8 K"],
...     cmap=["viridis", "plasma"],
...     replace=True,
... )
>>> [text.get_text() for text in multi.get_texts()]
['4.7 K', '4.8 K']
>>> figure.clear()