Matplotlib 3.4.0 中的新功能 (2021 年 3 月 26 日)#

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

Figure 和 Axes 的创建/管理#

新的子图功能#

新的 figure.Figure.add_subfigure 和 figure.Figure.subfigures 功能允许在图形中创建虚拟图形.以前使用嵌套的 gridspecs 完成了类似的嵌套(参见 嵌套的 Gridspecs ).但是,这不允许仅与每个子 gridspec 相关的本地化图形艺术家(例如,颜色条或suptitle).

新方法 figure.Figure.add_subfigure 和 figure.Figure.subfigures 旨在与 figure.Figure.add_subplot 和 figure.Figure.subplots 押韵,并具有大多数相同的参数.

有关更多详细信息,请参见 图形子图 .

备注

从 v3.4 开始,子图功能是实验性 API.

(Source code, png)

subplot_mosaic 的单行字符串表示法#

Figure.subplot_mosaic 和 pyplot.subplot_mosaic 现在接受单行字符串,使用分号分隔行.即:

plt.subplot_mosaic(
    """
    AB
    CC
    """)

可以写成更短的形式:

plt.subplot_mosaic("AB;CC")

(Source code, png)

Axes 创建方法 ( gca , add_axes , add_subplot ) 的行为变更#

创建新 Axes 的函数( pyplot.axes , pyplot.subplot , figure.Figure.add_axes , figure.Figure.add_subplot )的行为已更改.过去,这些函数会检测您是否尝试使用与当前 Figure 中已存在的 Axes 相同的关键字参数来创建 Axes,如果是,它们将返回现有的 Axes.现在, pyplot.axes , figure.Figure.add_axes 和 figure.Figure.add_subplot 将始终创建新的 Axes. pyplot.subplot 将继续重用具有匹配的 subplot spec 和相等 kwargs 的现有 Axes.

相应地,获取当前 Axes 的函数( pyplot.gca , figure.Figure.gca )的行为已更改.过去,这些函数接受关键字参数.如果关键字参数与已存在的 Axes 匹配,则将返回该 Axes,否则将使用这些关键字参数创建新的 Axes.现在,仅当当前图中根本没有 Axes 时,才会考虑关键字参数.在未来的版本中,这些函数将不再接受关键字参数.

add_subplot / add_axes 获得了 axes_class 参数#

特别是,现在可以使用惯用的方式使用 mpl_toolkits Axes 子类,例如 fig.add_subplot(axes_class=mpl_toolkits.axislines.Axes)

Subplot 和 subplot2grid 现在可以与 constrained layout 一起使用#

constrained_layout 依赖于 figure 上每个逻辑布局的单个 GridSpec .以前, pyplot.subplot 和 pyplot.subplot2grid 每次调用时都会添加一个新的 GridSpec ,因此与 constrained_layout 不兼容.

现在,如果行数和列数与 figure 中已存在的顶级 GridSpec 相同,则 subplot 尝试重用 GridSpec ,即 plt.subplot(2, 1, 2) 将使用与 plt.subplot(2, 1, 1) 相同的 GridSpec,并且 Figure 的 constrained_layout=True 选项将起作用.

相反,混合 nrows 和 ncols 将无法与 constrained_layout 一起使用: plt.subplot(2, 2, 1) 之后是 plt.subplots(2, 1, 2) 仍然会生成两个 GridSpec,并且 constrained_layout=True 会产生错误的结果.为了获得所需的效果,第二次调用可以指定第二个 Axes 应该覆盖的单元格: plt.subplots(2, 2, (2, 4)) ,或者可以使用更 Pythonic 的 plt.subplot2grid((2, 2), (0, 1), rowspan=2) .

绘图方法#

axline 支持 transform 参数#

axline 现在支持 transform 参数,该参数适用于点 xy1,xy2.斜率(如果给定)始终采用数据坐标.

例如,这可以与 ax.transAxes 一起使用,用于绘制具有固定斜率的线条.在下面的图中,该线穿过两个 Axes 上的同一点,即使它们显示不同的数据限制.

fig, axs = plt.subplots(1, 2)

for i, ax in enumerate(axs):
    ax.axline((0.25, 0), slope=2, transform=ax.transAxes)
    ax.set(xlim=(i, i+5), ylim=(i, i+5))

(Source code, png)

新的条形图自动标签#

添加了一个新的 Axes.bar_label 方法,用于自动标记条形图.

../../_images/sphx_glr_bar_label_demo_001.png

新的自动标签的示例.#

可以为 bar 和 barh 指定阴影线列表#

类似于其他一些矩形属性,现在可以向 bar 和 barh 传递一个填充样式的列表,以便创建具有不同填充样式的条形图,例如:

(Source code, png)

设置 BarContainer 的方向#

BarContainer 现在接受一个新的字符串参数 orientation.它可以是 'vertical' 或 'horizontal' ,默认为 None .

等高线图现在默认使用 ScalarFormatter#

将 fmt="%1.3f" 传递给等高线调用以恢复旧的默认标签格式.

Axes.errorbar 正确循环非颜色属性#

以前,如果显式指定了颜色,即使属性循环器用于其他属性(例如线条样式), Axes.errorbar 也会错误地跳过 Axes 属性循环.现在, Axes.errorbar 将像 Axes.plot 一样推进 Axes 属性循环,即只要循环器中的所有属性都不是显式传递的.

例如,以下代码将循环显示线条样式:

x = np.arange(0.1, 4, 0.5)
y = np.exp(-x)
offsets = [0, 1]

plt.rcParams['axes.prop_cycle'] = plt.cycler('linestyle', ['-', '--'])

fig, ax = plt.subplots()
for offset in offsets:
    ax.errorbar(x, y + offset, xerr=0.1, yerr=0.3, fmt='tab:blue')

(Source code, png)

errorbar errorevery 参数匹配 markevery#

与 plot 的 markevery 参数类似, errorbar 的 errorevery 参数现在接受切片和 NumPy 高级索引(必须与 x 的大小匹配).

(Source code, png)

hexbin 支持 C 参数的数据引用#

与 x 和 y 参数一样, Axes.hexbin 现在支持使用数据引用传递 C 参数.

data = {
    'a': np.random.rand(1000),
    'b': np.random.rand(1000),
    'c': np.random.rand(1000),
}

fig, ax = plt.subplots()
ax.hexbin('a', 'b', C='c', data=data, gridsize=10)

(Source code, png)

支持用于格式化 Sankey 标签的可调用对象#

matplotlib.sankey.Sankey 的 format 参数现在可以接受可调用对象.

这允许使用任意函数来标记流量,例如允许将数字映射到表情符号.

(Source code, png)

Axes.spines 访问快捷方式#

Axes.spines 现在是 Spine s 的专用容器类 Spines ,而不是 OrderedDict .除了类似字典的访问方式外, Axes.spines 现在还支持一些类似 pandas.Series 的功能.

通过项或属性访问单个元素:

ax.spines['top'].set_visible(False)
ax.spines.top.set_visible(False)

访问项的子集:

ax.spines[['top', 'right']].set_visible(False)

同时访问所有项:

ax.spines[:].set_visible(False)

新的 stairs 方法和 StepPatch artist#

pyplot.stairs 和底层艺术家 StepPatch 为绘制阶梯式常数函数提供了一个更清晰的界面,适用于您知道阶梯边缘的常见情况.这取代了 pyplot.step 的许多用例,例如在绘制 numpy.histogram 的输出时.

对于艺术家和函数,类x的边输入比类y的值输入长一个元素

(Source code, png)

请参阅 阶梯演示 中的示例.

为 stem 图添加了 orientation 参数#

默认情况下,stem 线是垂直的.可以使用 Axes.stem 或 pyplot.stem 的 orientation 参数将其更改为水平:

(Source code, png)

Bracket 箭头样式的角度#

现在应用在 Bracket 箭头样式(传递给 FancyArrowPatch 的 arrowstyle 参数的 ]-[ , ]- , -[ 或 |-| )上指定的角度.以前,允许使用 angleA 和 angleB 选项,但不起作用.

(Source code, png)

TickedStroke patheffect#

新的 TickedStroke patheffect 可用于生成带有刻度样式的线条.例如,这可以用于区分优化解决方案空间中约束边界的有效侧和无效侧.

../../_images/sphx_glr_tickedstroke_demo_002.png

颜色和颜色映射#

集合颜色指定和映射#

重新处理颜色映射以及 facecolor 和 edgecolor 的关键字参数已导致三个行为变更:

  1. 可以通过调用 Collection.set_array(None) 关闭颜色映射.以前,这将不起作用.

  2. 当设置了一个可映射的数组,且 facecolor='none' 和 edgecolor='face' ,则面和边都不会着色.以前,边会被颜色映射.

  3. 当设置了一个可映射的数组,且 facecolor='none' 和 edgecolor='red' ,则边是红色的.这解决了 Issue #1302.以前,边会被颜色映射.

透明度 (alpha) 可以在集合中设置为数组#

以前,控制集合中透明度的 alpha 值只能指定为应用于集合中所有元素的标量.例如, Axes.scatter 图中的所有标记,或 Axes.pcolormesh 图中的所有四边形都将具有相同的 alpha 值.

现在可以提供 alpha 作为数组,每个元素(标记,四边形等)在集合中都有一个值.

(Source code, png)

pcolormesh 通过启用对齐改进了透明度处理#

由于 snapping 关键字参数传递到 Agg 后端的方式,以前版本的 Matplotlib 似乎在具有透明度的网格边缘之间显示线条.此版本现在默认应用对齐.要恢复旧的行为(例如,对于测试图像),您可以将 rcParams["pcolormesh.snap"] (default: True) 设置为 False .

(Source code, png)

请注意,主绘图区网格边界之间的线条透明度不一致.当向颜色条添加透明度时,颜色条也会显示这些线条,因为其内部使用 pcolormesh 来绘制颜色条.默认启用对齐功能(如下所示)时,网格边界处的线条会消失.

(Source code, png)

Colormap 对象的 IPython 表示#

matplotlib.colors.Colormap 对象现在具有用于 IPython / Jupyter 后端的图像表示.在最后一行返回颜色映射的单元格将显示颜色映射的图像.

In[1]: cmap = plt.get_cmap('viridis').with_extremes(bad='r', under='g', over='b')

In[2]: cmap
Out[2]:
viridis
viridis colormap
under
bad
over

Colormap.set_extremes 和 Colormap.with_extremes#

由于 Colormap.set_bad , Colormap.set_under 和 Colormap.set_over 方法会就地修改颜色映射,因此用户必须小心,如果要设置极端颜色(例如,对于内置颜色映射),应首先复制颜色映射.

新的 Colormap.with_extremes(bad=..., under=..., over=...) 可用于首先复制颜色映射,然后在该副本上设置极端颜色.

新的 Colormap.set_extremes 方法是为了与 Colormap.with_extremes 实现 API 对称性而提供的,但请注意,它与之前的各个 setter 存在相同的问题.

获取 Colormap 对象的 under/over/bad 颜色#

matplotlib.colors.Colormap 现在具有方法 get_under , get_over , get_bad ,用于获取超出范围和被屏蔽的值所使用的颜色.

新的 cm.unregister_cmap 函数#

matplotlib.cm.unregister_cmap 允许用户删除他们之前注册的颜色映射.

新的 CenteredNorm 用于围绕中心对称的数据#

如果数据围绕中心对称,例如,围绕中心零的正异常和副异常, CenteredNorm 是一种新的规范化方法,可以自动创建围绕中心的对称映射.此规范化方法非常适合与在其中心使用非饱和发散颜色图结合使用.

(Source code, png)

如果对称中心与 0 不同,则可以使用 vcenter 参数进行设置.要手动设置 CenteredNorm 的范围,请使用 halfrange 参数.

有关数据规范化的示例和更多详细信息,请参见 颜色映射归一化 .

用于任意规范化的新 FuncNorm#

FuncNorm 允许使用函数进行正向和反向的任意归一化.

(Source code, png)

有关数据规范化的示例和更多详细信息,请参见 颜色映射归一化 .

现在可以把基于 GridSpec 的颜色条放在主坐标轴的上方或左侧#

... 通过将 location="top" 或 location="left" 传递给 colorbar() 调用.

标题,刻度和标签#

supxlabel 和 supylabel#

可以使用新的 Figure.supxlabel 和 Figure.supylabel 方法,向整个图添加 x 和 y 标签,类似于 Figure.suptitle .

(Source code, png)

共享坐标轴 subplots 的刻度标签在顶部或左侧标签上的可见性现在已正确#

当调用 subplots(..., sharex=True, sharey=True) 时,Matplotlib 会自动隐藏不在第一列的坐标轴的 x 刻度标签,以及不在最后一行的坐标轴的 y 刻度标签.如果 rcParams 指定坐标轴的标签应该在顶部 ( rcParams["xtick.labeltop"] = True ) 或右侧 ( rcParams["ytick.labelright"] = True ),则此行为不正确.

现在可以正确处理以下情况(根据需要在第一行和最后一列的坐标轴上调整可见性):

plt.rcParams["xtick.labelbottom"] = False
plt.rcParams["xtick.labeltop"] = True
plt.rcParams["ytick.labelleft"] = False
plt.rcParams["ytick.labelright"] = True

fig, axs = plt.subplots(2, 2, sharex=True, sharey=True)

(Source code, png)

带有标签的可迭代对象可以传递给 Axes.plot#

当通过将 2D 数据作为 y 值传递给 plot 来绘制多个数据集时,数据集的标签可以作为列表传递,列表的长度与 y 中的列数匹配.

x = [1, 2, 3]

y = [[1, 2],
     [2, 5],
     [4, 9]]

plt.plot(x, y, label=['low', 'high'])
plt.legend()

(Source code, png)

字体和文本#

文本变换可以旋转文本方向#

新的 Text 参数 transform_rotates_text 现在设置变换的旋转是否影响文本方向.

../../_images/sphx_glr_text_rotation_relative_to_line_001.png

新 transform_rotates_text 参数的示例#

matplotlib.mathtext 现在支持 overset 和 underset LaTeX 符号#

mathtext 现在支持 overset 和 underset,调用方式为 \overset{annotation}{body} 或 \underset{annotation}{body} ,其中 annotation 是主体"上方"或"下方"的文本.

(Source code, png)

math_fontfamily 参数用于更改 Text 字体族#

新的 math_fontfamily 参数可用于更改绘图中每个单独文本元素的字体族.如果未设置参数,则将使用全局值 rcParams["mathtext.fontset"] (default: 'dejavusans') .

../../_images/sphx_glr_mathtext_fontfamily_example_001.png

TextArea / AnchoredText 支持 horizontalalignment#

现在可以指定 TextArea 或 AnchoredText 中文本的水平对齐方式,这对于多行文本最为有效:

(Source code, png)

PDF 支持 Text artists 上的 URL#

text.Text artists 上的 URL(即来自 Artist.set_url )现在将保存在 PDF 文件中.

rcParams 改进#

dates 的新 rcParams:设置 converter 以及是否使用 interval_multiples#

新的 rcParams["date.converter"] (default: 'auto') 允许分别使用字符串 'auto' 和 'concise' 在 matplotlib.dates.DateConverter 和 matplotlib.dates.ConciseDateConverter 之间切换.

新的 rcParams["date.interval_multiples"] (default: True) 允许在日期定位器尝试以设定的间隔(即,每月的 1 号和 15 号)选取刻度,与从时间序列开始的任何位置开始的均匀间隔的刻度之间切换:

dates = np.arange('2001-01-10', '2001-05-23', dtype='datetime64[D]')
y = np.sin(dates.astype(float) / 10)
fig, axs = plt.subplots(nrows=2, constrained_layout=True)

plt.rcParams['date.converter'] = 'concise'
plt.rcParams['date.interval_multiples'] = True
axs[0].plot(dates, y)

plt.rcParams['date.converter'] = 'auto'
plt.rcParams['date.interval_multiples'] = False
axs[1].plot(dates, y)

(Source code, png)

日期格式化器现在遵循 usetex rcParam#

AutoDateFormatter 和 ConciseDateFormatter 现在遵循 rcParams["text.usetex"] (default: False) ,因此将使用与默认(非日期)格式化器的 TeX 渲染一致的字体.也可以通过在创建格式化器实例时传递 usetex 参数来启用/禁用 TeX 渲染.

在下面的图中,x 轴(日期)和 y 轴(数字)现在都使用相同的 (TeX) 字体:

(Source code, png)

将 image.cmap 设置为 Colormap#

现在可以将 rcParams["image.cmap"] (default: 'viridis') 设置为 Colormap 实例,例如使用上面的 set_extremes 创建的 colormap.(这只能从 Python 代码中完成,不能从 matplotlibrc 文件中完成.)

可以使用 rcParams 独立设置刻度和刻度标签颜色#

以前, rcParams["xtick.color"] (default: 'black') 定义了刻度颜色和标签颜色.现在可以使用 rcParams["xtick.labelcolor"] (default: 'inherit') 独立设置标签颜色.它默认为 'inherit' ,它将从 rcParams["xtick.color"] (default: 'black') 中获取值. ytick.[label]color 也是如此.例如,要将刻度设置为浅灰色,将刻度标签设置为黑色,可以在脚本中使用以下代码:

import matplotlib as mpl

mpl.rcParams['xtick.labelcolor'] = 'lightgrey'
mpl.rcParams['xtick.color'] = 'black'
mpl.rcParams['ytick.labelcolor'] = 'lightgrey'
mpl.rcParams['ytick.color'] = 'black'

或者将以下行添加到 matplotlibrc 文件或 Matplotlib 样式文件中:

xtick.labelcolor : lightgrey
xtick.color      : black
ytick.labelcolor : lightgrey
ytick.color      : black

3D 轴改进#

3D 轴中的 Errorbar 方法#

errorbar 函数 Axes.errorbar 已完全移植到 3D 轴框架中,支持错误线和帽标记的自定义样式,对 errorbar 间距的控制,上限和下限标记等功能.

../../_images/sphx_glr_errorbar3d_001.png

3D 轴中的 Stem plots#

现在 3D 轴支持 Stem plots.与 2D stem plots 非常相似, stem 支持以各种方向绘制 stem:

(Source code, png)

另请参见 3D 茎图 演示.

3D Collection 属性现在可以修改#

以前,3D Collection 中用于 3D 效果的属性(例如,修改颜色以产生深度阴影)在创建后无法更改.

现在可以随时修改 3D Collection 的所有属性.

在 3D 轴中平移#

单击鼠标中键并拖动以平移 3D 轴.

交互式工具改进#

新的 RangeSlider 小部件#

widgets.RangeSlider 允许创建定义范围而不是单个值的滑块.

(Source code, png)

滑块现在可以捕捉到任意值#

Slider UI 小部件现在接受 valstep 的数组.这通过允许滑块捕捉到任意值来概括先前的行为.

暂停和恢复动画#

animation.Animation.pause 和 animation.Animation.resume 方法允许您暂停和恢复动画.这些方法可以用作 UI 元素上事件侦听器的回调,以便您的绘图可以具有一些回放控制 UI.

Sphinx 扩展#

plot_directive 标题选项#

以前,通过指定内容,在使用带有外部源文件的 plot_directive 指令时支持标题:

.. plot:: path/to/plot.py

    This is the caption for the plot.

:caption: 选项允许为 external:

.. plot:: path/to/plot.py
    :caption: This is the caption for the plot.

和 inline plots:

.. plot::
    :caption: This is a caption for the plot.

    plt.plot([1, 2, 3])

后端特定的改进#

现在合并连续的栅格化绘制#

可以使用 rasterized 关键字参数或 set_rasterized() 将向量输出的元素单独设置为栅格化.这对于减少文件大小很有用.对于具有多个栅格元素的图形,如果不会影响视觉输出,它们现在会自动合并为较少数量的位图.对于具有许多元素的情况,这可以显着减小文件大小.

为了确保这种情况发生,请不要在栅格元素之间放置向量元素.

要禁止此合并,请将 Figure.suppressComposite 设置为 True.

在 FFMpegFileWriter 中支持 raw/rgba 帧格式#

使用 FFMpegFileWriter 时,可以将 frame_format 设置为 "raw" 或 "rgba" ,这可能比图像格式稍快,因为 Matplotlib 和 FFmpeg 之间不需要进行编码/解码.

nbAgg/WebAgg 支持鼠标中键和双击#

nbAgg 和 WebAgg 后端现在支持双击事件.以前,WebAgg 会将鼠标中键事件报告为右键单击,但现在报告正确的按钮类型.

nbAgg 支持二进制通信#

如果 Web 浏览器和 Notebook 支持二进制 WebSockets,则 nbAgg 现在将使用它们来稍微改善图形显示的传输.

尽可能为 PDF 文件中的 PNG 图像使用索引颜色#

当 PNG 图像具有 256 种或更少的颜色时,它们会在保存到 PDF 中之前转换为索引颜色.在某些情况下,这可以显着减小文件大小.对于使用颜色映射但没有插值的栅格数据(例如 Healpy mollview 图)尤其如此.目前,这仅适用于 RGB 图像.

改进了 PDF/PS 中的字体子集化#

PDF 和 PostScript 中的字体子集化已从嵌入的 ttconv C 代码重写为 Python.一些复合字符和轮廓可能略有变化.这修复了 PDF 中的 ttc 子集化,并增加了对 type 3 OTF 字体子集化的支持,从而减少了文件大小(使用 CJK 字体时要小得多),并避免了 type 42 嵌入和某些 PDF 阅读器(如 Acrobat Reader)的问题.

将字距调整添加到 PDF 中的字符串#

与 Agg 后端中生成的文本一样(有关示例,请参见 the previous what's new entry ),PDF 现在在文本字符串中包含字距调整.

QtAgg 中的完全分数 HiDPI#

完全分数 HiDPI(即,非整数的 HiDPI 比率)已在 Qt 5.14 中添加,并且 QtAgg 后端在使用此版本或更新版本的 Qt 时现在支持它.

wxAgg 支持全屏切换#

wxAgg 后端支持使用 f 快捷键或管理器函数 FigureManagerBase.full_screen_toggle 切换全屏.

On this page