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

要查看自上次修订以来的所有问题和拉取请求，请参阅 GitHub 统计数据为 3.9.2 版本（2024年8月12日）。

图形和轴的创建 / 管理 #

用于从文本或嵌套列表组合语义轴布局的临时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')

(Source code, 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')

(Source code, 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'])

(Source code, 2x.png, png)

tight_layout 现在支持 suptitle #

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

(Source code, 2x.png, png)

从现在开始，将考虑 suptitle：

(Source code, 2x.png, png)

设置轴的方框比例 #

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

有关使用案例，请查看 Axes box aspect 示例。

颜色和颜色映射 #

Turbo 色图 #

Turbo 是一个用于可视化的改进型彩虹色图，由 Google AI 团队为计算机视觉和机器学习创建。它的目的是显示深度和视差数据。更多详情请参见 Google AI 博客。

(Source code, 2x.png, png)

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

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

(Source code, 2x.png, png)

图例标签的文本颜色 #

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

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

(Source code, 2x.png, png)

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

之前，axes.Axes.pcolor 和 axes.Axes.pcolormesh 处理 x 和 y 与 C 具有相同（各自）大小的情况时，通过丢弃 C 的最后一行和最后一列，并将 x 和 y 视为 C 中剩余行和列的边缘。然而，许多用户希望 x 和 y 位于 C 的行和列的中心。

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

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

用户还可以通过新的 rcParams["pcolor.shading"] (default: 'auto') 在其 .matplotlibrc 文件中或通过 rcParams 来指定此项。

参见 pcolormesh 的示例。

标题、刻度和标签 #

将标签对齐到轴的边缘 #

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

默认设置通过 rcParams["xaxis.labelposition"] 和 rcParams["yaxis.labelposition"] 控制；Colorbar 标签根据其方向采用基于 rcParam 的设置。

(Source code)

(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))

(Source code, 2x.png, png)

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

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

(Source code, 2x.png, png)

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

解决了电源指示器（例如，1e4）保持在底部的问题，即使刻度在顶部。

设置等高线标签的zorder #

clabel 现在接受一个 zorder 关键字参数，使得设置等高线标签的 zorder 更加容易。如果没有指定，clabels 的默认 zorder 过去总是 3（即 Text 的默认 zorder），无论传递给 contour/contourf 的 zorder 是什么。现在 clabels 的默认 zorder 已更改为（contour / contourf 传递的 zorder + 2）。

其他更改 #

新的 `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()

(Source code, 2x.png, png)

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

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

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

之前，Axes.pie 会在 sum(x) > 1 时对其输入 x 进行归一化处理，但如果总和小于 1 则不做任何处理。这可能会引起混淆，因此添加了一个显式关键字参数 normalize。默认情况下，保留旧的行为。

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

(Source code, 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"] (default: '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"] (default: True) 允许在调用 show 或 pause 时禁用提升绘图窗口。当前不支持 MacOSX 后端。

将通用 `mathtext.fallback` 添加到 rcParams #

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

将 `contour.linewidth` 添加到 rcParams #

新的配置选项 rcParams["contour.linewidth"] (default: None) 允许以浮点数控制轮廓的默认线宽。当设置为 None 时，线宽将回退到 rcParams["lines.linewidth"] (default: 1.5)。与通常一样，当未设置为 None 时，配置值会被传递给 contour 的 linewidths 参数覆盖。

3D 轴改进 #

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

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

目前，在数据空间中设置纵横比（通过 set_aspect）的方式在 Axes3D 中不受支持，但未来可能会支持。如果你想模拟在数据空间中具有相等的纵横比，请将数据限制的比例设置为与 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)

(Source code, 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 参数。