Welcome to adjustText’s documentation!

Indices and tables

• Index
• Module Index
• Search Page

Module documentation

adjustText.adjustText.adjust_text(texts, x=None, y=None, add_objects=None, ax=None, expand_text=(1.2, 1.2), expand_points=(1.2, 1.2), expand_objects=(1.2, 1.2), expand_align=(0.9, 0.9), autoalign='xy', va='center', ha='center', force_text=(0.5, 1), force_points=(0.5, 1), force_objects=(0.5, 1), lim=100, precision=0.001, only_move={'objects': 'xy', 'points': 'xy', 'text': 'xy'}, text_from_text=True, text_from_points=True, save_steps=False, save_prefix='', save_format='png', add_step_numbers=True, draggable=True, on_basemap=False, *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.

Args:

texts (list): a list of text.Text objects to adjust x (seq): x-coordinates of points to repel from; if not provided only

uses text coordinates

y (seq): y-coordinates of points to repel from; if not provided only

uses text coordinates

add_objects (list): a list of additional matplotlib objects to avoid;

they must have a .get_window_extent() method

ax (obj): axes object with the plot; if not provided is determined by

plt.gca()

expand_text (seq): a tuple/list/… with 2 multipliers (x, y) by which

to expand the bounding box of texts when repelling them from each other; default (1.2, 1.2)

expand_points (seq): a tuple/list/… with 2 multipliers (x, y) by which

to expand the bounding box of texts when repelling them from points; default (1.2, 1.2)

expand_objects (seq): a tuple/list/… with 2 multipliers (x, y) by which

to expand the bounding box of texts when repelling them from other objects; default (1.2, 1.2)

expand_align (seq): a tuple/list/… with 2 multipliers (x, y) by which

to expand the bounding box of texts when autoaligning texts; default (0.9, 0.9)

autoalign: If ‘xy’, the best alignment of all texts will be

determined in all directions automatically before running the iterative adjustment (overriding va and ha); if ‘x’, will only align horizontally, if ‘y’, vertically; if False, do nothing (i.e. preserve va and ha); default ‘xy’

va (str): vertical alignment of texts; default ‘center’ ha (str): horizontal alignment of texts; default ‘center’ force_text (float): the repel force from texts is multiplied by this

value; default 0.5

force_points (float): the repel force from points is multiplied by this

value; default 0.5

force_objects (float): same as other forces, but for repelling

additional objects

lim (int): limit of number of iterations precision (float): 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; default 0.001

only_move (dict): a dict to restrict movement of texts to only certain

axis. Valid keys are ‘points’, ‘text’, and ‘objects’. For each of them valid values are ‘x’, ‘y’ and ‘xy’. This way you can forbid moving texts along either of the axes due to overlaps with points, but let it happen if there is an overlap with texts: only_move={‘points’:’y’, ‘text’:’xy’}. Default: everything is allowed.

text_from_text (bool): whether to repel texts from each other; default

True

text_from_points (bool): whether to repel texts from points; default

True; can be helpful to switch off in extremely crowded plots

save_steps (bool): whether to save intermediate steps as images;

default False

save_prefix (str): a path and/or prefix to the saved steps; default ‘’ save_format (str): a format to save the steps into; default ‘png add_step_numbers (bool): whether to add step numbers as titles to the

images of saving steps

draggable (bool): whether to make the annotations draggable; default

True

on_basemap (bool): whether your plot uses the basemap library, stops

labels going over the edge of the map; default False

*args and **kwargs: any arguments will be fed into plt.annotate after

all the optimization is done just for plotting

adjustText.adjustText.get_points_inside_bbox(x, y, bbox)

Return the indices of points inside the given bbox.

adjustText.adjustText.optimally_align_text(x, y, texts, expand=(1.0, 1.0), add_bboxes=[], renderer=None, ax=None, direction='xy')

For all text objects find alignment that causes the least overlap with points and other texts and apply it

adjustText.adjustText.overlap_bbox_and_point(bbox, xp, yp)

Given a bbox that contains a given point, return the (x, y) displacement necessary to make the bbox not overlap the point.

adjustText.adjustText.repel_text(texts, renderer=None, ax=None, expand=(1.2, 1.2), only_use_max_min=False, move=False)

Repel texts from each other while expanding their bounding boxes by expand (x, y), e.g. (1.2, 1.2) would multiply width and height by 1.2. Requires a renderer to get the actual sizes of the text, and to that end either one needs to be directly provided, or the axes have to be specified, and the renderer is then got from the axes object.

adjustText.adjustText.repel_text_from_bboxes(add_bboxes, texts, renderer=None, ax=None, expand=(1.2, 1.2), only_use_max_min=False, move=False)

Repel texts from other objects’ bboxes while expanding their (texts’) bounding boxes by expand (x, y), e.g. (1.2, 1.2) would multiply width and height by 1.2. Requires a renderer to get the actual sizes of the text, and to that end either one needs to be directly provided, or the axes have to be specified, and the renderer is then got from the axes object.

adjustText.adjustText.repel_text_from_points(x, y, texts, renderer=None, ax=None, expand=(1.2, 1.2), move=False)

Repel texts from all points specified by x and y while expanding their (texts’!) bounding boxes by expandby (x, y), e.g. (1.2, 1.2) would multiply both width and height by 1.2. Requires a renderer to get the actual sizes of the text, and to that end either one needs to be directly provided, or the axes have to be specified, and the renderer is then got from the axes object.