gsplot.legend#

legend(target, *, handles=None, labels=None, handler_map=None, loc='best', frameon=False, fancybox=False, labelspacing=0.3, handlelength=None, reverse=False, replace=False, props=None, **kwargs)#

Create publication legends on one or more explicit Axes.

Parameters:

  • target (Axes | _AxesBase | Sequence[Axes | _AxesBase] | Mapping[Any, Axes | _AxesBase] | ndarray[tuple[int, ...], dtype[Any]]) – One Axes or a deterministic same-Figure collection of Axes.

  • handles (Sequence[Artist] | Mapping[object, Sequence[Artist]] | None) – Optional matched entries. Multi-target explicit entries require exact target-key mappings; otherwise Matplotlib discovery is used.

  • labels (Sequence[str] | Mapping[object, Sequence[str]] | None) – Optional matched entries. Multi-target explicit entries require exact target-key mappings; otherwise Matplotlib discovery is used.

  • handler_map (Mapping[object, HandlerBase] | None) – Optional local handler mapping; it never changes Matplotlib defaults.

  • loc (str | int) – Direct publication controls. Defaults are "best", False, False, 0.3, and None respectively.

  • frameon (bool) – Direct publication controls. Defaults are "best", False, False, 0.3, and None respectively.

  • fancybox (bool) – Direct publication controls. Defaults are "best", False, False, 0.3, and None respectively.

  • labelspacing (float) – Direct publication controls. Defaults are "best", False, False, 0.3, and None respectively.

  • handlelength (float | None) – Direct publication controls. Defaults are "best", False, False, 0.3, and None respectively.

  • reverse (bool) – Reverse each selected entry sequence before construction.

  • replace (bool) – Remove existing legends only when explicitly set to True.

  • props (Mapping[str, object] | None) – Finite Matplotlib Legend constructor properties.

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

Returns:

Native Legends in normalized target order. Collection targets skip Axes that have no discovered entries.

Return type:

matplotlib.legend.Legend or tuple of Legend

Raises:

LayoutError – If entries, controls, target, handlers, or properties are invalid.

Examples

>>> import gsplot as gs
>>> figure, ax = gs.subplots()
>>> gs.line(ax, [0, 1], [0, 1], props={"label": "signal"})
[<matplotlib.lines.Line2D object ...>]
>>> item = gs.legend(ax, handlelength=3)
>>> item.axes is ax
True
>>> figure.clear()