gsplot.label#

label(target, xlabel='', ylabel='', xlim=None, ylim=None, *, xscale='linear', yscale='linear', xticks=None, yticks=None, minor=True, xminor=None, yminor=None, pad=5, xpad=None, ypad=None, margin=None, xmargin=None, ymargin=None, top=None, bottom=None, left=None, right=None, direction=None, square=False, index=False, index_offset=None, index_xoffset=None, index_yoffset=None)#

Set publication labels and optional panel geometry on 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.

  • xlabel (str | Sequence[tuple[str, str] | tuple[str, str, Any, Any] | Sequence[Any]] | Mapping[Any, tuple[str, str] | tuple[str, str, Any, Any] | Sequence[Any]]) – Shared axis labels. xlabel may instead contain ordered or exact-key two- or four-field label records.

  • ylabel (str) – Shared axis labels. xlabel may instead contain ordered or exact-key two- or four-field label records.

  • xlim (tuple[float | str | None, float | str | None] | Sequence[float | str | None] | None) – Optional finite, unequal limits; inverted limits are preserved. Endpoints set to None or wildcard placeholders use automatic smart margins.

  • ylim (tuple[float | str | None, float | str | None] | Sequence[float | str | None] | None) – Optional finite, unequal limits; inverted limits are preserved. Endpoints set to None or wildcard placeholders use automatic smart margins.

  • xscale (Literal['linear', 'log', 'symlog', 'logit']) – Shared linear, log, symlog, or logit scales.

  • yscale (Literal['linear', 'log', 'symlog', 'logit']) – Shared linear, log, symlog, or logit scales.

  • xticks (Sequence[float] | None) – Optional shared finite tick locations.

  • yticks (Sequence[float] | None) – Optional shared finite tick locations.

  • minor (bool) – Minor-tick controls. Coordinate-specific None inherits minor.

  • xminor (bool | None) – Minor-tick controls. Coordinate-specific None inherits minor.

  • yminor (bool | None) – Minor-tick controls. Coordinate-specific None inherits minor.

  • pad (float) – Label padding in points. Coordinate-specific None inherits pad.

  • xpad (float | None) – Label padding in points. Coordinate-specific None inherits pad.

  • ypad (float | None) – Label padding in points. Coordinate-specific None inherits pad.

  • margin (float | tuple[float, float] | None) – Margin ratios for auto-determined limits (defaults to 0.05 / 5%). Coordinate-specific None inherits margin.

  • xmargin (float | None) – Margin ratios for auto-determined limits (defaults to 0.05 / 5%). Coordinate-specific None inherits margin.

  • ymargin (float | None) – Margin ratios for auto-determined limits (defaults to 0.05 / 5%). Coordinate-specific None inherits margin.

  • top (bool | None) – Optional boolean flags for edge tick and label visibility.

  • bottom (bool | None) – Optional boolean flags for edge tick and label visibility.

  • left (bool | None) – Optional boolean flags for edge tick and label visibility.

  • right (bool | None) – Optional boolean flags for edge tick and label visibility.

  • direction (Literal['in', 'out', 'inout'] | None) – Optional tick direction: "in", "out", or "inout".

  • square (bool) – Apply the same unit box aspect as square() when true.

  • index (bool | Literal['in', 'out']) – Add generated panel indexes outside, or at the selected in/out location.

  • index_offset (tuple[float, float] | float | None) – Optional point shift relative to baseline panel index placement. Accepts a scalar for equal shift in x/y or a 2-tuple (dx, dy) in points.

  • index_xoffset (float | None) – Optional direct point shift along the x-axis for panel indexes.

  • index_yoffset (float | None) – Optional direct point shift along the y-axis for panel indexes.

Returns:

The supplied Axes are changed in place.

Return type:

None

Raises:

LayoutError – If targets, records, domains, ticks, padding, or controls are invalid.

Notes

Every target and value is validated before mutation. The operation never executes a Figure layout engine, resizes a Figure, or inspects pyplot’s current Figure.

Examples

>>> import gsplot as gs
>>> figure, ax = gs.subplots()
>>> gs.line(ax, [0, 1], [0, 1])
[<matplotlib.lines.Line2D object ...>]
>>> gs.label(ax, "time", "signal", xlim=(0, 1), square=True)
>>> ax.get_xlabel()
'time'
>>> figure.clear()