Matplotlib 3.8.0 中的新增功能 (2023 年 9 月 13 日)#

有关自上次修订以来的所有问题和 pull request 的列表,请参阅 3.10.0 的 GitHub 统计信息 (2024 年 12 月 13 日) .

类型提示#

Matplotlib 现在为大多数公共 API 提供第一方 PEP484 样式的类型提示文件.

虽然仍然被认为是临时的并且可能会发生变化(有时我们无法完全指定我们想要的内容),但它们应该为类型检查许多常见的用法模式以及与许多编辑器/IDE 集成提供合理的基础.

绘图和注释改进#

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

matplotlib.pyplot.annotate() 和 matplotlib.pyplot.text() 现在支持参数 antialiased.当 antialiased 设置为 True 时,抗锯齿将应用于文本.当 antialiased 设置为 False 时,抗锯齿将不应用于文本.当未指定 antialiased 时,抗锯齿将由 rcParams["text.antialiased"] (default: True) 在 Text 和 Annotation 对象创建时设置.例子:

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)

另请注意,刻度标签的抗锯齿将使用 rcParams["text.antialiased"] (default: True) 在创建它们时设置(通常在创建 Figure 时),之后无法更改.

此外,使用此新功能时,您可能需要确保在相同的上下文中创建和保存/显示图形:

# 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 属性的 getter 和 setter 方法:

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, 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, 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, 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) 进行配置.

MultipleLocator 的 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, 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, png)

用户可以使用新的颜色规范定义颜色,(matplotlib_color, alpha).请注意,显式的 alpha 关键字参数将覆盖来自 (matplotlib_color, alpha) 的 alpha 值.

饼图阴影可以被控制#

pie 的 shadow 参数现在可以是一个 dict,从而允许对使用的 Shadow -patch 进行更多控制.

PolyQuadMesh 是一个用于绘制四边形网格的新类#

~.Axes.pcolor 之前返回一个扁平化的 PolyCollection ,其中仅包含有效的(未屏蔽的)多边形.现在,我们返回一个 PolyQuadMesh ,它是一个混合类,结合了 2D 数组和网格坐标处理的实用性,但仍然继承了 PolyCollection 的绘制方法,这使得对渲染属性的控制比从 pcolormesh 返回的普通 QuadMesh 更多.这个新类是 PolyCollection 的子类,因此应该仍然像以前一样运行.这个新类会跟踪用户的 mask 并适当地更新发送到渲染器的多边形.

(Source code, png)

阴影的深浅可以被控制#

Shadow patch 现在有一个 shade 参数来控制阴影的深浅.如果为 1,则阴影为黑色;如果为 0,则阴影的颜色与被阴影的 patch 相同.默认值(之前是固定的)为 0.7.

SpinesProxy 现在支持调用 set() 方法#

现在可以调用例如 ax.spines[:].set(visible=False) .

允许使用关键字参数设置刻度标签字体#

Axes.tick_params 现在接受一个 labelfontfamily 关键字,该关键字可以独立于其余文本对象更改刻度标签字体:

Axis.tick_params(labelfontfamily='monospace')

Figure,Axes和Legend布局#

savefig 的 pad_inches="layout"]></item> <item id="22337"><![CDATA[当使用 constrained 或者 compressed layout 时,#

When using constrained or compressed layout,

savefig(filename, bbox_inches="tight", pad_inches="layout")

现在将使用在布局引擎上定义的 padding 大小.

添加一个公共方法来修改 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, png)

rcParams['legend.loc'] 现在接受 float-tuple 输入#

rcParams["legend.loc"] (default: 'best') rcParams 现在接受 float-tuple 输入,与 Legend 的 loc 关键字参数相同.这允许用户以更灵活和一致的方式设置图例的位置.

Mathtext 改进#

改进是针对 Mathtext 的,Mathtext 是 Matplotlib 原生的类 TeX 数学解析器 (参见 书写数学表达式 ,不要与 Matplotlib 直接使用 LaTeX 混淆 使用 LaTeX 渲染文本 ).

Boldsymbol mathtext 命令 \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 分隔符一起使用:

要使用 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, 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.

粗斜体 mathtext 命令 \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, png)

3D 悬停坐标#

3D 图形中显示的 x,y,z 坐标之前显示的是无意义的值.此问题已修复,可以直接报告鼠标光标正下方视图窗格上的坐标.当使用正交投影沿主轴方向查看 3D 图形时,或者当 2D 图形已投影到其中一个 3D 轴窗格上时,这可能最有用.请注意,仍然无法直接显示绘制的数据点的坐标.

3D 图形可以共享视角#

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

其他改进#

macosx:可以在窗口或选项卡中打开新图形#

有一个新的 rcParams["macosx.window_mode"] (default: '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']

将制作分辨率加倍的 png 文件用于 hiDPI 显示器.生成的 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