Matplotlib 3.8.0 的新特性（2023年9月13日）#

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

类型提示#

Matplotlib 现在为大多数公共 API 提供了符合 PEP484 风格的类型提示文件。

虽然仍被视为暂定且可能会有变动（有时我们并不能完全明确我们想要什么），但它们应该为类型检查许多常见使用模式提供了一个合理的基础，并且能够与许多编辑器/IDE集成。

绘图和注释改进#

支持自定义文本和注释的抗锯齿效果#

matplotlib.pyplot.annotate() 和 matplotlib.pyplot.text() 现在支持参数 antialiased。当 antialiased 设置为 True 时，将对文本应用抗锯齿。当 antialiased 设置为 False 时，不对文本应用抗锯齿。当未指定 antialiased 时，抗锯齿将由 Text 和 Annotation 对象创建时的 rcParams["text.antialiased"] (default: 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)

如果文本包含数学表达式，抗锯齿 应用于整个文本。示例：

# 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"] (default: 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"] (default: 'auto') 和 rcParams["ytick.minor.ndivs"] (default: '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"] (default: False) 进行配置。

offset 参数用于 MultipleLocator#

现在可以指定一个 偏移量 ，以将所有刻度按给定值移动。

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 值。

饼图阴影可以被控制#

pie 的 shadow 参数现在可以是一个字典，允许对使用的 Shadow-patch 进行更多控制。

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["legend.loc"] (default: 'best') rcParams 接受浮点数元组输入，与 Legend 的 loc 关键字参数相同。这允许用户以更灵活和一致的方式设置图例的位置。

数学文本改进#

改进针对的是 Mathtext，Matplotlib 的原生类 TeX 数学解析器（参见 书写数学表达式，不要与 Matplotlib 直接使用 LaTeX 混淆：使用 LaTeX 进行文本渲染）。

Boldsymbol 数学文本命令 \boldsymbol#

支持在 mathtext 中使用 \boldsymbol{} 命令：

要将符号变为粗体，请将文本包含在字体命令中，如下所示：

r'$\boldsymbol{a+2+\alpha}$'
\[\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 分隔符一起使用：

要使用中间命令，请将其放在 \left 和 \right 分隔符命令之间，如下所示：

r'$\left( \frac{a}{b} \middle| q \right)$'

mathtext 运算符#

在使用Unicode字体时，已添加和修正了许多操作符。此外，还为之前的许多操作符添加了正确的间距。特别是，用于 \gnapprox、 \lnapprox、 \leftangle 和 \rightangle 的字符已得到修正。

mathtext 间距修正#

由于文档的更新，许多关系和操作符符号的间距被归类为这样，因此将正确地进行间距处理。

mathtext 现在支持 `` ext``#

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

Illustration of the newly added \text command, showing that it renders as normal text, including spaces, despite being part of an equation. Also show that a dash is not rendered as a minus when part of a \text command.

粗斜体数学文本命令 \mathbfit#

支持在mathtext中使用粗斜体字体样式，使用 \mathbfit{} 命令：

要将字体改为粗体和斜体，请将文本包含在字体命令中，如下所示：

r'$\mathbfit{\eta \leq C(\delta(\eta))}$
\[\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轴窗格之一时，这可能最为有用。请注意，仍然无法直接显示绘制数据点的坐标。

3D 图可以共享视角#

3D 图现在可以共享相同的视角，因此当你旋转一个图时，其他图也会旋转。这可以通过在添加轴时使用 shareview 关键字参数，或者通过使用现有 3D 轴的 ax1.shareview(ax2) 方法来实现。

其他改进#

macosx: 新图表可以在窗口或标签中打开#

有一个新的 rcParams["macosx.window_mode`"] rcParam 用于控制使用 macosx 后端时新图形如何打开。默认值是 system，它使用系统设置，或者可以指定 tab 或 window 来明确选择用于打开新图形的模式。

matplotlib.mpl_toolkits 现在是一个隐式命名空间包#

随着 setuptools 67.3.0 中 pkg_resources.declare_namespace 的弃用，matplotlib.mpl_toolkits 现在作为隐式命名空间实现，遵循 PEP 420。

Plot 指令现在可以使用“srcset”制作响应式图像#

绘图 sphinx 指令（matplotlib.sphinxext.plot_directive，在 rst 中调用为 .. plot::）可以配置为自动生成更高分辨率的图像，并将这些图像添加到构建的 html 文档中。在 conf.py 中:

extensions = [
...
    'matplotlib.sphinxext.plot_directive',
    'matplotlib.sphinxext.figmpl_directive',
...]

plot_srcset = ['2x']

将为高DPI显示器生成双倍分辨率的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 "/>
On this page