新的更易用的颜色循环

添加了一个名为“petroff10”的新颜色循环。该循环的构建结合了算法强制执行的可访问性约束，包括色觉缺陷建模，以及从众包颜色偏好调查中开发的基于机器学习的美学模型。它的目标是既在美学上普遍令人愉悦，又能让色盲人士访问，使其可以作为通用设计的目标的默认值。有关更多详细信息，请参阅 Petroff, M. A.: "数据可视化中可访问的颜色序列" 和相关的 SciPy 演讲。演示包含在样式表 参考 中。要加载此颜色循环以代替默认值

import matplotlib.pyplot as plt
plt.style.use('petroff10')

暗模式发散颜色图

添加了三个发散颜色图：“berlin”、“managua” 和 “vanimo”。它们是暗模式发散颜色图，中心处的最小亮度，以及两端的最大亮度。这些取自 F. Crameri 的 Scientific colour maps 版本 8.0.1 (DOI: https://doi.org/10.5281/zenodo.1243862)。

import numpy as np
import matplotlib.pyplot as plt

vals = np.linspace(-5, 5, 100)
x, y = np.meshgrid(vals, vals)
img = np.sin(x*y)

_, ax = plt.subplots(1, 3)
ax[0].imshow(img, cmap=plt.cm.berlin)
ax[1].imshow(img, cmap=plt.cm.managua)
ax[2].imshow(img, cmap=plt.cm.vanimo)

(源代码, 2x.png, png)

在 contour 和 contourf 中指定单一颜色

contour 和 contourf 之前接受以字符串形式表示的单一颜色。现在已删除此限制，并且可以传递 指定颜色 教程中描述的任何格式的单一颜色。

import matplotlib.pyplot as plt

fig, (ax1, ax2) = plt.subplots(ncols=2, figsize=(6, 3))
z = [[0, 1], [1, 2]]

ax1.contour(z, colors=('r', 0.4))
ax2.contour(z, colors=(0.1, 0.2, 0.5))

plt.show()

(源代码, 2x.png, png)

异常处理控制

当传递无效的关键字参数时引发的异常现在将该参数名称作为异常的 name 属性。这为异常处理提供了更多控制。

import matplotlib.pyplot as plt

def wobbly_plot(args, **kwargs):
    w = kwargs.pop('wobble_factor', None)

    try:
        plt.plot(args, **kwargs)
    except AttributeError as e:
        raise AttributeError(f'wobbly_plot does not take parameter {e.name}') from e


wobbly_plot([0, 1], wibble_factor=5)

AttributeError: wobbly_plot does not take parameter wibble_factor

初步支持自由线程 CPython 3.13

Matplotlib 3.10 初步支持 CPython 3.13 的自由线程构建。有关自由线程 Python 的更多详细信息，请参阅 https://py-free-threading.github.io、PEP 703 和 CPython 3.13 发行说明。

对自由线程 Python 的支持并不意味着 Matplotlib 是完全线程安全的。我们期望在单个线程中使用 Figure 可以正常工作，并且虽然输入数据通常会被复制，但在某些情况下，从另一个线程修改用于绘图的数据对象可能会导致不一致，因为数据可能不会被复制。强烈不建议使用任何全局状态（例如 pyplot 模块），并且它不太可能稳定工作。另请注意，大多数 GUI 工具包都期望在主线程上运行，因此从其他线程进行交互式使用可能会受到限制或不支持。

如果您对自由线程 Python 感兴趣，例如因为您有一个基于多处理的工作流程，您有兴趣使用 Python 线程运行，我们鼓励您进行测试和实验。如果您遇到您怀疑是由于 Matplotlib 引起的问题，请提交一个 issue，并首先检查该错误是否也出现在“常规”非自由线程 CPython 3.13 构建中。

使用 Agg 渲染器增加 Figure 限制

使用 Agg 渲染器的 Figure 现在在每个方向上的像素限制为 2**23，而不是 2**16。此外，修复了导致艺术家在水平方向超过 2**15 像素时无法渲染的错误。

请注意，如果您正在使用 GUI 后端，它可能具有自己更小的限制（这可能取决于屏幕大小）。

向量化的 hist 样式参数

hist 方法的参数 *hatch*、*edgecolor*、*facecolor*、*linewidth* 和 *linestyle* 现在是向量化的。这意味着当输入 *x* 有多个数据集时，您可以为每个直方图传入单独的参数。

import matplotlib.pyplot as plt
import numpy as np
np.random.seed(19680801)

fig, ((ax1, ax2), (ax3, ax4)) = plt.subplots(2, 2, figsize=(9, 9))

data1 = np.random.poisson(5, 1000)
data2 = np.random.poisson(7, 1000)
data3 = np.random.poisson(10, 1000)

labels = ["Data 1", "Data 2", "Data 3"]

ax1.hist([data1, data2, data3], bins=range(17), histtype="step", stacked=True,
         edgecolor=["red", "green", "blue"], linewidth=[1, 2, 3])
ax1.set_title("Different linewidths")
ax1.legend(labels)

ax2.hist([data1, data2, data3], bins=range(17), histtype="barstacked",
         hatch=["/", ".", "*"])
ax2.set_title("Different hatch patterns")
ax2.legend(labels)

ax3.hist([data1, data2, data3], bins=range(17), histtype="bar", fill=False,
         edgecolor=["red", "green", "blue"], linestyle=["--", "-.", ":"])
ax3.set_title("Different linestyles")
ax3.legend(labels)

ax4.hist([data1, data2, data3], bins=range(17), histtype="barstacked",
         facecolor=["red", "green", "blue"])
ax4.set_title("Different facecolors")
ax4.legend(labels)

plt.show()

(源代码, 2x.png, png)

InsetIndicator 艺术家

indicate_inset 和 indicate_inset_zoom 现在返回一个 InsetIndicator 的实例，其中包含矩形和连接器补丁。这些补丁现在会自动更新，因此

ax.indicate_inset_zoom(ax_inset)
ax_inset.set_xlim(new_lim)

现在给出的结果与

ax_inset.set_xlim(new_lim)
ax.indicate_inset_zoom(ax_inset)

matplotlib.ticker.EngFormatter 现在可以计算偏移量

matplotlib.ticker.EngFormatter 已经获得了在轴附近显示偏移文本的能力。通过与 matplotlib.ticker.ScalarFormatter 共享的逻辑，它可以决定数据是否符合具有偏移量的条件，并使用适当的 SI 单位前缀和提供的 unit 来显示偏移量。

要启用这种新行为，只需在实例化 matplotlib.ticker.EngFormatter 时传入 useOffset=True。请参阅示例 带有 SI 前缀的偏移量和自然数量级。

(源代码, 2x.png, png)

修复 ImageGrid 的单个颜色栏的填充

对于 cbar_location 为“left”和“bottom”的情况，具有 cbar_mode="single" 的 ImageGrid 不再在轴和颜色栏之间添加 axes_pad。如果需要，请使用 cbar_pad 添加额外的间距。

ax.table 将接受 pandas DataFrame

table 方法现在可以接受 Pandas DataFrame 作为 cellText 参数。

import matplotlib.pyplot as plt
import pandas as pd

data = {
    'Letter': ['A', 'B', 'C'],
    'Number': [100, 200, 300]
}

df = pd.DataFrame(data)
fig, ax = plt.subplots()
table = ax.table(df, loc='center')  # or table = ax.table(cellText=df, loc='center')
ax.axis('off')
plt.show()

子图现在以行优先顺序添加

为了 API 的一致性，Figure.subfigures 现在以行优先顺序添加。

import matplotlib.pyplot as plt

fig = plt.figure()
subfigs = fig.subfigures(3, 3)
x = np.linspace(0, 10, 100)

for i, sf in enumerate(fig.subfigs):
    ax = sf.subplots()
    ax.plot(x, np.sin(x + i), label=f'Subfigure {i+1}')
    sf.suptitle(f'Subfigure {i+1}')
    ax.set_xticks([])
    ax.set_yticks([])
plt.show()

(源代码, 2x.png, png)

svg.id rcParam

rcParams["svg.id"] (默认值：None) 允许您将 id 属性插入到顶层 <svg> 标签中。

例如，rcParams["svg.id"] = "svg1" 会导致默认值），不包含 id 标签

<svg
    xmlns:xlink="http://www.w3.org/1999/xlink"
    width="50pt" height="50pt"
    viewBox="0 0 50 50"
    xmlns="http://www.w3.org/2000/svg"
    version="1.1"
    id="svg1"
></svg>

如果您想使用 <use> 标签将整个 matplotlib SVG 文件链接到另一个 SVG 文件中，这将非常有用。

<svg>
<use
    width="50" height="50"
    xlink:href="mpl.svg#svg1" id="use1"
    x="0" y="0"
/></svg>

其中 #svg1 指示符现在将引用顶层 <svg> 标签，因此将导致包含整个文件。

boxplot 和 bxp 方向参数

箱线图有一个新的参数 *orientation: {"vertical", "horizontal"}* 来更改图的方向。这将替换已弃用的 *vert: bool* 参数。

import matplotlib.pyplot as plt
import numpy as np

fig, ax = plt.subplots()
np.random.seed(19680801)
all_data = [np.random.normal(0, std, 100) for std in range(6, 10)]

ax.boxplot(all_data, orientation='horizontal')
plt.show()

(源代码, 2x.png, png)

violinplot 和 violin 方向参数

小提琴图有一个新的参数 *orientation: {"vertical", "horizontal"}* 来更改图的方向。这将替换已弃用的 *vert: bool* 参数。

import matplotlib.pyplot as plt
import numpy as np

fig, ax = plt.subplots()
np.random.seed(19680801)
all_data = [np.random.normal(0, std, 100) for std in range(6, 10)]

ax.violinplot(all_data, orientation='horizontal')
plt.show()

(源代码, 2x.png, png)

FillBetweenPolyCollection

新类 matplotlib.collections.FillBetweenPolyCollection 提供了 set_data 方法，从而可以进行例如重采样（galleries/event_handling/resample.html）。matplotlib.axes.Axes.fill_between() 和 matplotlib.axes.Axes.fill_betweenx() 现在返回这个新类。

import numpy as np
from matplotlib import pyplot as plt

t = np.linspace(0, 1)

fig, ax = plt.subplots()
coll = ax.fill_between(t, -t**2, t**2)
fig.savefig("before.png")

coll.set_data(t, -t**4, t**4)
fig.savefig("after.png")

填充 3D 线之间的区域

新方法 Axes3D.fill_between 允许使用多边形填充两条 3D 线之间的表面。

N = 50
theta = np.linspace(0, 2*np.pi, N)

x1 = np.cos(theta)
y1 = np.sin(theta)
z1 = 0.1 * np.sin(6 * theta)

x2 = 0.6 * np.cos(theta)
y2 = 0.6 * np.sin(theta)
z2 = 2  # Note that scalar values work in addition to length N arrays

fig = plt.figure()
ax = fig.add_subplot(projection='3d')
ax.fill_between(x1, y1, z1, x2, y2, z2,
                alpha=0.5, edgecolor='k')

(源代码, 2x.png, png)

使用鼠标旋转 3D 图形

使用鼠标旋转三维图形的操作更加直观。现在，图形对鼠标移动的反应方式相同，不受当前特定方向的影响；并且可以控制所有 3 个旋转自由度（方位角、仰角和滚转）。默认情况下，它使用 Ken Shoemake 的 ARCBALL 的一种变体 [1]。鼠标旋转的特定样式可以通过 rcParams["axes3d.mouserotationstyle"] 设置（默认值：'arcball'）。另请参阅 使用鼠标旋转。

要恢复到原始的鼠标旋转样式，请创建一个包含以下内容的 matplotlibrc 文件

axes3d.mouserotationstyle: azel

要尝试各种鼠标旋转样式之一

import matplotlib as mpl
mpl.rcParams['axes3d.mouserotationstyle'] = 'trackball'  # 'azel', 'trackball', 'sphere', or 'arcball'

import numpy as np
import matplotlib.pyplot as plt
from matplotlib import cm

ax = plt.figure().add_subplot(projection='3d')

X = np.arange(-5, 5, 0.25)
Y = np.arange(-5, 5, 0.25)
X, Y = np.meshgrid(X, Y)
R = np.sqrt(X**2 + Y**2)
Z = np.sin(R)

surf = ax.plot_surface(X, Y, Z, cmap=cm.coolwarm,
                       linewidth=0, antialiased=False)

plt.show()

[1]

Ken Shoemake, "ARCBALL: A user interface for specifying three-dimensional rotation using a mouse", in Proceedings of Graphics Interface '92, 1992, pp. 151-156, https://doi.org/10.20380/GI1992.18

3D 图形中的数据现在可以动态裁剪到轴视图限制

所有 3D 绘图函数现在都支持 *axlim_clip* 关键字参数，该参数会将数据裁剪到轴视图限制，隐藏这些边界之外的所有数据。在平移和缩放时，此裁剪将实时动态应用。

请注意，如果线段或 3D 面片的某个顶点被裁剪，则整个线段或面片将被隐藏。无法显示部分线或面片，使其在视图框边界处被“平滑”地切断，这是当前渲染器的局限性。

import matplotlib.pyplot as plt
import numpy as np

fig, ax = plt.subplots(subplot_kw={"projection": "3d"})
x = np.arange(-5, 5, 0.5)
y = np.arange(-5, 5, 0.5)
X, Y = np.meshgrid(x, y)
R = np.sqrt(X**2 + Y**2)
Z = np.sin(R)

# Note that when a line has one vertex outside the view limits, the entire
# line is hidden. The same is true for 3D patches (not shown).
# In this example, data where x < 0 or z > 0.5 is clipped.
ax.plot_wireframe(X, Y, Z, color='C0')
ax.plot_wireframe(X, Y, Z, color='C1', axlim_clip=True)
ax.set(xlim=(0, 10), ylim=(-5, 5), zlim=(-1, 0.5))
ax.legend(['axlim_clip=False (default)', 'axlim_clip=True'])

(源代码, 2x.png, png)

杂项更改

• matplotlib.ticker.ScalarFormatter 类获得了一个新的实例化参数 usetex。

• 由于内部优化，创建 Axes 现在快 20-25%。

• Figure.subfigures 和 SubFigure 上的 API 现在被认为是稳定的。