Matplotlib - Transforms

Matplotlib - Understanding Transforms and Coordinate Systems

Matplotlib uses a transformation framework to map coordinates from one system to another. This is crucial for placing elements like text, annotations, or shapes accurately, regardless of zooming, panning, or resizing.

Understanding these coordinate systems allows precise control over element placement.

Primary Coordinate Systems

There are four main coordinate systems you’ll encounter:

Coordinate System	Transformation Object	Description
Data Coordinates	ax.transData	The coordinate system of the data being plotted. This is the default for most plotting functions (like ax.plot, ax.scatter) and also for ax.text and ax.annotate. Its limits are controlled by ax.set_xlim() and ax.set_ylim(). Positions change upon zooming/panning.
Axes Coordinates	ax.transAxes	The coordinate system of the Axes instance itself, relative to its bounding box. (0,0) is the bottom-left corner, and (1,1) is the top-right corner of the Axes. This is independent of data limits and very useful for placing text or elements at fixed positions within the plot area (e.g., always in the top-left corner).
Figure Coordinates	fig.transFigure	The coordinate system of the Figure instance. (0,0) is the bottom-left corner, and (1,1) is the top-right corner of the entire Figure canvas. This is useful for placing elements relative to the whole figure, like a figure title (fig.suptitle) or text outside specific Axes.
Display Coordinates	None or IdentityTransform()	The raw pixel coordinate system of the output device (screen, image file). (0,0) is the bottom-left pixel, and (width, height) in pixels is the top-right. This is rarely used directly for plotting but underlies the other systems.

Using Transforms

Many Matplotlib functions that involve positioning (like ax.text, ax.annotate, shape patches) accept a transform keyword argument. By setting this argument, you specify which coordinate system the provided x and y values belong to.

Example: Placing Text in Different Coordinate Systems

import matplotlib.pyplot as plt
import numpy as np

fig, ax = plt.subplots(figsize=(7, 5))

# Some dummy data
ax.plot([1, 2, 3, 4], [1, 4, 2, 3])
ax.set_xlim(0, 5)
ax.set_ylim(0, 5)
ax.set_title('Transform Examples')

# 1. Text in Data Coordinates (Default for ax.text)
ax.text(2, 3, 'Data Coords (2, 3)', color='blue')

# 2. Text in Axes Coordinates (Fixed position within the Axes)
ax.text(0.05, 0.95, 'Axes Coords (0.05, 0.95)\nTop-Left Corner',
        transform=ax.transAxes,
        fontsize=10, verticalalignment='top',
        bbox=dict(boxstyle='round', facecolor='wheat', alpha=0.5))

ax.text(0.5, 0.5, 'Axes Coords (0.5, 0.5)\nCenter',
        transform=ax.transAxes,
        fontsize=10, horizontalalignment='center', verticalalignment='center',
        bbox=dict(boxstyle='round', facecolor='lightblue', alpha=0.5))

# 3. Text in Figure Coordinates (Relative to the whole figure window)
fig.text(0.98, 0.02, 'Figure Coords (0.98, 0.02)\nBottom-Right Corner',
         transform=fig.transFigure,
         fontsize=10, horizontalalignment='right', verticalalignment='bottom',
         bbox=dict(boxstyle='round', facecolor='lightgrey', alpha=0.5))

plt.show()

In this example:

• The blue text is placed at (x=2, y=3) in the data’s coordinate system. If you zoomed in, its position relative to the data would remain fixed, but its pixel position would change.
• The wheat-colored text is placed near the top-left corner of the Axes using ax.transAxes. It will stay in the top-left corner even if you pan or zoom the data.
• The light blue text is placed exactly in the center of the Axes using ax.transAxes.
• The grey text is placed near the bottom-right corner of the Figure window using fig.transFigure. Its position is independent of the Axes.

Understanding and utilizing these transforms provides powerful control for creating well-annotated and precisely laid out figures.