Matplotlib 3.8.0 新特性 (2023年9月13日)#
有关自上次修订以来的所有问题和拉取请求列表，请参阅 3.10.3 (2025年5月8日) 的 GitHub 统计数据。
类型提示#
Matplotlib 现在为大多数公共 API 提供第一方 PEP484 风格的类型提示文件。
虽然仍被认为是临时性的且可能会更改（有时我们无法完全指定我们想要的内容），但它们应该为类型检查许多常见使用模式以及与许多编辑器/IDE 集成提供合理的基础。
绘图和注释改进#
支持自定义文本和注释的抗锯齿#
matplotlib.pyplot.annotate() 和 matplotlib.pyplot.text() 现在支持参数 antialiased。当 antialiased 设置为 True 时，文本将应用抗锯齿。当 antialiased 设置为 False 时，文本将不应用抗锯齿。当未指定 antialiased 时，抗锯齿将在创建 Text 和 Annotation 对象时由 rcParams["text.antialiased"]（默认值：True）设置。示例
mpl.text.Text(.5, .5, "foo\nbar", antialiased=True)
plt.text(0.5, 0.5, '6 inches x 2 inches', antialiased=True)
ax.annotate('local max', xy=(2, 1), xytext=(3, 1.5), antialiased=False)
如果文本包含数学表达式，antialiased 将应用于整个文本。示例
# no part will be antialiased for the text below
plt.text(0.5, 0.25, r"$I'm \sqrt{x}$", antialiased=False)
另请注意，刻度标签的抗锯齿将在它们创建时（通常在创建 Figure 时）通过 rcParams["text.antialiased"]（默认值：True）进行设置，之后无法更改。
此外，有了这项新功能，您可能需要确保在相同的上下文下创建和保存/显示图形
# previously this was a no-op, now it is what works
with rccontext(text.antialiased=False):
fig, ax = plt.subplots()
ax.annotate('local max', xy=(2, 1), xytext=(3, 1.5))
fig.savefig('/tmp/test.png')
# previously this had an effect, now this is a no-op
fig, ax = plt.subplots()
ax.annotate('local max', xy=(2, 1), xytext=(3, 1.5))
with rccontext(text.antialiased=False):
fig.savefig('/tmp/test.png')
`AutoMinorLocator` 分割的 rcParams#
rcParams rcParams["xtick.minor.ndivs"]（默认值：'auto'）和 rcParams["ytick.minor.ndivs"]（默认值：'auto'）已添加，以允许设置默认分割数量；如果设置为 auto，分割数量将根据主刻度线之间的距离选择。
Axline 设置器和获取器#
从 axes.Axes.axline 返回的对象现在支持其 xy1、xy2 和 slope 属性的获取器和设置器方法
line1.get_xy1()
line1.get_slope()
line2.get_xy2()
line1.set_xy1(.2, .3)
line1.set_slope(2.4)
line2.set_xy2(.1, .6)
等高线图的裁剪#
contour 和 contourf 现在接受 clip_path 参数。
import numpy as np
import matplotlib.pyplot as plt
import matplotlib.patches as mpatches
x = y = np.arange(-3.0, 3.01, 0.025)
X, Y = np.meshgrid(x, y)
Z1 = np.exp(-X**2 - Y**2)
Z2 = np.exp(-(X - 1)**2 - (Y - 1)**2)
Z = (Z1 - Z2) * 2
fig, ax = plt.subplots()
patch = mpatches.RegularPolygon((0, 0), 5, radius=2,
transform=ax.transData)
ax.contourf(X, Y, Z, clip_path=patch)
plt.show()
(Source code, 2x.png, png)
Axes.ecdf#
新的 Axes 方法 ecdf 允许绘制经验累积分布函数，无需任何分箱。
import matplotlib.pyplot as plt
import numpy as np
fig, ax = plt.subplots()
ax.ecdf(np.random.randn(100))
(Source code, 2x.png, png)
Figure.get_suptitle()、Figure.get_supxlabel()、Figure.get_supylabel()#
这些方法分别返回由 Figure.suptitle()、Figure.supxlabel() 和 Figure.supylabel() 设置的字符串。
Ellipse.get_vertices()、Ellipse.get_co_vertices()#
这些方法返回椭圆长轴和短轴顶点的坐标。此外，还添加了一个示例画廊演示，展示如何向椭圆添加箭头以显示椭圆的顺时针或逆时针旋转。为了将箭头精确地放置在椭圆上，使用了顶点的坐标。
在 label_outer() 中移除内部刻度线#
迄今为止，label_outer() 只移除了刻度标签。刻度线仍可见。现在可以通过新参数 label_outer(remove_inner_ticks=True) 进行配置。
import numpy as np
import matplotlib.pyplot as plt
x = np.linspace(0, 2 * np.pi, 100)
fig, axs = plt.subplots(2, 2, sharex=True, sharey=True,
gridspec_kw=dict(hspace=0, wspace=0))
axs[0, 0].plot(x, np.sin(x))
axs[0, 1].plot(x, np.cos(x))
axs[1, 0].plot(x, -np.cos(x))
axs[1, 1].plot(x, -np.sin(x))
for ax in axs.flat:
ax.grid(color='0.9')
ax.label_outer(remove_inner_ticks=True)
(Source code, 2x.png, png)
可配置的图例阴影#
图例的 shadow 参数现在除了布尔值外，还接受字典。字典可以包含 patches.Patch 的任何关键字。例如，这允许设置图例阴影的颜色和/或透明度
ax.legend(loc='center left', shadow={'color': 'red', 'alpha': 0.5})
并控制阴影位置
ax.legend(loc='center left', shadow={"ox":20, "oy":-20})
目前不支持通过 rcParams["legend.shadow"]（默认值：False）进行配置。
MultipleLocator 的 offset 参数#
现在可以指定一个 offset 来将所有刻度线偏移给定值。
import matplotlib.pyplot as plt
import matplotlib.ticker as mticker
_, ax = plt.subplots()
ax.plot(range(10))
locator = mticker.MultipleLocator(base=3, offset=0.3)
ax.xaxis.set_major_locator(locator)
plt.show()
(Source code, 2x.png, png)
添加新的有效颜色格式 (matplotlib_color, alpha)#
import matplotlib.pyplot as plt
from matplotlib.patches import Rectangle
fig, ax = plt.subplots()
rectangle = Rectangle((.2, .2), .6, .6,
facecolor=('blue', 0.2),
edgecolor=('green', 0.5))
ax.add_patch(rectangle)
(Source code, 2x.png, png)
用户可以使用新的颜色规范，即 *(`matplotlib_color`, alpha)* 来定义颜色。请注意，明确的 alpha 关键字参数将覆盖来自 *(`matplotlib_color`, alpha)* 的 alpha 值。
饼图阴影可控#
`PolyQuadMesh` 是一个用于绘制四边形网格的新类#
pcolor 以前返回一个扁平化的 PolyCollection，其中只包含有效的多边形（未遮罩）。现在，我们返回一个 PolyQuadMesh，它是一个混合类，结合了二维数组和网格坐标处理的实用性，但仍继承了 PolyCollection 的绘图方法，这使得它比从 pcolormesh 返回的普通 QuadMesh 对渲染属性有更多的控制。这个新类是 PolyCollection 的子类，因此其行为应与以前相同。这个新类为用户跟踪遮罩，并适当地更新发送到渲染器的多边形。
(Source code, 2x.png, png)
阴影深浅可控#
Shadow 补丁现在有一个 shade 参数来控制阴影的深浅。如果为 1，阴影是黑色；如果为 0，阴影的颜色与被阴影的补丁相同。默认值（以前是固定的）为 0.7。
`SpinesProxy` 现在支持调用 set() 方法#
现在可以调用例如 ax.spines[:].set(visible=False)。
允许使用关键字参数设置刻度标签字体#
Axes.tick_params 现在接受一个 *labelfontfamily* 关键字，可以独立于其他文本对象更改刻度标签字体。
Axis.tick_params(labelfontfamily='monospace')
图形、坐标轴和图例布局#
savefig 的 pad_inches="layout"#
当使用受限或压缩布局时，
savefig(filename, bbox_inches="tight", pad_inches="layout")
将现在使用布局引擎上定义的填充大小。
添加一个公共方法以修改 Legend 的位置#
Legend 位置现在可以在定义后进行调整。
from matplotlib import pyplot as plt
fig = plt.figure()
ax = fig.add_subplot(1, 1, 1)
x = list(range(-100, 101))
y = [i**2 for i in x]
ax.plot(x, y, label="f(x)")
ax.legend()
ax.get_legend().set_loc("right")
# Or
# ax.get_legend().set(loc="right")
plt.show()
(Source code, 2x.png, png)
`rcParams['legend.loc']` 现在接受浮点元组输入#
rcParams rcParams["legend.loc"]（默认值：'best'）现在接受浮点元组输入，与 Legend 的 *loc* 关键字参数相同。这允许用户以更灵活和一致的方式设置图例位置。
Mathtext 改进#
改进针对 Mathtext，Matplotlib 的原生 TeX 类似数学解析器（参见 撰写数学表达式，不要与 Matplotlib 直接使用 LaTeX 混淆：使用 LaTeX 渲染文本）。
Boldsymbol mathtext 命令 \boldsymbol#
支持在 mathtext 中使用 \boldsymbol{} 命令
要将符号更改为粗体，请将文本用字体命令括起来，如所示
r'$\boldsymbol{a+2+\alpha}$'
`mathtext` 具有更多可调整大小的分隔符#
已添加 \lgroup 和 \rgroup 可调整大小的分隔符。
以下分隔符名称此前已受支持，但现在可以使用 \left 和 \right 进行大小调整
\lbrace、\rbrace、\leftbrace和\rightbrace\lbrack和\rbrack\leftparen和\rightparen
使用这些并没有明显的优势。相反，它们是为了完整性而添加的。
`mathtext` 文档改进#
文档已更新，直接从解析器获取信息。这意味着（几乎）所有支持的符号、运算符等都显示在 撰写数学表达式 中。
`mathtext` 现在支持 \substack#
\substack 可用于在方程中创建多行下标或上标。
要使用它，请将数学表达式用 substack 命令括起来，如所示
r'$\sum_{\substack{1\leq i\leq 3\\ 1\leq j\leq 5}}$'
`mathtext` 现在支持 \middle 分隔符#
\middle 分隔符已添加，现在可以与 \left 和 \right 分隔符一起使用
要使用 middle 命令，请将其放在 \left 和 \right 分隔符命令之间，如所示
r'$\left( \frac{a}{b} \middle| q \right)$'
`mathtext` 运算符#
当使用 Unicode 字体时，已添加并修正了许多运算符。此外，还对以前的许多运算符添加了正确的间距。特别是，用于 \gnapprox、\lnapprox、\leftangle 和 \rightangle 的字符已得到修正。
`mathtext` 间距修正#
由于文档更新，一些关系和运算符符号的间距被这样分类，因此将正确进行间距。
`mathtext` 现在支持 \text#
\text 可用于在方程中获取正体文本并获得普通破折号 (-)。
import matplotlib.pyplot as plt
plt.text(0.1, 0.5, r"$a = \sin(\phi) \text{ such that } \phi = \frac{x}{y}$")
plt.text(0.1, 0.3, r"$\text{dashes (-) are retained}$")
(Source code, 2x.png, png)
粗斜体 mathtext 命令 \mathbfit#
支持在 mathtext 中使用 \mathbfit{} 命令来设置粗斜体字体样式
要将字体更改为粗斜体，请将文本用字体命令括起来，如所示
r'$\mathbfit{\eta \leq C(\delta(\eta))}$
3D 绘图改进#
指定 3D 图的刻度线和轴标签位置#
现在可以指定 3D 图的刻度线和轴标签位置。
import matplotlib.pyplot as plt
positions = ['lower', 'upper', 'default', 'both', 'none']
fig, axs = plt.subplots(2, 3, figsize=(12, 8),
subplot_kw={'projection': '3d'})
for ax, pos in zip(axs.flatten(), positions):
for axis in ax.xaxis, ax.yaxis, ax.zaxis:
axis.set_label_position(pos)
axis.set_ticks_position(pos)
title = f'position="{pos}"'
ax.set(xlabel='x', ylabel='y', zlabel='z', title=title)
axs[1, 2].axis('off')
(Source code, 2x.png, png)
3D 悬停坐标#
以前在 3D 图中显示的 x、y、z 坐标值毫无意义。现在已修复为直接报告鼠标光标正下方的视图平面上的坐标。这在以正交投影方式沿主轴方向查看 3D 图时，或将 2D 图投影到 3D 轴平面之一时，可能最为有用。请注意，目前仍无法直接显示绘制数据点的坐标。
其他改进#
macOSX：新图形可以在窗口或标签页中打开#
已新增一个 rcParams["macosx.window_mode"]（默认值：'system'）rcParam，用于控制 macosx 后端如何打开新图形。默认值为 **system**，使用系统设置，或者可以明确指定 **tab** 或 **window** 来选择打开新图形的模式。
`matplotlib.mpl_toolkits` 现在是一个隐式命名空间包#
随着 `setuptools` 67.3.0 中 `pkg_resources.declare_namespace` 的弃用，`matplotlib.mpl_toolkits` 现在根据 PEP 420 实现为隐式命名空间。
Plot Directive 现在可以使用 "srcset" 创建响应式图像#
plot sphinx 指令（matplotlib.sphinxext.plot_directive，在 rst 中作为 .. plot:: 调用）可以配置为自动生成更高分辨率的图形，并将其添加到构建的 html 文档中。在 conf.py 中
extensions = [
...
'matplotlib.sphinxext.plot_directive',
'matplotlib.sphinxext.figmpl_directive',
...]
plot_srcset = ['2x']
将为 hiDPI 显示器生成两倍分辨率的 png 文件。生成的 html 文件将包含类似以下的图像条目
<img src="../_images/nestedpage-index-2.png" style="" srcset="../_images/nestedpage-index-2.png, ../_images/nestedpage-index-2.2x.png 2.00x" alt="" class="plot-directive "/>