publiplots.LegendBuilder

class publiplots.LegendBuilder(ax, x_offset=2, y_offset=None, gap=2, column_spacing=5, vpad=5, max_width=None)[source]

Publication-ready legend builder with automatic column overflow.

All dimensions are in millimeters for precise positioning in publication-quality plots. The builder automatically creates new columns when vertical space is exhausted.

This is the primary interface for creating legends in publiplots.

Parameters:

  • ax (Axes) – Main plot axes to attach legends to.

  • x_offset (float, default=2) – Horizontal distance from the right edge of axes (millimeters).

  • y_offset (float, optional) – Vertical position from top of axes (millimeters). If None, starts at axes height minus vpad.

  • gap (float, default=2) – Vertical spacing between legend elements (millimeters).

  • column_spacing (float, default=5) – Horizontal spacing between columns (millimeters).

  • vpad (float, default=5) – Padding from top of axes (millimeters).

  • max_width (float, optional) – Maximum width for legends (millimeters). If None, auto-estimated from content.

Examples

>>> fig, ax = pp.scatterplot(df, x='x', y='y', hue='group', legend=False)
>>> builder = pp.legend(ax, auto=False, x_offset=2, gap=2)
>>> builder.add_legend(handles, label="Treatment")
>>> builder.add_colorbar(mappable, label="Expression", height=15)

Notes

All dimensions are in millimeters. New columns are created automatically when vertical space is exhausted.

__init__(ax, x_offset=2, y_offset=None, gap=2, column_spacing=5, vpad=5, max_width=None)[source]

Initialize legend builder. All dimensions in millimeters.

Methods

__init__(ax[, x_offset, y_offset, gap, ...])

Initialize legend builder.

add_colorbar([mappable, cmap, vmin, vmax, ...])

Add a colorbar with automatic overflow handling.

add_legend(handles[, label, frameon, max_height])

Add a legend with automatic overflow handling.

add_legend_for(type[, label])

Add legend by auto-detecting from self.ax stored metadata.

get_remaining_height()

Get remaining vertical space.

Attributes

MM2INCH

PT2MM

MM2INCH = 0.03937007874015748
PT2MM = 0.35277777777777775
add_legend(handles, label='', frameon=False, max_height=None, **kwargs)[source]

Add a legend with automatic overflow handling.

Creates a new column automatically if the legend doesn’t fit in the current vertical space.

Parameters:

  • handles (list) – Legend handles (from create_legend_handles or plot objects).

  • label (str) – Legend title.

  • frameon (bool) – Whether to show frame around legend.

  • max_height (float, optional) – Maximum height in millimeters. If legend exceeds this, increase ncol to fit (PyComplexHeatmap behavior).

  • **kwargs – Additional kwargs for legend customization: - ncol: number of columns (auto-adjusted if max_height exceeded) - labelspacing: vertical space between entries - handletextpad: space between handle and text - columnspacing: space between columns (in font-size units)

Returns:

The created legend object.

Return type:

Legend

Notes

All dimensions in millimeters. Columns created automatically on overflow.

add_colorbar(mappable=None, cmap=None, vmin=None, vmax=None, center=None, label='', height=15, width=4.5, title_position='top', orientation='vertical', ticks=None, **kwargs)[source]

Add a colorbar with automatic overflow handling.

Supports both ScalarMappable input (standard matplotlib) and direct colormap specification (PyComplexHeatmap style).

Parameters:

  • mappable (ScalarMappable, optional) – Existing ScalarMappable object (standard matplotlib usage).

  • cmap (str, optional) – Colormap name (alternative to mappable, PyComplexHeatmap style). If provided, creates ScalarMappable internally.

  • vmin (float, optional) – Value range for colormap (used with cmap parameter).

  • vmax (float, optional) – Value range for colormap (used with cmap parameter).

  • center (float, optional) – Center value for divergent colormaps. Uses TwoSlopeNorm for proper centering (e.g., 0 for red-white-blue).

  • label (str) – Colorbar label/title.

  • height (float, default=15) – Colorbar height in millimeters.

  • width (float, default=4.5) – Colorbar width in millimeters.

  • title_position ({'top', 'right'}, default='top') – Position of title. ‘top’ places label above colorbar (horizontal), ‘right’ uses matplotlib default (vertical).

  • orientation ({'vertical', 'horizontal'}, default='vertical') – Colorbar orientation.

  • ticks (list of float, optional) – Custom tick positions. If None and center is provided, automatically sets ticks at [vmin, center, vmax].

  • **kwargs – Additional kwargs passed to fig.colorbar().

Returns:

The created colorbar object.

Return type:

Colorbar

Notes

All dimensions in millimeters. Columns created automatically on overflow.

Examples

Standard matplotlib style: >>> builder.add_colorbar(sm, label=”Values”, height=20)

PyComplexHeatmap style with divergent colormap: >>> builder.add_colorbar( … cmap=’RdBu_r’, vmin=-2, vmax=2, center=0, … label=”Log2 FC”, ticks=[-2, 0, 2] … )

add_legend_for(type, label=None, **kwargs)[source]

Add legend by auto-detecting from self.ax stored metadata.

Parameters:

  • type (str) – Type of legend: ‘hue’, ‘size’, or ‘style’

  • label (str, optional) – Legend label (overrides default from metadata).

  • **kwargs (dict) – Additional customization passed to add_legend() or add_colorbar() (frameon, labelspacing, handletextpad, height, width, etc.)

Examples

>>> builder = pp.legend(ax, auto=False)
>>> builder.add_legend_for('hue', label='Groups')
>>> builder.add_legend_for('size', label='Magnitude')
>>> builder.add_legend_for('hue', label='Score')  # Works for colorbar too
get_remaining_height()[source]

Get remaining vertical space.