Matplotlib 3.3.0 新特性（2020 年 7 月 16 日）#

有关自上次修订以来的所有问题和拉取请求列表，请参阅 GitHub 3.11.0 版本统计信息 (2026年6月11日)。

图形和坐标轴的创建/管理 #

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

图例标签的文本颜色 #

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

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

(源代码, 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 上居中（如果 x 和 y 与 C 大小相同，否则会抛出错误）。shading='auto' 会根据 X、Y、C 的大小选择 'flat' 或 'nearest'。

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

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

参见 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'）控制；颜色条标签根据其方向采用相应的 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），则关闭自动定位。这也可以通过新的 rcParameter 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 已更改为（传递给 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()

(源代码, 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，则会引发错误。

(源代码, 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 后端。

在 rcParams 中添加通用的 `mathtext.fallback`#

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

在 rcParams 中添加 `contour.linewidth`#

新的配置选项 rcParams["contour.linewidth"]（默认：None）允许将轮廓的默认线宽控制为浮点数。当设置为 None 时，线宽会回退到 rcParams["lines.linewidth"]（默认：1.5）。当传递给 contour 的 linewidths 参数不为 None 时，配置值照常被覆盖。

3D 坐标轴改进 #

`Axes3D` 不再为了匹配 2D 纵横比而扭曲 3D 绘图 #

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

目前，Axes3D 不支持在数据空间中设置纵横比（通过 set_aspect 的模式），但将来可能会支持。如果您想模拟数据空间中的等轴比，请设置数据限制的比率以匹配 get_box_aspect 的值。要控制这些比率，请使用 set_box_aspect 方法，该方法接受以 X:Y:Z 三元组形式的比率。默认纵横比为 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 参数的包装函数。