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, 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.01, 0.02), expand: tuple[float, float] = (1.05, 1.1), explode_radius='auto', ensure_inside_axes=True, expand_axes=False, only_move={'explode': 'xy', 'pull': 'xy', 'static': 'xy', 'text': 'xy'}, ax=None, min_arrow_len=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 moves all texts that are outside the axes limits inside. Then in each iteration moves all texts away from each other and from points. In the end hides texts and substitutes them with annotations to link them 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; if not provided only uses text coordinates.

  • y (array_like) – y-coordinates of points to repel from; if not provided only uses text coordinates

  • 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.

  • 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.01, 0.01)) – same as other forces, but for pulling texts back to original positions

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

  • expand (array_like, default (1.05, 1.1)) – 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 size of the largest text

  • 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’. Valid values are ‘’, ‘x’, ‘y’, and ‘xy’.

  • ax (matplotlib axe, default is current axe (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 0.5 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 0.5 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.