Matplotlib 3.9.0 中的新功能 (2024 年 5 月 15 日)

有关自上次修订以来所有问题和拉取请求的列表，请参阅 3.10.0 (2024 年 12 月 13 日) 的 GitHub 统计数据。

绘图和注释改进

Axes.inset_axes 不再是实验性的

Axes.inset_axes 被认为是稳定可用的。

箱线图的图例支持

箱线图现在支持 label 参数来创建图例条目。图例标签可以作为字符串列表传递，以标记单个 Axes.boxplot 调用中的多个框

np.random.seed(19680801)
fruit_weights = [
    np.random.normal(130, 10, size=100),
    np.random.normal(125, 20, size=100),
    np.random.normal(120, 30, size=100),
]
labels = ['peaches', 'oranges', 'tomatoes']
colors = ['peachpuff', 'orange', 'tomato']

fig, ax = plt.subplots()
ax.set_ylabel('fruit weight (g)')

bplot = ax.boxplot(fruit_weights,
                   patch_artist=True,  # fill with color
                   label=labels)

# fill with colors
for patch, color in zip(bplot['boxes'], colors):
    patch.set_facecolor(color)

ax.set_xticks([])
ax.legend()

(源代码, 2x.png, png)

或者作为单个字符串传递给每个单独的 Axes.boxplot

fig, ax = plt.subplots()

data_A = np.random.random((100, 3))
data_B = np.random.random((100, 3)) + 0.2
pos = np.arange(3)

ax.boxplot(data_A, positions=pos - 0.2, patch_artist=True, label='Box A',
           boxprops={'facecolor': 'steelblue'})
ax.boxplot(data_B, positions=pos + 0.2, patch_artist=True, label='Box B',
           boxprops={'facecolor': 'lightblue'})

ax.legend()

(源代码, 2x.png, png)

饼图标签中的百分号在使用 usetex=True 时自动转义

在使用 Axes.pie 时，通常会指定包含百分号 (%) 的标签，在 LaTeX 中这表示注释。当通过 rcParams["text.usetex"] (默认值: False) 启用 LaTeX 或传递 textprops={"usetex": True} 时，会导致百分号消失。

现在，百分号会自动转义（通过添加前导反斜杠），以便无论 usetex 设置如何都会显示。如果您预先转义了百分号，则会检测到并保持原样。

stackplot 的 hatch 参数

stackplot 的 *hatch* 参数现在接受一个字符串列表，描述将按顺序应用于堆栈中的层的阴影样式

fig, (ax1, ax2) = plt.subplots(ncols=2, figsize=(10,5))

cols = 10
rows = 4
data = (
np.reshape(np.arange(0, cols, 1), (1, -1)) ** 2
+ np.reshape(np.arange(0, rows), (-1, 1))
+ np.random.random((rows, cols))*5
)
x = range(data.shape[1])
ax1.stackplot(x, data, hatch="x")
ax2.stackplot(x, data, hatch=["//","\\","x","o"])

ax1.set_title("hatch='x'")
ax2.set_title("hatch=['//','\\\\','x','o']")

plt.show()

(源代码, 2x.png, png)

添加仅绘制小提琴图一半的选项

将参数 *side* 设置为 'low' 或 'high' 可以只绘制 Axes.violinplot 的一半。

# Fake data with reproducible random state.
np.random.seed(19680801)
data = np.random.normal(0, 8, size=100)

fig, ax = plt.subplots()

ax.violinplot(data, [0], showmeans=True, showextrema=True)
ax.violinplot(data, [1], showmeans=True, showextrema=True, side='low')
ax.violinplot(data, [2], showmeans=True, showextrema=True, side='high')

ax.set_title('Violin Sides Example')
ax.set_xticks([0, 1, 2], ['Default', 'side="low"', 'side="high"'])
ax.set_yticklabels([])

(源代码, 2x.png, png)

极坐标轴上的 axhline 和 axhspan

...现在绘制圆形和圆弧 (axhline) 或环形和扇形 (axhspan)。

fig = plt.figure()
ax = fig.add_subplot(projection="polar")
ax.set_rlim(0, 1.2)

ax.axhline(1, c="C0", alpha=.5)
ax.axhspan(.8, .9, fc="C1", alpha=.5)
ax.axhspan(.6, .7, .8, .9, fc="C2", alpha=.5)

(源代码, 2x.png, png)

子图标题现在可以自动对齐

如果刻度标签或 x 轴标签放置在某个子图的顶部，则子图轴标题可能会垂直不对齐。现在，Figure 类上的新 align_titles 方法将垂直对齐标题。

fig, axs = plt.subplots(1, 2, layout='constrained')

axs[0].plot(np.arange(0, 1e6, 1000))
axs[0].set_title('Title 0')
axs[0].set_xlabel('XLabel 0')

axs[1].plot(np.arange(1, 0, -0.1) * 2000, np.arange(1, 0, -0.1))
axs[1].set_title('Title 1')
axs[1].set_xlabel('XLabel 1')
axs[1].xaxis.tick_top()
axs[1].tick_params(axis='x', rotation=55)

(源代码, 2x.png, png)

fig, axs = plt.subplots(1, 2, layout='constrained')

axs[0].plot(np.arange(0, 1e6, 1000))
axs[0].set_title('Title 0')
axs[0].set_xlabel('XLabel 0')

axs[1].plot(np.arange(1, 0, -0.1) * 2000, np.arange(1, 0, -0.1))
axs[1].set_title('Title 1')
axs[1].set_xlabel('XLabel 1')
axs[1].xaxis.tick_top()
axs[1].tick_params(axis='x', rotation=55)

fig.align_labels()
fig.align_titles()

(源代码, 2x.png, png)

axisartist 现在可以与标准 Formatters 一起使用

...而不是仅限于特定于 axisartist 的格式化器。

切换轴上的次刻度

可以使用 minorticks_on 和 minorticks_off 来显示或移除 Axis 上的次刻度；例如，ax.xaxis.minorticks_on()。另请参阅 minorticks_on。

StrMethodFormatter 现在遵循 axes.unicode_minus

在格式化负值时，如果设置了 rcParams["axes.unicode_minus"] (默认值: True)，StrMethodFormatter 现在将使用 Unicode 负号。

>>> from matplotlib.ticker import StrMethodFormatter
>>> with plt.rc_context({'axes.unicode_minus': False}):
...     formatter = StrMethodFormatter('{x}')
...     print(formatter.format_data(-10))
-10

>>> with plt.rc_context({'axes.unicode_minus': True}):
...     formatter = StrMethodFormatter('{x}')
...     print(formatter.format_data(-10))
−10

图形、轴和图例布局

子图现在具有可控的 zorder

以前，设置子图的 zorder 没有效果，并且这些子图绘制在任何图形级艺术家之上（例如，在图形级图例之上）。现在，子图的行为与其他任何艺术家一样，它们的 zorder 可以控制，默认 zorder 为 0。

x = np.linspace(1, 10, 10)
y1, y2 = x, -x
fig = plt.figure(constrained_layout=True)
subfigs = fig.subfigures(nrows=1, ncols=2)
for subfig in subfigs:
    axarr = subfig.subplots(2, 1)
    for ax in axarr.flatten():
        (l1,) = ax.plot(x, y1, label="line1")
        (l2,) = ax.plot(x, y2, label="line2")
subfigs[0].set_zorder(6)
l = fig.legend(handles=[l1, l2], loc="upper center", ncol=2)

(源代码, 2x.png, png)

获取 xmargin、ymargin 和 zmargin 的方法

添加了 Axes.get_xmargin、Axes.get_ymargin 和 Axes3D.get_zmargin 方法，分别返回通过 Axes.set_xmargin、Axes.set_ymargin 和 Axes3D.set_zmargin 设置的边距值。

Mathtext 改进

mathtext 文档改进

文档已更新，可直接从解析器获取信息。这意味着（几乎）所有受支持的符号、运算符等都会在 编写数学表达式 中显示。

mathtext 间距更正

由于文档更新，一些关系和运算符符号的间距已正确分类，因此将正确地设置间距。

小部件改进

复选框和单选按钮小部件支持清除

CheckButtons 和 RadioButtons 小部件现在支持通过调用其 .clear 方法来清除其状态。请注意，不可能不选择任何单选按钮，因此在构造时选择的选项将被选中。

3D绘图改进

设置3D轴的限制现在可以精确地设置限制

以前，设置3D轴的限制总是会在限制上添加一个小的边距。现在，默认情况下精确设置限制。新引入的 rcparam axes3d.automargin 可用于恢复到旧的行为，即自动添加边距。

fig, axs = plt.subplots(1, 2, subplot_kw={'projection': '3d'})

plt.rcParams['axes3d.automargin'] = True
axs[0].set(xlim=(0, 1), ylim=(0, 1), zlim=(0, 1), title='Old Behavior')

plt.rcParams['axes3d.automargin'] = False  # the default in 3.9.0
axs[1].set(xlim=(0, 1), ylim=(0, 1), zlim=(0, 1), title='New Behavior')

(源代码, 2x.png, png)

其他改进

BackendRegistry

新的 BackendRegistry 类是可用后端的事实来源。单例实例是 matplotlib.backends.backend_registry。它在 Matplotlib 内部使用，也从 IPython 8.24.0 开始在 IPython（以及因此在 Jupyter）中使用。

后端有三个来源：内置（源代码位于 Matplotlib 存储库中）、显式 module://some.backend 语法（通过加载模块获取后端），或者通过入口点（外部包中的自注册后端）。

要获取所有已注册的后端列表，请使用

>>> from matplotlib.backends import backend_registry
>>> backend_registry.list_all()

为 EllipseCollection 添加 widths、heights 和 angles 设置器

现在可以在创建集合后更改 EllipseCollection 的 widths、heights 和 angles 值。

from matplotlib.collections import EllipseCollection

rng = np.random.default_rng(0)

widths = (2, )
heights = (3, )
angles = (45, )
offsets = rng.random((10, 2)) * 10

fig, ax = plt.subplots()

ec = EllipseCollection(
    widths=widths,
    heights=heights,
    angles=angles,
    offsets=offsets,
    units='x',
    offset_transform=ax.transData,
    )

ax.add_collection(ec)
ax.set_xlim(-2, 12)
ax.set_ylim(-2, 12)

new_widths = rng.random((10, 2)) * 2
new_heights = rng.random((10, 2)) * 3
new_angles = rng.random((10, 2)) * 180

ec.set(widths=new_widths, heights=new_heights, angles=new_angles)

(源代码, 2x.png, png)

image.interpolation_stage rcParam

这个新的 rcParam 控制图像插值是在 “data” 空间还是在 “rgba” 空间中发生。

箭头补丁位置现在可修改

添加了一个设置器方法，允许更新 patches.Arrow 对象的位置，而无需完全重新绘制。

from matplotlib import animation
from matplotlib.patches import Arrow

fig, ax = plt.subplots()
ax.set_xlim(0, 10)
ax.set_ylim(0, 10)

a = Arrow(2, 0, 0, 10)
ax.add_patch(a)


# code for modifying the arrow
def update(i):
    a.set_data(x=.5, dx=i, dy=6, width=2)


ani = animation.FuncAnimation(fig, update, frames=15, interval=90, blit=False)

plt.show()

(源代码, 2x.png, png)

NonUniformImage 现在具有鼠标悬停支持

当鼠标悬停在 NonUniformImage 上时，现在会显示数据值。