Matplotlib 3.3.0 (2020 年 7 月 16 日) 的新特性 #

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

图形和轴的创建/管理 #

用于从文本或嵌套列表组合语义轴布局的临时 API #

Figure 类有一个临时方法，可以基于嵌套列表输入或 ASCII 艺术生成命名 axes.Axes 的复杂网格

axd = plt.figure(constrained_layout=True).subplot_mosaic(
    [['.', 'histx'],
     ['histy', 'scat']]
)
for k, ax in axd.items():
    ax.text(0.5, 0.5, k,
            ha='center', va='center', fontsize=36,
            color='darkgrey')

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

或作为字符串（带有单字符轴标签）

axd = plt.figure(constrained_layout=True).subplot_mosaic(
    """
    TTE
    L.E
    """)
for k, ax in axd.items():
    ax.text(0.5, 0.5, k,
            ha='center', va='center', fontsize=36,
            color='darkgrey')

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

有关更多详细信息和示例，请参阅复杂和语义图形组合 (subplot_mosaic)。

`GridSpec.subplots()`#

GridSpec 类获得了一个 subplots 方法，因此可以编写

fig.add_gridspec(2, 2, height_ratios=[3, 1]).subplots()

作为一种替代方案

fig.subplots(2, 2, gridspec_kw={"height_ratios": [3, 1]})

新的 `Axes.sharex`、`Axes.sharey` 方法 #

这些新方法允许在创建轴之后立即共享它们。请注意，如果轴不是在创建后立即共享，则行为是不确定的。

例如，它们可以用于选择性地链接使用 subplot_mosaic 一起创建的一些轴

fig = plt.figure(constrained_layout=True)
axd = fig.subplot_mosaic([['.', 'histx'], ['histy', 'scat']],
                         gridspec_kw={'width_ratios': [1, 7],
                                      'height_ratios': [2, 7]})

axd['histx'].sharex(axd['scat'])
axd['histy'].sharey(axd['scat'])

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

tight_layout 现在支持 suptitle #

以前的版本没有考虑 Figure.suptitle，因此在调用 tight_layout 后，它可能会与其他艺术家重叠

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

从现在开始，将考虑 suptitle

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

设置轴框的纵横比 #

现在可以使用 set_box_aspect 直接设置轴框的纵横比。框的纵横比是轴的高度与轴的宽度在物理单位中的比率，与数据限制无关。这对于例如生成一个与其中包含的数据无关的方形图，或在具有固定（数据）纵横比的图像图旁边具有相同轴尺寸的非图像图很有用。

有关用例，请查看轴框纵横比示例。

颜色和颜色图 #

Turbo 颜色图 #

Turbo 是一种改进的彩虹颜色图，用于可视化，由 Google AI 团队为计算机视觉和机器学习创建。其目的是显示深度和视差数据。有关更多详细信息，请参阅 Google AI 博客。

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

`colors.BoundaryNorm` 支持 extend 关键字参数 #

BoundaryNorm 现在有一个 extend 关键字参数，类似于 contourf 中的 extend。当设置为“both”、“min”或“max”时，它会将相应的超出范围的值映射到 Colormap 查找表索引，这些索引位于其范围的适当端附近，以便超出范围的值的颜色与其范围内相邻值的颜色相邻，但不同。颜色栏从范数继承 extend 参数，因此例如，使用 extend='both'，颜色栏将具有用于超出范围值的三角形扩展，其颜色与相邻的范围内颜色不同。

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

图例标签的文本颜色 #

现在可以通过将参数 labelcolor 传递给 legend 来设置图例标签的文本颜色。labelcolor 关键字可以是：

单个颜色（字符串或 RGBA 元组），用于调整所有标签的文本颜色。
列表或元组，允许单独设置每个标签的文本颜色。
linecolor，用于将每个标签的文本颜色设置为与相应的线条颜色匹配。
markerfacecolor，用于将每个标签的文本颜色设置为与相应的标记面颜色匹配。
markeredgecolor，它将每个标签的文本颜色设置为与相应的标记边缘颜色匹配。

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

Pcolor 和 Pcolormesh 现在接受 `shading='nearest'` 和 `'auto'`#

以前，axes.Axes.pcolor 和 axes.Axes.pcolormesh 通过删除 C 的最后一行和最后一列来处理 x 和 y 与 C 具有相同（各自）大小的情况，并且 x 和 y 被视为 C 中剩余行和列的边缘。但是，许多用户希望 x 和 y 位于 C 的行和列的中心。

为了适应这一点，shading='nearest' 和 shading='auto' 是 shading 关键字参数的新允许字符串。如果 x 和 y 与 C 具有相同的维度，则 'nearest' 将把颜色居中于 x 和 y （否则将抛出错误）。 shading='auto' 将根据 X、Y、C 的大小选择 'flat' 或 'nearest'。

如果 shading='flat'，则 X 和 Y 的维度应比 C 大 1。如果 X 和 Y 与 C 具有相同的维度，则使用之前的行为，并删除 C 的最后一行和最后一列，并发出 DeprecationWarning。

用户还可以通过新的 rcParams["pcolor.shading"] （默认值：'auto'）在其 .matplotlibrc 中或通过 rcParams 来指定此行为。

有关示例，请参见 pcolormesh。

标题、刻度和标签 #

将标签与轴边缘对齐 #

set_xlabel、set_ylabel 和 ColorbarBase.set_label 支持一个用于简化定位的参数 loc。对于 xlabel，支持的值为“left”、“center”或“right”。对于 ylabel，支持的值为“bottom”、“center”或“top”。

默认值由 rcParams["xaxis.labellocation"] （默认值：'center'）和 rcParams["yaxis.labellocation"] （默认值：'center'）控制；Colorbar 标签采用基于其方向的 rcParam。

(源代码)

(2x.png, png)

(2x.png, png)

允许使用字符串或函数输入设置刻度格式化程序 #

set_major_formatter 和 set_minor_formatter 现在除了接受 Formatter 实例之外，还接受 str 或函数输入。对于 str，会自动生成并使用 StrMethodFormatter。对于函数，会自动生成并使用 FuncFormatter。换句话说，

ax.xaxis.set_major_formatter('{x} km')
ax.xaxis.set_minor_formatter(lambda x, pos: str(x-5))

是以下代码的快捷方式

import matplotlib.ticker as mticker

ax.xaxis.set_major_formatter(mticker.StrMethodFormatter('{x} km'))
ax.xaxis.set_minor_formatter(
    mticker.FuncFormatter(lambda x, pos: str(x-5))

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

`Axes.set_title` 获得一个 y 关键字参数来控制自动定位 #

set_title 尝试自动定位标题，以避免顶部 x 轴上的任何装饰器。这并不总是理想的，因此现在 y 是 set_title 的一个显式关键字参数。它的默认值为 None，这意味着使用自动定位。如果提供了一个值（即 3.0 之前的默认值为 y=1.0），则会关闭自动定位。也可以使用新的 rc 参数 rcParams["axes.titley"] （默认值：None）设置此项。

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

使用 `axis.tick_top()` 时，偏移文本现在设置为顶部 #

解决了即使刻度线在顶部，幂指示符（例如，1e4）仍保留在底部的问题。

设置等高线标签的 zorder #

clabel 现在接受一个 zorder 关键字参数，使其更容易设置等高线标签的 zorder。如果未指定，clabel 的默认 zorder 总是 3（即 Text 的默认 zorder），而与传递给 contour/contourf 的 zorder 无关。clabel 的新默认 zorder 已更改为 (2 + 传递给 contour / contourf 的 zorder)。

其他更改 #

新的 `Axes.axline` 方法 #

添加了一个新的 axline 方法，用于绘制穿过两个点的无限长直线。

fig, ax = plt.subplots()

ax.axline((.1, .1), slope=5, color='C0', label='by slope')
ax.axline((.1, .2), (.8, .7), color='C3', label='by points')

ax.legend()

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

`imshow` 现在将深度为 1 的 3D 数组强制转换为 2D #

从这个版本开始，大小为 MxNx1 的数组将被强制转换为 MxN 进行显示。这意味着像 plt.imshow(np.random.rand(3, 3, 1)) 这样的命令将不再返回图像形状无效的错误消息。

更好地控制 `Axes.pie` 归一化 #

以前，如果 sum(x) > 1，Axes.pie 会对其输入 x 进行归一化，但如果总和小于 1，则不会执行任何操作。这可能会令人困惑，因此添加了一个显式的关键字参数 normalize。默认情况下，保留旧的行为。

通过传递 normalize，可以显式控制是否进行任何重新缩放，或者是否应创建部分饼图。如果禁用归一化，并且 sum(x) > 1，则会引发错误。

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

日期使用现代纪元 #

Matplotlib 使用 dates.date2num (通过 matplotlib.units) 将日期转换为自纪元以来的天数。以前，使用 0000-12-31T00:00:00 的纪元，以便将 0001-01-01 转换为 1.0。如此遥远的过去意味着现代日期无法保留微秒，因为 2000 年乘以 64 位浮点数的 2^(-52) 分辨率得出 14 微秒。

在这里，我们将默认纪元更改为更合理的 UNIX 默认值 1970-01-01T00:00:00，对于现代日期，其分辨率为 0.35 微秒。（无法实现更高的分辨率，因为我们依赖于 datetime.datetime 来进行日期定位）。通过 get_epoch 提供对纪元的访问，并且有一个新的 rcParams["date.epoch"] (默认值：'1970-01-01T00:00:00') rcParam。用户也可以调用 set_epoch，但它必须在任何日期转换或绘图之前设置。

如果您的数据以旧纪元的序数浮点数形式存储，则可以使用以下公式将其转换为新的序数

new_ordinal = old_ordinal + mdates.date2num(np.datetime64('0000-12-31'))

线条现在接受 `MarkerStyle` 实例作为输入 #

与 scatter 类似，plot 和 Line2D 现在接受 MarkerStyle 实例作为 marker 参数的输入

plt.plot(..., marker=matplotlib.markers.MarkerStyle("D"))

字体 #

通过绝对路径选择字体的简单语法 #

现在可以通过将绝对 pathlib.Path 传递给 Text 的 font 关键字参数来选择字体。

改进的字体粗细检测 #

Matplotlib 现在能够更好地从字体元数据中确定字体的粗细，从而更准确地区分同一系列中的字体。

rcParams 改进 #

`matplotlib.rc_context` 可以用作装饰器 #

matplotlib.rc_context 现在可以用作装饰器（从技术上讲，它现在实现为 contextlib.contextmanager），例如，

@rc_context({"lines.linewidth": 2})
def some_function(...):
    ...

用于控制默认“引发窗口”行为的 rcParams #

新的配置选项 rcParams["figure.raise_window"] (默认值：True) 允许在调用 show 或 pause 时禁用提升绘图窗口。MacOSX 后端目前不支持。

将广义的 `mathtext.fallback` 添加到 rcParams #

新的 rcParams["mathtext.fallback"] (默认值：'cm') rcParam。接受“cm”、“stix”、“stixsans”或“none”以关闭回退。rcParam mathtext.fallback_to_cm 已弃用，但如果使用，将覆盖新的回退。

将 `contour.linewidth` 添加到 rcParams #

新的配置选项 rcParams["contour.linewidth"] (默认值：None) 允许将等高线的默认线宽控制为浮点数。当设置为 None 时，线宽将回退到 rcParams["lines.linewidth"] (默认值：1.5)。当未设置为 None 时，该配置值像往常一样被传递给 contour 的 linewidths 参数覆盖。

3D 轴改进 #

`Axes3D` 不再扭曲 3D 图以匹配 2D 纵横比 #

先前使用 Axes3D 绘制的图表会被拉伸以适应正方形边界框。由于这种拉伸是在从 3D 到 2D 的投影之后进行的，如果使用非正方形边界框，则会导致图像失真。从 3.3 版本开始，这种情况不再发生。

目前，Axes3D 不支持在数据空间中设置纵横比的模式（通过 set_aspect），但未来可能会支持。如果您想模拟在数据空间中具有相等纵横比，请将您的数据限制的比率设置为与 get_box_aspect 的值匹配。要控制这些比率，请使用 set_box_aspect 方法，该方法接受 X:Y:Z 的 3 元组形式的比率。默认的纵横比为 4:4:3。

3D 轴现在支持次要刻度 #

ax = plt.figure().add_subplot(projection='3d')

ax.scatter([0, 1, 2], [1, 3, 5], [30, 50, 70])

ax.set_xticks([0.25, 0.75, 1.25, 1.75], minor=True)
ax.set_xticklabels(['a', 'b', 'c', 'd'], minor=True)

ax.set_yticks([1.5, 2.5, 3.5, 4.5], minor=True)
ax.set_yticklabels(['A', 'B', 'C', 'D'], minor=True)

ax.set_zticks([35, 45, 55, 65], minor=True)
ax.set_zticklabels([r'$\alpha$', r'$\beta$', r'$\delta$', r'$\gamma$'],
                   minor=True)

ax.tick_params(which='major', color='C0', labelcolor='C0', width=5)
ax.tick_params(which='minor', color='C1', labelcolor='C1', width=3)

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

“主页/前进/后退”按钮现在可以用于 3D 轴 #

交互式工具改进 #

光标文本现在使用与指向精度匹配的有效数字位数 #

以前，光标文本显示的 x/y 位置通常包含比鼠标指向精度（通常为一个像素）多得多的有效数字位数。现在，对于线性刻度，此问题已得到修复。

GTK / Qt 缩放矩形现在为黑色和白色 #

这使得即使在深色背景上也可以看到它。

事件处理程序简化 #

现在，可以将 backend_bases.key_press_handler 和 backend_bases.button_press_handler 事件处理程序直接连接到画布，方法是使用 canvas.mpl_connect("key_press_event", key_press_handler) 和 canvas.mpl_connect("button_press_event", button_press_handler)，而无需编写填充（现在可选的）canvas 和 toolbar 参数的包装函数。