Utilities¶

If you are creating with Multiplex, you may find these utility functions useful. These methods are generally applicable and useful to many different visualizations. Apart from saving you time and improving the quality of your code, these functions have been rigorously tested, so they are robust.

General Utilities¶

These utilities are very general: they are used in almost all visualization types, or re-usable in various scenarios.

util.get_bb(figure, axes, component, transform=None)¶

Get the bounding box of the given component.

The bounding box is a rectangular box that covers the component. It indicates the bounds of the component and it has many uses. For example, it can be used to align components, or to make sure that they do not overlap.

Parameters:	figure (`matplotlib.figure.Figure`) – The figure that the component occupies. This is used to get the figure renderer. axes (`matplotlib.axes.Axes`) – The axes (or subplot) where the component is plotted. component (object) – The component whose bounding box will be fetched. transform (None or `matplotlib.transforms.TransformNode`) – The bounding box transformation. If None is given, the data transformation is used.
Returns:	The bounding box of the component.
Return type:	`matplotlib.transforms.Bbox`

util.get_scatter_bb(figure, axes, component, transform)¶

Get the bounding box of the given scatter path component. This function assumes that the component is a matplotlib.collections.PathCollection with just one scatter point.

Parameters:	figure (`matplotlib.figure.Figure`) – The figure that the component occupies. This is used to get the figure renderer. axes (`matplotlib.axes.Axes`) – The axes (or subplot) where the component is plotted. component (matplotlib.collections.PathCollection) – The scatter path collection, whose bounding box will be fetched. transform (None or `matplotlib.transforms.TransformNode`) – The bounding box transformation. If None is given, the data transformation is used.
Returns:	The bounding box of the scatter path.
Return type:	`matplotlib.transforms.Bbox`

util.to_px(axes, bb, transform=None)¶

Convert the given bounding box to pixels based on the given transform.

Parameters:	axes (`matplotlib.axes.Axes`) – The axes (or subplot) where the component is plotted. bb (`matplotlib.transforms.Bbox`) – The bounding box of the component. transform (None or `matplotlib.transforms.TransformNode`) – The bounding box transformation. If None is given, the data transformation is used.
Returns:	A new bounding box with values as pixels.
Return type:	`matplotlib.transforms.Bbox`

util.overlapping(figure, axes, c1, c2, *args, **kwargs)¶

Check whether the given components overlap. To check whether the given components overlap, the function extracts their bounding boxes and calls the overlapping_bb() function.

If a complex component, such as an Annotation, is given, it cannot extract its bounding box. In such cases, where possible extract the bounding box separately, perhaps by getting the virtual bounding box (get_virtual_bb()), and call the overlapping_bb() function directly.

Note

Since the overlap considers the rectangular bounding box, it is not perfectly precise.

Parameters:	figure (`matplotlib.figure.Figure`) – The figure that the component occupies. This is used to get the figure renderer. axes (`matplotlib.axes.Axes`) – The axes (or subplot) where the component is plotted. c1 (object) – The first component. Its bounding box will be compared to the second component. c2 (object) – The second component. Its bounding box will be compared to the first component.
Returns:	A boolean indicating whether the two components overlap.
Return type:	bool

util.overlapping_bb(bb1, bb2)¶

Check whether the two given bounding boxes overlap.

Parameters:	bb1 (`matplotlib.transforms.Bbox`) – The first bounding box. bb2 (`matplotlib.transforms.Bbox`) – The second bounding box.
Returns:	A boolean indicating whether the two bounding boxes overlap.
Return type:	bool

util.get_alignment(align, end=False)¶

Get the proper alignment value for the current line. This is mainly used for justification values.

Justified text justifies all lines except the last one. The last line is not full, therefore it is aligned differently: either left, center or right. This function extracts the proper alignment depending on whether this is the last line or not.

This function supports all the alignment options in the align function. If a simple alignment, such as left is given, it returns that value. This function only modifies the justify options.

Parameters:	align (str) – The provided alignment value. end (bool) – A boolean indicating whether this is the end of the group of items to be aligned. If it is the end line, alignments like justify-left transform into left. Otherwise, justify is returned.
Returns:	The alignment value for the current line.
Return type:	str

util.align(figure, axes, items, align='left', xpad=0, xlim=None, va='top', transform=None, *args, **kwargs)¶

Align the given objects horizontally around the given xlim.

Parameters:

figure (matplotlib.figure.Figure) – The figure that the component occupies. This is used to get the figure renderer.
axes (matplotlib.axes.Axes) – The axes (or subplot) where the component is plotted.
items (list of objcet) – The list of objects to organize.
align (str) –
The text’s alignment. Possible values:
- left
- center
- right
- justify
- justify-start (or justify-left)
- justify-center
- justify-end or (justify-right)
xpad (float) – The space between objects. Normally this depends on the wordspacing.
xlim (tuple) – The x-limit relative to which to align the objects. If it is not given, the axes’ x-limit is used instead. The x-limit is a tuple limiting the start and end.
va (str) – The vertical alignment, can be one of top or bottom. If the vertical alignment is bottom, the annotation grows up. If the vertical alignment is top, the annotation grows down.
transform (None or matplotlib.transforms.TransformNode) – The bounding box transformation. If None is given, the data transformation is used.

Raises:

ValueError

util.get_aspect(axes)¶

Get the aspect ratio of the axes. The calculation considers the display ratio as well as the data ratio.

Note

This solution is based on Mad Physicist’s answer on Stack Overflow.

Parameters:	axes (`matplotlib.axes.Axes`) – The axes whose aspect ratio will be calculated.
Returns:	The aspect ratio as a fraction of the display ratio and the data ratio.
Return type:	float

Text Utilities¶

The text utility functions are generally used only with text.

text_util.draw_token(figure, axes, text, x, y, style, wordspacing, *args, **kwargs)¶

Draw the token on the plot.

Use the kwargs as a general style, and the style as a specific style for each word. If you specify a kwargs styling option, but it is missing from the style, the general style is used.

Note

For example, imagine you specify the token color to be blue and the fontsize to be 12 in the **kwargs. If in the dictionary’s style of a particular word you set the color to be red, its color will be red. However, since the fontsize is not specified, it will use the general font size: 12.

Parameters:	figure (`matplotlib.figure.Figure`) – The figure that the component occupies. This is used to get the figure renderer. axes (`matplotlib.axes.Axes`) – The axes (or subplot) where the component is plotted. text (str) – The text token to draw. x (int) – The x-position of the token. y (int) – The y-position of the token. style (dict) – The style information for the token. This `dict` is used to override the styling options in the `kwargs`. wordspacing (float) – The space between words. This value is used to add padding around words (the whitespace).
Returns:	The drawn text box.
Return type:	`matplotlib.text.Text`

text_util.get_linespacing(figure, axes, wordspacing=0, transform=None, *args, **kwargs)¶

Calculate the line spacing (or line height) of text tokens. The line spacing is calculated by creating a token and getting its height. The token is immediately removed so it is not visible on the plot.

When calculating the line spacing, it is important to provide the style as args and kwargs. In this way, the line spacing considers the font, font size and other attributes that may affect the line spacing.

Parameters:	figure (`matplotlib.figure.Figure`) – The figure that the component occupies. This is used to get the figure renderer. axes (`matplotlib.axes.Axes`) – The axes (or subplot) where the component is plotted. wordspacing (float) – The spacing between tokens. This is used to be able to create the padding around words. transform (None or `matplotlib.transforms.TransformNode`) – The bounding box transformation. If None is given, the data transformation is used.
Returns:	The line spacing (or line height).
Return type:	float

text_util.get_wordspacing(figure, axes, transform=None, *args, **kwargs)¶

Calculate the word spacing of text tokens. The word spacing is given as half a sample character. The token is immediately removed so it is not visible on the plot.

When calculating the word spacing, it is important to provide the style as args and kwargs. In this way, the word spacing considers the font, font size and other attributes that may affect the word spacing.

Parameters:	figure (`matplotlib.figure.Figure`) – The figure that the component occupies. This is used to get the figure renderer. axes (`matplotlib.axes.Axes`) – The axes (or subplot) where the component is plotted. transform (None or `matplotlib.transforms.TransformNode`) – The bounding box transformation. If None is given, the data transformation is used.
Returns:	The word spacing.
Return type:	float