align_text#

align_text(ax, labels: Sequence[Text] | None = None, *, renderer=None, pad: float = 2.0, avoid_points: bool = True, avoid: Iterable = (), only_move: str = 'xy', max_iter: int = 60, spring: float = 0.05, step: float = 0.6, clip: bool = True, arrows: bool | dict = False, min_arrow_dist: float = 8.0) → list[source]#

Nudge text objects until they no longer overlap each other or the data.

Parameters:

  • ax (ultraplot.axes.Axes) – The axes whose labels are aligned.

  • labels (sequence of Text, optional) – The labels to move. Default is every text registered for alignment on the axes (see text with avoid_overlap=True).

  • pad (float, default: 2.0) – Padding in points added around every label bounding box.

  • avoid_points (bool, default: True) – Whether labels also repel the data points of lines and scatter plots.

  • avoid (sequence of Artist, optional) – Additional artists (a legend, an inset, …) whose bounding boxes the labels must stay clear of.

  • only_move ({'xy', 'x', 'y'}, default: 'xy') – Restrict movement to a single axis. Useful when the horizontal position of a label is meaningful, e.g. labels on a time series.

  • max_iter (int, default: 60) – Maximum number of relaxation iterations.

  • spring (float, default: 0.05) – Strength of the pull back towards the original anchor. Larger values keep labels closer to where they were placed at the cost of overlap.

  • step (float, default: 0.6) – Damping applied to each iteration’s displacement.

  • clip (bool, default: True) – Whether to keep labels inside the axes.

  • arrows (bool or dict, default: False) – Whether to draw a connector from displaced labels back to their anchor. A dict is passed to FancyArrowPatch.

  • min_arrow_dist (float, default: 8.0) – Only draw connectors for labels displaced further than this (in points).

Returns:

list – The connector patches that were drawn, if any.