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/

• Examples
• With multiple subplots, run adjust_text for one subplot at a time

Indices and tables

• Index

• Module Index

• Search Page

Module documentation

adjustText.adjust_text(texts, x=None, y=None, add_objects=None, ax=None, expand_text: float | tuple[float, float] = (1.05, 1.2), expand_points: float | tuple[float, float] = (1.05, 1.2), expand_objects: float | tuple[float, float] = (1.05, 1.2), expand_align: float | tuple[float, float] = (1.05, 1.2), autoalign='xy', va='center', ha='center', force_text: float | tuple[float, float] = (0.1, 0.25), force_points: float | tuple[float, float] = (0.2, 0.5), force_objects: float | tuple[float, float] = (0.1, 0.25), lim=500, precision=0.01, only_move={'objects': 'xy', 'points': 'xy', 'text': 'xy'}, avoid_text=True, avoid_points=True, avoid_self=True, save_steps=False, save_prefix='', save_format='png', add_step_numbers=True, *args, **kwargs)

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

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

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

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

• expand_points (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 points.

• expand_objects (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 other objects.

• expand_align (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 autoaligning texts.

• autoalign (str or boolean {'xy', 'x', 'y', True, False}, default 'xy') –

  Direction in wich the best alignement will be determined - ‘xy’ or True, best alignment of all texts determined in all

  directions automatically before running the iterative adjustment (overriding va and ha),

  • ’x’, will only align horizontally,

  • ’y’, will only align vertically,

  • False, do nothing (i.e. preserve va and ha)

• va (str, default 'center') – vertical alignment of texts

• ha (str, default 'center') – horizontal alignment of texts,

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

• force_points (tuple, default (0.2, 0.5)) – the repel force from points is multiplied by this value

• force_objects (float, default (0.1, 0.25)) – same as other forces, but for repelling additional objects

• lim (int, default 500) – limit of number of iterations

• precision (float, default 0.01) – iterate until the sum of all overlaps along both x and y are less than this amount, as a fraction of the total widths and heights, respectively. May need to increase for complicated situations.

• only_move (dict, default {'points':'xy', 'text':'xy', 'objects':'xy'}) – a dict to restrict movement of texts to only certain axes for certain types of overlaps. Valid keys are ‘points’, ‘text’, and ‘objects’. Valid values are ‘’, ‘x’, ‘y’, and ‘xy’. For example, only_move={‘points’:’y’, ‘text’:’xy’, ‘objects’:’xy’} forbids moving texts along the x axis due to overlaps with points.

• avoid_text (bool, default True) – whether to repel texts from each other.

• avoid_points (bool, default True) – whether to repel texts from points. Can be helpful to switch off in extremely crowded plots.

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

• save_steps (bool, default False) – whether to save intermediate steps as images.

• save_prefix (str, default '') – if save_steps is True, a path and/or prefix to the saved steps.

• save_format (str, default 'png') – if save_steps is True, a format to save the steps into.

• add_step_numbers (bool, default True) – if save_steps is True, whether to add step numbers as titles to the images of saving steps.

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

Returns:

Number of iteration

Return type:

int