publiplots.MultiAxesLegendGroup

class publiplots.MultiAxesLegendGroup(anchor=None, collect=None, *, side='right', figure=None, orientation='auto', align='auto', axes=None, x_offset=None, y_offset=None, gap=2, column_spacing=5, vpad=None, max_width=None, inside=False, clear_anchor=True)[source]

Unified legend band across multiple axes.

All elements share a single mm-based layout anchored to the chosen side of anchor. Each element can be attached to a different axes (via ax= on add_* calls) for hit-testing and picking; its POSITION is always computed against the anchor’s chosen edge regardless of which axes owns the artist.

The group can be attached before or after the plot calls. Before is marginally more efficient — each plot sees the group, skips its own per-axis legend render, and stashes the entry for the group to collect. After is seamless: the group walks every axes on construction and removes per-axis legend artists whose titles match entries it will claim, then renders the shared legend and lets SubplotsAutoLayout shrink the per-column / per-row reservations to match. Inside legends for entries the group does NOT claim (different kind, or excluded via collect=) survive the eviction.

Parameters:

  • anchor (Axes, optional) – The axes whose chosen edge defines the origin for the shared band. When None (default), the group is figure-anchored: it spans the full subplot grid on the chosen side (e.g., side='right' anchors to the rightmost cells’ right edge and extends vertically across every row). Pass an explicit axes to pin the band to that single cell instead (axes-anchored).

  • side ({'right', 'bottom', 'left', 'top'}, default 'right') – Which edge of the anchor the band grows outward from. 'right' is the classic publiplots outside-right column.

  • figure (Figure, optional) – Figure to attach a figure-anchored group to. Defaults to plt.gcf(); only needed when no current figure exists.

  • collect (list or tuple of str, optional) – Names of entries to auto-collect from across the grid’s stashed LegendEntry objects. None (default) collects everything. A list filters and orders — e.g. collect=['treatment', 'dose'] renders only those two names, in that order.

  • axes (Axes or sequence of Axes, optional) – Scope collection to a subset of the figure’s axes. None (default) walks the full subplot grid. When set, the group collects stashed entries only from those axes and evicts per-axis legends only from those axes — letting multiple groups on the same figure render independent bands (e.g. a side='top' band for the top row and a side='right' band for the bottom row).

  • x_offset (float | None) – Same meaning as LegendBuilder — all in millimeters.

  • y_offset (float | None) – Same meaning as LegendBuilder — all in millimeters.

  • gap (float) – Same meaning as LegendBuilder — all in millimeters.

  • column_spacing (float) – Same meaning as LegendBuilder — all in millimeters.

  • vpad (float | None) – Same meaning as LegendBuilder — all in millimeters.

  • max_width (float | None) – Same meaning as LegendBuilder — all in millimeters.

__init__(anchor=None, collect=None, *, side='right', figure=None, orientation='auto', align='auto', axes=None, x_offset=None, y_offset=None, gap=2, column_spacing=5, vpad=None, max_width=None, inside=False, clear_anchor=True)[source]

Methods

__init__([anchor, collect, side, figure, ...])

add_colorbar([mappable, ax])

Add a colorbar to the shared band.

add_legend(handles[, label, ax])

Add a legend to the shared band.

claims(name)

True if the group will render an entry with this name.
claims(name)[source]

True if the group will render an entry with this name.

add_legend(handles, label='', *, ax=None, **kwargs)[source]

Add a legend to the shared band.

The artist is attached to ax (defaults to a sensible corner cell for figure-anchored groups, or the anchor for axes-anchored); position is always computed against the anchor’s chosen edge.

For inside-mode groups (inside=True on the factory), this method auto-injects inside=True + loc= derived from the group’s side / align so that manual handle-add calls (e.g. band.add_legend(..., ncol=2) after collect=[]) render through the same axes-relative path as the auto-collect branch. Explicit user kwargs win.

add_colorbar(mappable=None, *, ax=None, **kwargs)[source]

Add a colorbar to the shared band. See add_legend for ax semantics.