Welcome to the documentation for adjustText!

adjustText is a small library to help you adjust text positions on matplotlib plots to remove or minimize overlaps with each other and data points. The approach is based on overlaps of bounding boxes and iteratively moving them to reduce overlaps. The idea is from the ggrepel package for R/ggplot2 (https://github.com/slowkow/ggrepel).

The repository with the issue tracker can be found here: https://github.com/Phlya/adjustText/

Module documentation

adjustText.adjust_text(texts, x=None, y=None, objects=None, target_x=None, target_y=None, avoid_self=True, force_text: tuple[float, float] = (0.1, 0.2), force_static: tuple[float, float] = (0.1, 0.2), force_pull: tuple[float, float] = (0.01, 0.01), force_explode: tuple[float, float] = (0.05, 0.05), pull_threshold: float = 10, expand: tuple[float, float] = (1.05, 1.2), explode_radius: str | float = 'auto', ensure_inside_axes: bool = True, expand_axes: bool = False, only_move: dict = {'explode': 'xy', 'pull': 'xy', 'static': 'xy', 'text': 'xy'}, ax: matplotlib.axes.Axes | None = None, min_arrow_len: float = 5, time_lim: float | None = None, iter_lim: int | None = None, *args, **kwargs)[source]

Iteratively adjusts the locations of texts.

Call adjust_text the very last, after all plotting (especially anything that can change the axes limits) has been done. This is because to move texts the function needs to use the dimensions of the axes, and without knowing the final size of the plots the results will be completely nonsensical, or suboptimal.

First “explodes” all texts to move them apart. Then in each iteration pushes all texts away from each other, and any specified points or objects. At the same time slowly tries to pull the texts closer to their origianal locations that they label (this reduces chances that a text ends up super far away). In the end adds arrows connecting the texts to the respective points.

Parameters:
  • texts (list) – A list of matplotlib.text.Text objects to adjust.

  • x (array_like) – x-coordinates of points to repel from; with avoid_self=True, the original text coordinates will be added to this array

  • y (array_like) – y-coordinates of points to repel from; with avoid_self=True, the original text coordinates will be added to this array

  • objects (list or PathCollection) – a list of additional matplotlib objects to avoid; they must have a .get_window_extent() method; alternatively, a PathCollection or a list of Bbox objects.

  • target_x (array_like) – if provided, x-coordinates of points to connect adjusted texts to; if not provided, uses the original text coordinates. Provide together with target_y. Should be the same length as texts and in the same order, or None.

  • target_y (array_like) – if provided, y-coordinates of points to connect adjusted texts to; if not provided, uses the original text coordinates. Provide together with target_x. Should be the same length as texts and in the same order, or None.

  • avoid_self (bool, default True) – whether to repel texts from its original positions.

  • force_text (tuple, default (0.1, 0.2)) – the repel force from texts is multiplied by this value

  • force_static (tuple, default (0.1, 0.2)) – the repel force from points and objects is multiplied by this value

  • force_pull (tuple, default (0.1, 0.1)) – same as other forces, but for pulling texts back to original positions

  • force_explode (float, default (0.1, 0.2)) – same as other forces, but for the forced move of texts away from nearby texts and static positions before iterative adjustment

  • pull_threshold (float, default 10) – how close to the original position the text should be pulled (if it’s closer along one of the axes, don’t pull along it) - in display coordinates

  • expand (array_like, default (1.05, 1.2)) – a tuple/list/… with 2 multipliers (x, y) by which to expand the bounding box of texts when repelling them from each other.

  • explode_radius (float or "auto", default "auto") – how far to check for nearest objects to move the texts away in the beginning in display units, so on the order of 100 is the typical value. “auto” uses the mean size of the texts

  • ensure_inside_axes (bool, default True) – Whether to force texts to stay inside the axes

  • expand_axes (bool, default False) – Whether to expand the axes to fit all texts before adjusting there positions

  • only_move (dict, default {"text": "xy", "static": "xy", "explode": "xy", "pull": "xy"}) – a dict to restrict movement of texts to only certain axes for certain types of overlaps. Valid keys are ‘text’, ‘static’, ‘explode’ and ‘pull’. Can contain ‘x’, ‘y’, ‘x+’, ‘x-’, ‘y+’, ‘y-’, or combinations of one ‘x?’ and one ‘y?’. ‘x’ and ‘y’ mean that the text can move in that direction, ‘x+’ and ‘x-’ mean that the text can move in the positive or negative direction along the x axis, and similarly for ‘y+’ and ‘y-‘.

  • ax (matplotlib axes, default is current axes (plt.gca())) – ax object with the plot

  • min_arrow_len (float, default 5) – If the text is closer than this to the target point, don’t add an arrow (in display units)

  • time_lim (float, default None) – How much time to allow for the adjustments, in seconds. If both time_lim and iter_lim are set, faster will be used. If both are None, time_lim is set to 1 seconds.

  • iter_lim (int, default None) – How many iterations to allow for the adjustments. If both time_lim and iter_lim are set, faster will be used. If both are None, time_lim is set to 1 seconds.

  • kwargs (args and) – any arguments will be fed into obj:FancyArrowPatch after all the optimization is done just for plotting the connecting arrows if required.