matplotlib.figure

matplotlib.figure 实现了以下类：

Figure

顶层 Artist，它包含了所有绘图元素。许多方法在 FigureBase 中实现。

SubFigure

图中的逻辑图形，通常通过 Figure.add_subfigure 或 Figure.subfigures 方法添加到图形（或父 SubFigure）中。

图形通常使用 pyplot 方法 figure、subplots 和 subplot_mosaic 创建。

fig, ax = plt.subplots(figsize=(2, 2), facecolor='lightskyblue',
                       layout='constrained')
fig.suptitle('Figure')
ax.set_title('Axes', loc='left', fontstyle='oblique', fontsize='medium')

(Source code, 2x.png, png)

某些情况下需要直接实例化一个 Figure 类，通常是在某种应用程序内部（参见 在图形用户界面中嵌入 Matplotlib 获取示例列表）。关于 Figure 的更多信息可以在 图表介绍 找到。

图

图类

Figure

所有绘图元素的顶级容器。

添加轴和子图

Figure.add_axes	将 Axes 添加到图形中。
Figure.add_subplot	将一个 Axes 添加到图形中作为子图布局的一部分。
Figure.subplots	向此图形添加一组子图。
Figure.subplot_mosaic	基于ASCII艺术或嵌套列表构建Axes布局。
Figure.add_gridspec	用于创建以该图形为父级的 GridSpec 的低级 API。
Figure.get_axes	图中的坐标轴列表。
Figure.axes	图中的坐标轴列表。
Figure.delaxes	从图形中移除 Axes ax ；更新当前的 Axes。
Figure.subfigures	将一组子图添加到此图或子图中。
Figure.add_subfigure	将一个 SubFigure 添加到图形中，作为子图布局的一部分。

保存

Figure.savefig

将当前图形保存为图像或矢量图形到文件中。

注释

Figure.colorbar	向绘图添加颜色条。
Figure.legend	在图上放置一个图例。
Figure.text	添加文本到图形。
Figure.suptitle	为图形添加一个居中的标题。
Figure.get_suptitle	返回副标题作为字符串，如果未设置则返回空字符串。
Figure.supxlabel	为图形添加一个居中的 supxlabel。
Figure.get_supxlabel	返回 supxlabel 作为字符串，如果未设置则返回空字符串。
Figure.supylabel	为图形添加一个居中的子标签。
Figure.get_supylabel	如果已设置，则返回 supylabel 作为字符串，否则返回空字符串。
Figure.align_labels	如果标签对齐是自动进行的（即标签位置未手动设置），则对齐同一子图行或列（分别）的x标签和y标签。
Figure.align_xlabels	如果标签对齐是自动进行的（即标签位置未手动设置），则在同一子图行中对齐子图的x标签。
Figure.align_ylabels	如果在同一子图列中自动进行标签对齐（即标签位置未手动设置），请对齐子图的y标签。
Figure.align_titles	如果在同一子图行中自动进行标题对齐（即标题位置未手动设置），则对齐子图的标题。
Figure.autofmt_xdate	日期刻度标签经常重叠，因此旋转它们并将它们右对齐是有用的。

图形几何

Figure.set_size_inches	设置图形尺寸（英寸）。
Figure.get_size_inches	返回当前图形的大小（以英寸为单位）。
Figure.set_figheight	设置图形的高度（以英寸为单位）。
Figure.get_figheight	返回图形的高度（英寸）。
Figure.set_figwidth	设置图像的宽度（以英寸为单位）。
Figure.get_figwidth	返回图形的宽度（英寸）。
Figure.dpi	每英寸的点数分辨率。
Figure.set_dpi	设置图像的分辨率，单位为每英寸点数。
Figure.set_dpi	设置图像的分辨率，单位为每英寸点数。

子图布局

Figure.subplots_adjust	调整子图布局参数。
Figure.set_layout_engine	设置此图形的布局引擎。
Figure.get_layout_engine

不鼓励或已弃用

Figure.tight_layout	调整子图之间和周围的填充。
Figure.set_tight_layout	[已弃用] 设置在绘图时是否以及如何调用 Figure.tight_layout。
Figure.get_tight_layout	返回在绘图时是否调用了 Figure.tight_layout。
Figure.set_constrained_layout	[已弃用] 设置在绘图时是否使用 constrained_layout。
Figure.get_constrained_layout	返回是否正在使用约束布局。
Figure.set_constrained_layout_pads	[已弃用] 设置 constrained_layout 的填充。
Figure.get_constrained_layout_pads	[已弃用] 获取 constrained_layout 的填充。

交互式

参见

• 事件处理

Figure.ginput	与图形交互的阻塞调用。
Figure.add_axobserver	每当 Axes 状态改变时，func(self) 将被调用。
Figure.waitforbuttonpress	阻塞调用以与图形交互。
Figure.pick	处理一个拾取事件。

修改外观

Figure.set_frameon	设置图形背景补丁的可见性，即是否绘制图形背景。
Figure.get_frameon	返回图形背景补丁的可见性，即是否绘制图形背景。
Figure.set_linewidth	设置图形矩形的线宽。
Figure.get_linewidth	获取图形矩形的线宽。
Figure.set_facecolor	设置图形矩形的面颜色。
Figure.get_facecolor	获取图形矩形的面部颜色。
Figure.set_edgecolor	设置图形矩形的边缘颜色。
Figure.get_edgecolor	获取图形矩形的边缘颜色。

添加和获取艺术家

Figure.add_artist	将一个 Artist 添加到图形中。
Figure.get_children	获取图中包含的艺术家的列表。
Figure.figimage	将一个非重采样的图像添加到图形中。

获取和修改状态

参见

• 交互式图表

Figure.clear	清除图形。
Figure.gca	获取当前的 Axes。
Figure.sca	将当前的 Axes 设置为 a 并返回 a。
Figure.get_tightbbox	返回图形 以英寸为单位 的（紧密）边界框。
Figure.get_window_extent	获取艺术家在显示空间中的边界框。
Figure.show	如果使用带有 pyplot 的 GUI 后端，显示图形窗口。
Figure.set_canvas	设置包含图形的画布
Figure.draw	使用给定的渲染器绘制艺术家（及其子元素）。
Figure.draw_without_rendering	绘制图形但不输出。
Figure.draw_artist	仅绘制 Artist a。

子图

Matplotlib 有一个 SubFigure 的概念，它是父 Figure 中的一个逻辑图形。它有许多与父图形相同的方法。参见 嵌套轴布局。

(Source code, 2x.png, png)

SubFigure 类

SubFigure

可以放置在图中的逻辑图形。

添加轴和子图

SubFigure.add_axes	将 Axes 添加到图形中。
SubFigure.add_subplot	将一个 Axes 添加到图形中作为子图布局的一部分。
SubFigure.subplots	向此图形添加一组子图。
SubFigure.subplot_mosaic	基于ASCII艺术或嵌套列表构建Axes布局。
SubFigure.add_gridspec	用于创建以该图形为父级的 GridSpec 的低级 API。
SubFigure.delaxes	从图形中移除 Axes ax ；更新当前的 Axes。
SubFigure.add_subfigure	将一个 SubFigure 添加到图形中，作为子图布局的一部分。
SubFigure.subfigures	将一组子图添加到此图或子图中。

注释

SubFigure.colorbar	向绘图添加颜色条。
SubFigure.legend	在图上放置一个图例。
SubFigure.text	添加文本到图形。
SubFigure.suptitle	为图形添加一个居中的标题。
SubFigure.get_suptitle	返回副标题作为字符串，如果未设置则返回空字符串。
SubFigure.supxlabel	为图形添加一个居中的 supxlabel。
SubFigure.get_supxlabel	返回 supxlabel 作为字符串，如果未设置则返回空字符串。
SubFigure.supylabel	为图形添加一个居中的子标签。
SubFigure.get_supylabel	如果已设置，则返回 supylabel 作为字符串，否则返回空字符串。
SubFigure.align_labels	如果标签对齐是自动进行的（即标签位置未手动设置），则对齐同一子图行或列（分别）的x标签和y标签。
SubFigure.align_xlabels	如果标签对齐是自动进行的（即标签位置未手动设置），则在同一子图行中对齐子图的x标签。
SubFigure.align_ylabels	如果在同一子图列中自动进行标签对齐（即标签位置未手动设置），请对齐子图的y标签。
SubFigure.align_titles	如果在同一子图行中自动进行标题对齐（即标题位置未手动设置），则对齐子图的标题。

添加和获取艺术家

SubFigure.add_artist	将一个 Artist 添加到图形中。
SubFigure.get_children	获取图中包含的艺术家的列表。

修改外观

SubFigure.set_frameon	设置图形背景补丁的可见性，即是否绘制图形背景。
SubFigure.get_frameon	返回图形背景补丁的可见性，即是否绘制图形背景。
SubFigure.set_linewidth	设置图形矩形的线宽。
SubFigure.get_linewidth	获取图形矩形的线宽。
SubFigure.set_facecolor	设置图形矩形的面颜色。
SubFigure.get_facecolor	获取图形矩形的面部颜色。
SubFigure.set_edgecolor	设置图形矩形的边缘颜色。
SubFigure.get_edgecolor	获取图形矩形的边缘颜色。

Passthroughs

SubFigure.set_dpi	设置父图的分辨率，单位为每英寸点数。
SubFigure.get_dpi	以每英寸点数（DPI）为单位返回父图的分辨率，作为浮点数。

FigureBase 父类

class matplotlib.figure.FigureBase(**kwargs)

包含向 Figure 和 SubFigure 添加艺术家、创建 Axes 等方法的基类。

add_artist(artist, clip=False)

将一个 Artist 添加到图形中。

通常，艺术家通过 Axes.add_artist 方法添加到 Axes 对象中；在需要直接将艺术家添加到图形中的罕见情况下，可以使用此方法。

参数:

艺术家 : Artist艺术家

要添加到图形中的艺术家。如果添加的艺术家之前没有设置变换，其变换将被设置为 figure.transSubfigure。

剪辑bool, 默认: False

添加的艺术家是否应被图形的补丁裁剪。

返回:

Artist

新增的艺术家。

add_axes(*args, **kwargs)

将 Axes 添加到图形中。

调用签名:

add_axes(rect, projection=None, polar=False, **kwargs)
add_axes(ax)

参数:

矩形元组 (左, 底, 宽, 高)

新 Axes 的尺寸（左、底、宽、高）。所有量都是图形宽度和高度的分数。

投影{None, 'aitoff', 'hammer', 'lambert', 'mollweide', 'polar', 'rectilinear', str}, 可选

Axes 的投影类型。str 是自定义投影的名称，参见 projections。默认的 None 结果是 'rectilinear' 投影。

极地bool, 默认: False

如果为真，等同于 projection='polar'。

axes_class : Axes 的子类类型, 可选子类类型

被实例化的 axes.Axes 子类。此参数与 projection 和 polar 不兼容。示例请参见 axisartist。

sharex, sharey : Axes, 可选Axes，可选

使用 sharex 和/或 sharey 共享 x 或 y axis。轴将具有与共享的 Axes 相同的限制、刻度和比例。

标签str

返回的 Axes 的标签。

返回:

Axes，或 Axes 的子类

返回的 Axes 类取决于所使用的投影。如果使用直角投影，则为 Axes；如果使用极坐标投影，则为 projections.polar.PolarAxes。

其他参数:

**kwargs

此方法还接受返回的 Axes 类的关键字参数。直角坐标系 Axes 类的关键字参数 Axes 可以在下表中找到，但如果使用其他投影，可能还会有其他关键字参数，请参阅实际的 Axes 类。

属性	描述
可调整	{'box', 'datalim'}
agg_filter	一个过滤函数，它接收一个 (m, n, 3) 浮点数组和一个 dpi 值，并返回一个 (m, n, 3) 数组和两个从图像左下角开始的偏移量
alpha	标量或无
锚点	(float, float) 或 {'C', 'SW', 'S', 'SE', 'E', 'NE', ...}
animated	布尔值
aspect	{'auto', 'equal'} 或 float
autoscale_on	布尔值
autoscalex_on	未知
autoscaley_on	未知
axes_locator	Callable[[Axes, Renderer], Bbox]
axisbelow	布尔值或 'line'
box_aspect	浮点数或无
clip_box	BboxBase 或 None
clip_on	布尔值
clip_path	补丁或（路径，变换）或无
facecolor 或 fc	color
figure	Figure 或 SubFigure
forward_navigation_events	布尔值或“自动”
frame_on	布尔值
gid	str
in_layout	布尔值
标签	对象
鼠标悬停	布尔值
导航	布尔值
navigate_mode	未知
path_effects	AbstractPathEffect 的列表
picker	None 或 bool 或 float 或 callable
position	[左, 底, 宽, 高] 或 Bbox
prop_cycle	Cycler
rasterization_zorder	浮点数或无
光栅化	布尔值
sketch_params	(scale: float, length: float, randomness: float)
snap	布尔值或无
subplotspec	未知
标题	str
transform	Transform
url	str
visible	布尔值
xbound	(下限: 浮点数, 上限: 浮点数)
xlabel	str
xlim	(左: 浮点数, 右: 浮点数)
xmargin	浮点数大于 -0.5
xscale	未知
xticklabels	未知
xticks	未知
ybound	(下限: 浮点数, 上限: 浮点数)
ylabel	str
ylim	(底部: 浮点数, 顶部: 浮点数)
ymargin	浮点数大于 -0.5
yscale	未知
yticklabels	未知
yticks	未知
zorder	float

参见

Figure.add_subplot

pyplot.subplot

pyplot.axes

Figure.subplots

pyplot.subplots

注释

在极少数情况下，add_axes 可能会被调用，其参数为一个已经在当前图形中创建但不在图形 Axes 列表中的 Axes 实例。

示例

一些简单的例子:

rect = l, b, w, h
fig = plt.figure()
fig.add_axes(rect)
fig.add_axes(rect, frameon=False, facecolor='g')
fig.add_axes(rect, polar=True)
ax = fig.add_axes(rect, projection='polar')
fig.delaxes(ax)
fig.add_axes(ax)

add_gridspec(nrows=1, ncols=1, **kwargs)

用于创建以该图形为父级的 GridSpec 的低级 API。

这是一个低级API，允许你创建一个gridspec并在其基础上添加子图。大多数用户不需要这种自由度，应该使用更高级的方法 subplots 或 subplot_mosaic。

参数:

nrowsint, 默认值: 1

网格中的行数。

ncolsint, 默认值: 1

网格中的列数。

返回:

GridSpec

其他参数:

**kwargs

关键字参数传递给 GridSpec。

参见

matplotlib.pyplot.subplots

示例

添加一个跨越两行的子图:

fig = plt.figure()
gs = fig.add_gridspec(2, 2)
ax1 = fig.add_subplot(gs[0, 0])
ax2 = fig.add_subplot(gs[1, 0])
# spans two rows:
ax3 = fig.add_subplot(gs[:, 1])

add_subfigure(subplotspec, **kwargs)

将一个 SubFigure 添加到图形中，作为子图布局的一部分。

参数:

subplotspecgridspec.SubplotSpec

定义子图将在父网格区域中放置的位置。

返回:

SubFigure

其他参数:

**kwargs

传递给 SubFigure 对象。

参见

Figure.subfigures

add_subplot(*args, **kwargs)

将一个 Axes 添加到图形中作为子图布局的一部分。

调用签名:

add_subplot(nrows, ncols, index, **kwargs)
add_subplot(pos, **kwargs)
add_subplot(ax)
add_subplot()

参数:

*args : int, (int, int, index), 或 SubplotSpec, 默认值: (1, 1, 1)int, (int, int, index), or SubplotSpec, default: (1, 1, 1)

由以下之一描述的子图的位置：

• 三个整数（nrows，ncols，index）。子图将占据一个具有*nrows*行和*ncols*列的网格中的*index*位置。index*从左上角的1开始，并向右增加。*index*也可以是一个二元组，指定子图的（*first，last）索引（基于1，并包括*last*），例如，fig.add_subplot(3, 1, (1, 2)) 创建一个跨越图表上部2/3的子图。

• 一个三位整数。这些数字被解释为如果分别给出三个一位整数，即 fig.add_subplot(235) 与 fig.add_subplot(2, 3, 5) 相同。请注意，这只能用于不超过9个子图的情况。

• 一个 SubplotSpec。

在极少数情况下，add_subplot 可能会被调用，参数为一个已经在当前图形中创建但不在图形 Axes 列表中的子图 Axes 实例。

投影{None, 'aitoff', 'hammer', 'lambert', 'mollweide', 'polar', 'rectilinear', str}, 可选

子图的投影类型 (Axes)。str 是自定义投影的名称，参见 projections。默认值 None 会导致 'rectilinear' 投影。

极地bool, 默认: False

如果为真，等同于 projection='polar'。

axes_class : Axes 的子类类型, 可选子类类型

被实例化的 axes.Axes 子类。此参数与 projection 和 polar 不兼容。示例请参见 axisartist。

sharex, sharey : Axes, 可选Axes，可选

使用 sharex 和/或 sharey 共享 x 或 y axis。轴将具有与共享的 Axes 相同的限制、刻度和比例。

标签str

返回的 Axes 的标签。

返回:

Axes

子图的轴。返回的轴实际上可以是子类的实例，例如极坐标投影的 projections.polar.PolarAxes。

其他参数:

**kwargs

此方法还接受返回的 Axes 基类的关键字参数；除了 figure 参数。直角坐标系基类 Axes 的关键字参数可以在下表中找到，但如果使用其他投影，可能还会有其他关键字参数。

属性	描述
可调整	{'box', 'datalim'}
agg_filter	一个过滤函数，它接收一个 (m, n, 3) 浮点数组和一个 dpi 值，并返回一个 (m, n, 3) 数组和两个从图像左下角开始的偏移量
alpha	标量或无
锚点	(float, float) 或 {'C', 'SW', 'S', 'SE', 'E', 'NE', ...}
animated	布尔值
aspect	{'auto', 'equal'} 或 float
autoscale_on	布尔值
autoscalex_on	未知
autoscaley_on	未知
axes_locator	Callable[[Axes, Renderer], Bbox]
axisbelow	布尔值或 'line'
box_aspect	浮点数或无
clip_box	BboxBase 或 None
clip_on	布尔值
clip_path	补丁或（路径，变换）或无
facecolor 或 fc	color
figure	Figure 或 SubFigure
forward_navigation_events	布尔值或“自动”
frame_on	布尔值
gid	str
in_layout	布尔值
标签	对象
鼠标悬停	布尔值
导航	布尔值
navigate_mode	未知
path_effects	AbstractPathEffect 的列表
picker	None 或 bool 或 float 或 callable
position	[左, 底, 宽, 高] 或 Bbox
prop_cycle	Cycler
rasterization_zorder	浮点数或无
光栅化	布尔值
sketch_params	(scale: float, length: float, randomness: float)
snap	布尔值或无
subplotspec	未知
标题	str
transform	Transform
url	str
visible	布尔值
xbound	(下限: 浮点数, 上限: 浮点数)
xlabel	str
xlim	(左: 浮点数, 右: 浮点数)
xmargin	浮点数大于 -0.5
xscale	未知
xticklabels	未知
xticks	未知
ybound	(下限: 浮点数, 上限: 浮点数)
ylabel	str
ylim	(底部: 浮点数, 顶部: 浮点数)
ymargin	浮点数大于 -0.5
yscale	未知
yticklabels	未知
yticks	未知
zorder	float

参见

Figure.add_axes

pyplot.subplot

pyplot.axes

Figure.subplots

pyplot.subplots

示例

fig = plt.figure()

fig.add_subplot(231)
ax1 = fig.add_subplot(2, 3, 1)  # equivalent but more general

fig.add_subplot(232, frameon=False)  # subplot with no frame
fig.add_subplot(233, projection='polar')  # polar subplot
fig.add_subplot(234, sharex=ax1)  # subplot sharing x-axis with ax1
fig.add_subplot(235, facecolor="red")  # red subplot

ax1.remove()  # delete ax1 from the figure
fig.add_subplot(ax1)  # add ax1 back to the figure

align_labels(axs=None)

如果标签对齐是自动进行的（即标签位置未手动设置），则对齐同一子图行或列（分别）的x标签和y标签。

调用此方法后，对齐方式在绘制事件中保持不变。

参数:

axs : Axes 的列表列表

可选的列表（或 ndarray），包含要对其标签的 Axes。默认是对齐图中的所有 Axes。

参见

matplotlib.figure.Figure.align_xlabels

matplotlib.figure.Figure.align_ylabels

matplotlib.figure.Figure.align_titles

align_titles(axs=None)

如果在同一子图行中自动进行标题对齐（即标题位置未手动设置），则对齐子图的标题。

调用此方法后，对齐方式在绘制事件中保持不变。

参数:

axs : Axes 的列表列表

可选的 Axes 列表（或 ndarray）以对齐标题。默认是对齐图中的所有 Axes。

参见

matplotlib.figure.Figure.align_xlabels

matplotlib.figure.Figure.align_ylabels

matplotlib.figure.Figure.align_labels

注释

这假设 axs 来自同一个 GridSpec，因此它们的 SubplotSpec 位置对应于图形位置。

示例

带有标题的示例:

fig, axs = plt.subplots(1, 2)
axs[0].set_aspect('equal')
axs[0].set_title('Title 0')
axs[1].set_title('Title 1')
fig.align_titles()

align_xlabels(axs=None)

如果标签对齐是自动进行的（即标签位置未手动设置），则在同一子图行中对齐子图的x标签。

调用此方法后，对齐方式在绘制事件中保持不变。

如果标签位于底部，它将与那些标签也在底部的 Axes 对齐，并且这些 Axes 位于相同的底部子图行。如果标签位于顶部，它将与那些位于相同顶部行的 Axes 的标签对齐。

参数:

axs : Axes 的列表列表

可选的 Axes 列表（或 ndarray），用于对齐 xlabels。默认情况下，将对齐图中的所有 Axes。

参见

matplotlib.figure.Figure.align_ylabels

matplotlib.figure.Figure.align_titles

matplotlib.figure.Figure.align_labels

注释

这假设 axs 来自同一个 GridSpec，因此它们的 SubplotSpec 位置对应于图形位置。

示例

带有旋转的xtick标签的示例:

fig, axs = plt.subplots(1, 2)
for tick in axs[0].get_xticklabels():
    tick.set_rotation(55)
axs[0].set_xlabel('XLabel 0')
axs[1].set_xlabel('XLabel 1')
fig.align_xlabels()

align_ylabels(axs=None)

如果在同一子图列中自动进行标签对齐（即标签位置未手动设置），请对齐子图的y标签。

调用此方法后，对齐方式在绘制事件中保持不变。

如果标签在左侧，它将与左侧标签对齐，这些标签位于具有相同最左侧子图列的Axes上。如果标签在右侧，它将与具有相同最右侧列的Axes上的标签对齐。

参数:

axs : Axes 的列表列表

可选的列表（或 ndarray），包含要对其 ylabels 的 Axes。默认情况下，图中的所有 Axes 都会对齐。

参见

matplotlib.figure.Figure.align_xlabels

matplotlib.figure.Figure.align_titles

matplotlib.figure.Figure.align_labels

注释

这假设 axs 来自同一个 GridSpec，因此它们的 SubplotSpec 位置对应于图形位置。

示例

带有大刻度标签的示例:

fig, axs = plt.subplots(2, 1)
axs[0].plot(np.arange(0, 1000, 50))
axs[0].set_ylabel('YLabel 0')
axs[1].set_ylabel('YLabel 1')
fig.align_ylabels()

autofmt_xdate(bottom=0.2, rotation=30, ha='right', which='major')

日期刻度标签经常重叠，因此旋转它们并右对齐它们是有用的。此外，一个常见的用例是具有共享x轴的多个子图，其中x轴是日期数据。刻度标签通常很长，因此在底部子图上旋转它们并在其他子图上关闭它们，以及关闭x轴标签是有帮助的。

参数:

底部float, 默认值: 0.2

subplots_adjust 的子图底部。

旋转浮动，默认：30度

xtick 标签的旋转角度，单位为度。

哈哈{'left', 'center', 'right'}, 默认: 'right'

xticklabels 的水平对齐方式。

哪个{'major', 'minor', 'both'}, 默认: 'major'

选择要旋转的刻度标签。

clear(keep_observers=False)

清除图形。

参数:

keep_observersbool, 默认: False

如果, 例如, 一个 gui 小部件正在跟踪图中的 Axes, 请将 keep_observers 设置为 True。

clf(keep_observers=False)

[不推荐] clear() 方法的别名。

不鼓励

不推荐使用 clf()。请改用 clear()。

参数:

keep_observersbool, 默认: False

如果, 例如, 一个 gui 小部件正在跟踪图中的 Axes, 请将 keep_observers 设置为 True。

colorbar(mappable, cax=None, ax=None, use_gridspec=True, **kwargs)

向绘图添加颜色条。

参数:

可映射的

matplotlib.cm.ScalarMappable`（即 `.AxesImage、ContourSet 等）由这个颜色条描述。这个参数对于 Figure.colorbar 方法是必需的，但对于 pyplot.colorbar 函数是可选的，它会默认设置为当前图像。

注意，可以“即时”创建一个 ScalarMappable 来生成不附加到先前绘制的艺术家的颜色条，例如

fig.colorbar(cm.ScalarMappable(norm=norm, cmap=cmap), ax=ax)

cax : Axes, 可选Axes，可选

将绘制颜色条的轴。如果为 None，则将创建一个新的轴，并且其空间将从 ax 中指定的轴中窃取。

ax : Axes 或可迭代对象或 Axes 的 numpy.ndarray，可选坐标轴或可迭代对象或坐标轴的numpy数组，可选

将被偷取空间以创建新颜色条轴的一个或多个父轴。仅当未设置 cax 时，此参数才被使用。

默认为包含用于创建颜色条的可映射对象的坐标轴。

use_gridspecbool, 可选

如果 cax 是 None，则创建一个新的 cax 作为 Axes 的实例。如果 ax 使用 subplotspec 定位并且 use_gridspec 是 True，那么 cax 也会使用 subplotspec 定位。

返回:

colorbar颜色条

其他参数:

位置None 或 {'left', 'right', 'top', 'bottom'}

颜色条坐标轴相对于父坐标轴的位置。它还决定了颜色条的 方向 （左侧和右侧的颜色条是垂直的，顶部和底部的颜色条是水平的）。如果为 None，位置将根据 方向 设置（垂直颜色条在右侧，水平颜色条在底部），如果 方向 未设置，则默认为 '右侧'。

方向None 或 {'vertical', 'horizontal'}

颜色条的方向。最好设置颜色条的 位置 ，因为这同时也决定了 方向 ；为 位置 和 方向 传递不兼容的值会引发异常。

分数float, 默认值: 0.15

用于颜色条的原始轴的比例。

收缩float, 默认值: 1.0

颜色条大小的乘数。

方面float, 默认值: 20

长宽比。

填充float, 默认值: 如果垂直为0.05, 如果水平为0.15

颜色条和新图像轴之间原始轴的分数。

锚点(浮点数, 浮点数), 可选

颜色条 Axes 的锚点。如果垂直，默认值为 (0.0, 0.5)；如果水平，默认值为 (0.5, 1.0)。

panchor : (float, float), 或 False, 可选（浮点数，浮点数），或

颜色条父坐标轴的锚点。如果为 False，父坐标轴的锚点将保持不变。默认为垂直时为 (1.0, 0.5)；水平时为 (0.5, 0.0)。

扩展{'neither', 'both', 'min', 'max'}

为超出范围的值创建尖端（除非选择'neither'）。这些是通过使用颜色图的set_under和set_over方法为给定颜色图设置的。

extendfractoctree 是一个 reStructuredText 指令 ，这是一个非常多功能的标记。指令可以有参数、选项和内容。

如果设置为 None，最小和最大三角形颜色条扩展的长度都将为内部颜色条长度的 5%（这是默认设置）。

如果设置为 'auto'，则使三角形颜色条扩展与内部方框长度相同（当 spacing 设置为 'uniform' 时）或与各自相邻的内部方框长度相同（当 spacing 设置为 'proportional' 时）。

如果是一个标量，表示最小和最大三角形颜色条扩展的长度，作为内部颜色条长度的分数。也可以给出一个两元素的分数序列，分别表示最小和最大颜色条扩展的长度，作为内部颜色条长度的分数。

extendrect布尔值

如果 False ，颜色条的最小和最大扩展将是三角形的（默认）。如果 True ，扩展将是矩形的。

间距{'均匀', '比例'}

对于离散色条（BoundaryNorm 或等高线），'uniform' 给每个颜色分配相同的空间；'proportional' 使空间与数据区间成比例。

刻度None 或刻度列表或定位器

如果为 None，刻度将根据输入自动确定。

格式None 或 str 或 Formatter

如果为 None，则使用 ScalarFormatter。支持格式字符串，例如 "%4.2e" 或 "{x:.2e}"。也可以提供一个替代的 Formatter。

drawedges布尔值

是否在颜色边界处绘制线条。

标签str

颜色条长轴上的标签。

边界, 值无或序列

如果未设置，色图将显示在0-1的刻度上。如果是序列，values 的长度必须比 boundaries 少1。对于由 boundaries 中相邻条目分隔的每个区域，将使用映射到 values 中相应值的颜色。通常仅对索引颜色（即 norm=NoNorm()）或其他不寻常的情况有用。

注释

如果 mappable 是一个 ContourSet，它的 extend kwarg 会自动包含在内。

shrink kwarg 提供了一种简单的方法来相对于 Axes 缩放颜色条。请注意，如果指定了 cax，它将决定颜色条的大小，而 shrink 和 aspect 将被忽略。

为了更精确的控制，你可以手动指定绘制可映射对象和颜色条的轴对象的位置。在这种情况下，不要使用任何轴属性关键字参数。

已知一些矢量图形查看器（svg 和 pdf）在颜色条的段之间渲染出白色间隙。这是由于查看器中的错误，而不是 Matplotlib 的问题。作为一种解决方法，颜色条可以渲染为重叠的段:

cbar = colorbar()
cbar.solids.set_edgecolor("face")
draw()

然而，在其他情况下，这会产生负面后果，例如在半透明图像（alpha < 1）和颜色条扩展的情况下；因此，默认情况下不使用此解决方法（参见问题 #1188）。

contains(mouseevent)

测试鼠标事件是否发生在图形上。

返回:

布尔值, {}

delaxes(ax)

从图形中移除 Axes ax ；更新当前的 Axes。

draw(renderer)

使用给定的渲染器绘制艺术家（及其子元素）。

如果艺术家不可见（Artist.get_visible 返回 False），则此操作无效。

参数:

渲染器 : RendererBase 子类。RendererBase 子类。

注释

此方法在 Artist 子类中被重写。

property figure

根 Figure。要获取 SubFigure 的父级，请使用 get_figure 方法。

property frameon

返回图形背景补丁的可见性，即是否绘制图形背景。等同于 Figure.patch.get_visible()。

gca()

获取当前的 Axes。

如果当前这个 Figure 中没有 Axes，则使用 Figure.add_subplot 创建一个新的 Axes。（要测试当前 Figure 中是否有 Axes，检查 figure.axes 是否为空。要测试当前 pyplot 的 figure 堆栈中是否有 Figure，检查 pyplot.get_fignums() 是否为空。）

get_children()

获取图中包含的艺术家的列表。

get_default_bbox_extra_artists()

返回通常用于 Figure.get_tightbbox 的艺术家列表。

get_edgecolor()

获取图形矩形的边缘颜色。

get_facecolor()

获取图形矩形的面部颜色。

get_figure(root=None)

返回 (Sub)Figure 所属的 Figure 或 SubFigure 实例。

参数:

根bool, 默认=True

如果为 False，返回该艺术家所在的 (子)图。如果为 True，返回子图嵌套树的根图。

自 3.10 版本弃用: 从版本 3.12 开始，root 将默认为 False。

get_frameon()

返回图形背景补丁的可见性，即是否绘制图形背景。等同于 Figure.patch.get_visible()。

get_linewidth()

获取图形矩形的线宽。

get_suptitle()

返回副标题作为字符串，如果未设置则返回空字符串。

get_supxlabel()

返回 supxlabel 作为字符串，如果未设置则返回空字符串。

get_supylabel()

如果已设置，则返回 supylabel 作为字符串，否则返回空字符串。

get_tightbbox(renderer=None, *, bbox_extra_artists=None)

返回图形 以英寸为单位 的（紧密）边界框。

注意，FigureBase 与其他所有艺术家不同，后者返回其 Bbox 以像素为单位。

设置了 artist.set_in_layout(False) 的艺术家不会被包含在边界框中。

参数:

渲染器 : RendererBase 子类RendererBase 子类

用于绘制图形（即 fig.canvas.get_renderer()）的渲染器

bbox_extra_artists : Artist 列表或 None列表

要包含在紧密边界框中的艺术家列表。如果为 ``None``（默认），则每个 Axes 的所有艺术家子对象都包含在紧密边界框中。

返回:

BboxBase

包含边界框（以图英寸为单位）。

get_window_extent(renderer=None)

获取艺术家在显示空间中的边界框。

边界框的宽度和高度是非负的。

子类应覆盖以包含在边界框“紧”计算中。默认是返回位于0, 0的空边界框。

使用此功能时要小心，如果艺术家的窗口范围发生变化，结果将不会更新。范围可能会因变换堆栈中的任何更改而改变，例如更改轴的限制、图形大小或使用的画布（如在保存图形时所做的那样）。这可能导致意外行为，即交互式图形在屏幕上看起来正常，但保存时会出现错误。

legend(*args, **kwargs)

在图上放置一个图例。

调用签名:

legend()
legend(handles, labels)
legend(handles=handles)
legend(labels)

调用签名对应于以下不同的使用此方法的方式：

1. 自动检测需要在图例中显示的元素

当你不传入任何额外参数时，要添加到图例中的元素会自动确定。

在这种情况下，标签取自艺术家。您可以在创建艺术家时指定它们，或者通过调用艺术家的 set_label() 方法来指定:

ax.plot([1, 2, 3], label='Inline label')
fig.legend()

或:

line, = ax.plot([1, 2, 3])
line.set_label('Label via method')
fig.legend()

可以通过定义一个以下划线开头的标签来排除特定行从自动图例元素选择中。这是所有艺术家的默认设置，因此在没有参数且未手动设置标签的情况下调用 Figure.legend 将不会绘制任何图例。

2. 在图例中显式列出艺术家和标签

为了完全控制哪些艺术家有图例条目，可以分别传递一个图例艺术家迭代器和一个图例标签迭代器:

fig.legend([line1, line2, line3], ['label1', 'label2', 'label3'])

3. 在图例中显式列出艺术家

这与2类似，但标签取自艺术家的标签属性。例如:

line1, = ax1.plot([1, 2, 3], label='label1')
line2, = ax2.plot([1, 2, 3], label='label2')
fig.legend(handles=[line1, line2])

4. 标记现有图元素

不鼓励

不推荐使用此调用签名，因为绘图元素与标签之间的关系仅通过它们的顺序隐式表示，容易混淆。

要为所有 Axes 上的所有艺术家创建图例，请使用字符串的可迭代对象调用此函数，每个图例项对应一个字符串。例如:

fig, (ax1, ax2) = plt.subplots(1, 2)
ax1.plot([1, 3, 5], color='blue')
ax2.plot([2, 4, 6], color='red')
fig.legend(['the blues', 'the reds'])

参数:

handles : Artist 的列表, 可选列表

要添加到图例中的艺术家（线条、补丁）列表。如果需要完全控制图例中显示的内容，并且上述自动机制不足够时，请与 labels 一起使用。

在这种情况下，句柄和标签的长度应该相同。如果它们不同，则会被截断为较短的长度。

标签list of str, 可选

要在艺术家旁边显示的标签列表。如果需要完全控制图例中显示的内容，并且上述自动机制不足以满足需求，请与 handles 一起使用此选项。

返回:

Legend

其他参数:

locstr 或一对浮点数，默认值：'右上角'

图例的位置。

字符串 'upper left', 'upper right', 'lower left', 'lower right' 将图例放置在图形相应的角落。

字符串 'upper center', 'lower center', 'center left', 'center right' 将图例放置在图形相应边缘的中心。

字符串 'center' 将图例放置在图形的中心。

位置也可以是一个2元组，给出图例在图坐标中左下角的坐标（在这种情况下，bbox_to_anchor 将被忽略）。

为了向后兼容，'center right'``（但没有其他位置）也可以拼写为'right'``，并且每个“字符串”位置也可以用数值表示：

位置字符串	位置代码
'最佳' (仅限Axes)	0
'右上角'	toctree 是一个 reStructuredText 指令 ，这是一个非常多功能的标记。指令可以有参数、选项和内容。
'左上角'	2
'左下'	3
'右下角'	4
'右'	5
'居中 左'	6
'居中右'	7
'lower center'	8
'上中'	9
'中心'	10

如果一个图形使用了约束布局管理器，loc 关键字参数的字符串代码可以通过使用前缀 'outside' 获得更好的布局行为。在角落处存在歧义，因此 'outside upper right' 将在布局中为图例在其余轴的上方留出空间，而 'outside right upper' 将在布局的右侧留出空间。除了上述 loc 的值外，我们还有 'outside right upper'、'outside right lower'、'outside left upper' 和 'outside left lower'。更多详情请参见 图例指南。

bbox_to_anchor : BboxBase, 2-tuple, 或 4-tuple of floatsBboxBase, 2-tuple, 或 4-tuple 的浮点数

用于与 loc 一起定位图例的框。默认为 axes.bbox``（如果作为 `.Axes.legend` 的方法调用）或 ``figure.bbox``（如果 ``figure.legend）。此参数允许图例的任意放置。

Bbox 坐标在由 bbox_transform 给出的坐标系中解释，默认转换为 Axes 或 Figure 坐标，具体取决于调用 legend 的对象。

如果给定一个4元组或 BboxBase ，那么它指定图例放置的bbox (x, y, width, height)。要将图例放置在Axes（或图形）右下象限的最佳位置:

loc='best', bbox_to_anchor=(0.5, 0., 0.5, 0.5)

一个 2-元组 (x, y) 将由 loc 指定的图例角放置在 x, y 处。例如，要将图例的右上角放置在 Axes（或图）的中心，可以使用以下关键字:

loc='upper right', bbox_to_anchor=(0.5, 0.5)

ncolsint, 默认值: 1

图例所占的列数。

为了向后兼容，拼写 ncol 也被支持，但不推荐使用。如果两者都给出，ncols 优先。

prop : 无或 FontProperties 或字典无或

图例的字体属性。如果为 None（默认），将使用当前的 matplotlib.rcParams。

字体大小int 或 {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}

图例的字体大小。如果值是数字，则大小将是绝对字体大小（以点为单位）。字符串值相对于当前默认字体大小。此参数仅在未指定 prop 时使用。

labelcolor : str 或 list, 默认值: rcParams["legend.labelcolor"] (default: 'None')str 或 list, 默认:

图例中文本的颜色。可以是有效的颜色字符串（例如，'红色'），或者是颜色字符串的列表。labelcolor 也可以设置为与线条或标记的颜色相匹配，使用 'linecolor'、'markerfacecolor'（或 'mfc'），或 'markeredgecolor'（或 'mec'）。

标签颜色可以通过 rcParams["legend.labelcolor"] (default: 'None') 全局设置。如果为 None，则使用 rcParams["text.color"] (default: 'black')。

numpoints : int, 默认值: rcParams["legend.numpoints"] (default: 1)int, 默认值:

在为 `.Line2D`（线）创建图例条目时，图例中的标记点数量。

scatterpoints : int, 默认值: rcParams["legend.scatterpoints"] (default: 1)int, 默认值:

在为 `.PathCollection`（散点图）创建图例条目时，图例中的标记点数量。

scatteryoffsets : 浮点数可迭代对象, 默认值: [0.375, 0.5, 0.3125]浮点数的可迭代对象，默认值：

散点图图例条目创建的标记的垂直偏移（相对于字体大小）。0.0 在图例文本的底部，1.0 在顶部。要使所有标记在同一高度绘制，请设置为 [0.5]。

markerscale : float, 默认值: rcParams["legend.markerscale"] (default: 1.0)浮点数, 默认:

图例标记相对于最初绘制的标记的相对大小。

markerfirstbool, 默认: True

如果 True，图例标记放置在图例标签的左侧。如果 False，图例标记放置在图例标签的右侧。

反向bool, 默认: False

如果 True，图例标签按输入的反序显示。如果 False，图例标签按输入的顺序显示。

Added in version 3.7.

frameon : bool, 默认值: rcParams["legend.frameon"] (default: True)bool, 默认值:

图例是否应绘制在补丁（框架）上。

fancybox : bool, 默认值: rcParams["legend.fancybox"] (default: True)bool, 默认值:

是否应在构成图例背景的 FancyBboxPatch 周围启用圆角。

shadow : None, bool 或 dict, 默认值: rcParams["legend.shadow"] (default: False)None, bool 或 dict, 默认:

是否在图例后面绘制阴影。阴影可以使用 Patch 关键字进行配置。目前不支持通过 rcParams["legend.shadow"] (default: False) 进行自定义。

framealpha : float, 默认值: rcParams["legend.framealpha"] (default: 0.8)浮点数, 默认:

图例背景的透明度。如果启用了 shadow 并且 framealpha 为 None，则忽略默认值。

facecolor : "inherit" 或颜色, 默认: rcParams["legend.facecolor"] (default: 'inherit')“继承”或颜色，默认：

图例的背景颜色。如果为 "inherit"，则使用 rcParams["axes.facecolor"] (default: 'white')。

edgecolor : "inherit" 或颜色, 默认: rcParams["legend.edgecolor"] (default: '0.8')“继承”或颜色，默认：

图例背景补丁边缘颜色。如果为 "inherit"，则使用 rcParams["axes.edgecolor"] (default: 'black')。

模式expand, None

如果 mode 设置为 "expand"，图例将会水平扩展以填充 Axes 区域（如果定义了 bbox_to_anchor，则填充其定义的图例大小）。

bbox_transform : None 或 Transform无或

边界框的变换（bbox_to_anchor）。对于值 ``None``（默认），将使用 Axes 的 transAxes 变换。

标题str 或 None

图例的标题。默认无标题 (None)。

title_fontproperties : None 或 FontProperties 或 dict无或

图例标题的字体属性。如果为 None（默认），将使用 title_fontsize 参数（如果存在）；如果 title_fontsize 也为 None，则将使用当前的 rcParams["legend.title_fontsize"] (default: None)。

title_fontsize : int 或 {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}, 默认值: rcParams["legend.title_fontsize"] (default: None)int 或 {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}，默认值：

图例标题的字体大小。注意：这不能与 title_fontproperties 结合使用。如果你想在设置其他字体属性时设置字体大小，请在 title_fontproperties 中使用 size 参数。

对齐{'center', 'left', 'right'}, 默认: 'center'

图例标题和条目框的对齐方式。条目作为一个整体块对齐，以便标记始终对齐。

borderpad : float, 默认值: rcParams["legend.borderpad"] (default: 0.4)浮点数, 默认:

图例边框内的分数空白，以字体大小为单位。

labelspacing : float, 默认值: rcParams["legend.labelspacing"] (default: 0.5)浮点数, 默认:

图例条目之间的垂直空间，以字体大小为单位。

handlelength : float, 默认值: rcParams["legend.handlelength"] (default: 2.0)浮点数, 默认:

图例句柄的长度，以字体大小单位表示。

handleheight : float, 默认值: rcParams["legend.handleheight"] (default: 0.7)浮点数, 默认:

图例句柄的高度，以字体大小单位表示。

handletextpad : float, 默认值: rcParams["legend.handletextpad"] (default: 0.8)浮点数, 默认:

图例句柄和文本之间的填充，以字体大小为单位。

borderaxespad : float, 默认值: rcParams["legend.borderaxespad"] (default: 0.5)浮点数, 默认:

Axes 和图例边框之间的填充，以字体大小为单位。

columnspacing : float, 默认值: rcParams["legend.columnspacing"] (default: 2.0)浮点数, 默认:

列之间的间距，以字体大小为单位。

handler_map字典或无

自定义字典，将实例或类型映射到图例处理程序。这个 handler_map 更新了在 matplotlib.legend.Legend.get_legend_handler_map 中找到的默认处理程序映射。

可拖动bool, 默认: False

图例是否可以用鼠标拖动。

参见

Axes.legend

注释

此功能不支持某些艺术家。详情请参阅 图例指南。

sca(a)

将当前的 Axes 设置为 a 并返回 a。

set(*, agg_filter=<UNSET>, alpha=<UNSET>, animated=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, edgecolor=<UNSET>, facecolor=<UNSET>, frameon=<UNSET>, gid=<UNSET>, in_layout=<UNSET>, label=<UNSET>, linewidth=<UNSET>, mouseover=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, rasterized=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, zorder=<UNSET>)

一次性设置多个属性。

支持的属性有

属性	描述
agg_filter	一个过滤函数，它接收一个 (m, n, 3) 浮点数组和一个 dpi 值，并返回一个 (m, n, 3) 数组和两个从图像左下角开始的偏移量
alpha	标量或无
animated	布尔值
clip_box	BboxBase 或 None
clip_on	布尔值
clip_path	补丁或（路径，变换）或无
edgecolor	color
facecolor	color
figure	未知
frameon	布尔值
gid	str
in_layout	布尔值
标签	对象
linewidth	数字
鼠标悬停	布尔值
path_effects	AbstractPathEffect 的列表
picker	None 或 bool 或 float 或 callable
光栅化	布尔值
sketch_params	(scale: float, length: float, randomness: float)
snap	布尔值或无
transform	Transform
url	str
visible	布尔值
zorder	float

set_edgecolor(color)

设置图形矩形的边缘颜色。

参数:

颜色 : color颜色

set_facecolor(color)

设置图形矩形的面颜色。

参数:

颜色 : color颜色

set_figure(fig)

自 3.10 版本弃用: 目前，如果 fig 不是此（子）图形所在的根 Figure，此方法将引发异常。未来它将始终引发异常。

set_frameon(b)

设置图形背景补丁的可见性，即是否绘制图形背景。等同于 Figure.patch.set_visible()。

参数:

b布尔值

set_linewidth(linewidth)

设置图形矩形的线宽。

参数:

行宽数字

subfigures(nrows=1, ncols=1, squeeze=True, wspace=None, hspace=None, width_ratios=None, height_ratios=None, **kwargs)

将一组子图添加到此图或子图中。

子图具有与图形相同的艺术家方法，并且在逻辑上与图形相同，但不能自行打印。请参阅 图子图。

在 3.10 版本发生变更: 子图现在按行优先顺序添加。

参数:

nrows, ncolsint, 默认值: 1

子图网格的行数/列数。

挤压bool, 默认: True

如果为 True，则从返回的子图数组中挤压出额外的维度。

wspace, hspace浮点数，默认值：None

子图之间保留的宽度/高度的量，表示为子图平均宽度/高度的分数。如果没有给出，如果使用约束布局（参见 ConstrainedLayoutEngine），则将从 rcParams 推断这些值，否则如果没有使用布局引擎，则为零。

width_ratios : 长度为 ncols 的类数组对象, 可选长度为的类数组

定义列的相对宽度。每一列的相对宽度为 width_ratios[i] / sum(width_ratios)。如果没有给出，所有列将具有相同的宽度。

height_ratios : 长度为 nrows 的类数组对象, 可选长度为的类数组

定义行的相对高度。每行的高度为 height_ratios[i] / sum(height_ratios)。如果未指定，所有行将具有相同的高度。

subplot_mosaic(mosaic, *, sharex=False, sharey=False, width_ratios=None, height_ratios=None, empty_sentinel='.', subplot_kw=None, per_subplot_kw=None, gridspec_kw=None)

基于ASCII艺术或嵌套列表构建Axes布局。

这是一个用于直观构建复杂 GridSpec 布局的辅助函数。

请参阅 复杂且语义化的图形组合 (subplot_mosaic) 以获取示例和完整的API文档

参数:

马赛克列表的列表 {可哈希或嵌套} 或字符串

你希望的 Axes 排列的视觉布局，标记为字符串。例如

x = [['A panel', 'A panel', 'edge'],
     ['C panel', '.',       'edge']]

生成 4 个 Axes：

• '一个面板'，高度为1行，跨度为前两列

• 'edge' 是两行高，并且位于右侧边缘

• 'C 面板' 位于左下角，占据一行一列的宽度

• 底部中心的一个1行1列的空白空间

布局中的任何条目都可以是相同形式的列表的列表，以创建嵌套布局。

如果输入是字符串，那么它可以是一个多行字符串，形式为

'''
AAE
C.E
'''

其中每个字符是一列，每行是一行。或者它可以是一个单行字符串，其中行由 ; 分隔:

'AB;CC'

字符串表示法仅允许单字符轴标签，不支持嵌套，但非常简洁。

Axes 标识符可以是 str 或不可迭代的可哈希对象（例如 tuple 不能使用）。

sharex, shareybool, 默认: False

如果为 True，x 轴 (sharex) 或 y 轴 (sharey) 将在所有子图中共享。在这种情况下，刻度标签可见性和轴单位的行为与 subplots 相同。如果为 False，每个子图的 x 轴或 y 轴将是独立的。

width_ratios : 长度为 ncols 的类数组对象, 可选长度为的类数组

定义列的相对宽度。每列的相对宽度为 width_ratios[i] / sum(width_ratios)。如果未指定，所有列将具有相同的宽度。等同于 gridspec_kw={'width_ratios': [...]}。在嵌套布局的情况下，此参数仅适用于外部布局。

height_ratios : 长度为 nrows 的类数组对象, 可选长度为的类数组

定义行的相对高度。每行的高度为 height_ratios[i] / sum(height_ratios)。如果未指定，所有行将具有相同的高度。等同于 gridspec_kw={'height_ratios': [...]}。在嵌套布局的情况下，此参数仅适用于外部布局。

subplot_kw字典，可选

传递给 Figure.add_subplot 调用的关键字字典，用于创建每个子图。这些值可能会被 per_subplot_kw 中的值覆盖。

per_subplot_kw字典，可选

一个字典，将 Axes 标识符或标识符元组映射到一个关键字参数字典，这些参数将被传递给用于创建每个子图的 Figure.add_subplot 调用。这些字典中的值优先于 subplot_kw 中的值。

如果 mosaic 是一个字符串，因此所有键都是单个字符，则可以使用单个字符串而不是元组作为键；即 "AB" 等同于 ("A", "B")。

Added in version 3.7.

gridspec_kw字典，可选

传递给 GridSpec 构造函数的带有关键字的字典，用于创建子图放置的网格。对于嵌套布局，此参数仅适用于外部布局。对于更复杂的布局，用户应使用 Figure.subfigures 来创建嵌套。

empty_sentinel对象，可选

布局中的条目，表示“保留此空间为空”。默认为 '.'。注意，如果 layout 是字符串，它将通过 inspect.cleandoc 处理以删除前导空白，这可能会干扰使用空白作为空占位符。

返回:

dict[标签, 轴]

一个将标签映射到 Axes 对象的字典。Axes 的顺序是根据它们在整个布局中的位置从左到右、从上到下排列的。

subplots(nrows=1, ncols=1, *, sharex=False, sharey=False, squeeze=True, width_ratios=None, height_ratios=None, subplot_kw=None, gridspec_kw=None)

向此图形添加一组子图。

这个实用封装使得通过一次调用就能方便地创建常见的子图布局。

参数:

nrows, ncolsint, 默认值: 1

子图网格的行数/列数。

sharex, shareybool 或 {'none', 'all', 'row', 'col'}，默认值：False

控制x轴(sharex)或y轴(sharey)的共享：

• True 或 'all'：所有子图将共享 x 轴或 y 轴。

• False 或 'none'：每个子图的 x 轴或 y 轴将是独立的。

• 'row': 每个子图行将共享一个 x 或 y 轴。

• 'col': 每个子图列将共享一个 x 轴或 y 轴。

当子图在列中共享x轴时，只有底部子图的x刻度标签会被创建。同样地，当子图在行中共享y轴时，只有第一列子图的y刻度标签会被创建。要稍后打开其他子图的刻度标签，请使用 tick_params。

当子图共享一个具有单位的轴时，调用 Axis.set_units 将使用新单位更新每个轴。

请注意，无法取消共享轴。

挤压bool, 默认: True

• 如果为 True，则从返回的 Axes 数组中挤出额外的维度：

  • 如果只构建了一个子图（nrows=ncols=1），则返回的单个 Axes 对象作为标量返回。

  • 对于 Nx1 或 1xM 的子图，返回的对象是一个包含 Axes 对象的一维 numpy 对象数组。

  • 对于 NxM，如果 N>1 且 M>1，则返回的子图是二维数组。

• 如果为 False，则不会进行任何挤压操作：返回的 Axes 对象始终是一个包含 Axes 实例的 2D 数组，即使它最终是 1x1。

width_ratios : 长度为 ncols 的类数组对象, 可选长度为的类数组

定义列的相对宽度。每列的相对宽度为 width_ratios[i] / sum(width_ratios)。如果未指定，所有列将具有相同的宽度。等同于 gridspec_kw={'width_ratios': [...]}。

height_ratios : 长度为 nrows 的类数组对象, 可选长度为的类数组

定义行的相对高度。每行的高度为 height_ratios[i] / sum(height_ratios)。如果未指定，所有行将具有相同的高度。等同于 gridspec_kw={'height_ratios': [...]}。

subplot_kw字典，可选

传递给 Figure.add_subplot 调用的关键字字典，用于创建每个子图。

gridspec_kw字典，可选

传递给 GridSpec 构造函数的带有关键字的字典，用于创建子图放置的网格。

返回:

Axes 或 Axes 数组

如果创建了多个子图，则返回一个 Axes 对象或 Axes 对象数组。结果数组的维度可以通过 squeeze 关键字控制，如上所述。

参见

pyplot.subplots

Figure.add_subplot

pyplot.subplot

示例

# First create some toy data:
x = np.linspace(0, 2*np.pi, 400)
y = np.sin(x**2)

# Create a figure
fig = plt.figure()

# Create a subplot
ax = fig.subplots()
ax.plot(x, y)
ax.set_title('Simple plot')

# Create two subplots and unpack the output array immediately
ax1, ax2 = fig.subplots(1, 2, sharey=True)
ax1.plot(x, y)
ax1.set_title('Sharing Y axis')
ax2.scatter(x, y)

# Create four polar Axes and access them through the returned array
axes = fig.subplots(2, 2, subplot_kw=dict(projection='polar'))
axes[0, 0].plot(x, y)
axes[1, 1].scatter(x, y)

# Share an X-axis with each column of subplots
fig.subplots(2, 2, sharex='col')

# Share a Y-axis with each row of subplots
fig.subplots(2, 2, sharey='row')

# Share both X- and Y-axes with all subplots
fig.subplots(2, 2, sharex='all', sharey='all')

# Note that this is the same as
fig.subplots(2, 2, sharex=True, sharey=True)

subplots_adjust(left=None, bottom=None, right=None, top=None, wspace=None, hspace=None)

调整子图布局参数。

未设置的参数保持不变；初始值由 rcParams["figure.subplot.[name]"] 提供。

参数:

左浮点数，可选

子图的左边缘位置，作为图宽的一部分。

右浮点数，可选

子图的右边界的相对位置，作为图宽的一部分。

底部浮点数，可选

子图的底部边缘位置，作为图高度的一部分。

顶部浮点数，可选

子图顶部边缘的位置，作为图形高度的分数。

wspace浮点数，可选

子图之间的填充宽度，作为平均Axes宽度的分数。

hspace浮点数，可选

子图之间的填充高度，作为平均 Axes 高度的分数。

suptitle(t, **kwargs)

为图形添加一个居中的标题。

参数:

tstr

标题文本。

xfloat, 默认值: 0.5

文本在图形坐标中的x位置。

yfloat, 默认值: 0.98

文本在图形坐标中的y位置。

horizontalalignment, ha{'center', 'left', 'right'}, 默认: center

文本相对于 (x, y) 的水平对齐方式。

垂直对齐, va{'top', 'center', 'bottom', 'baseline'}, 默认: top

文本相对于 (x, y) 的垂直对齐方式。

字体大小, 大小 : 默认值: rcParams["figure.titlesize"] (default: 'large')默认:

文本的字体大小。查看 Text.set_size 以获取可能的值。

fontweight, weight : 默认值: rcParams["figure.titleweight"] (default: 'normal')默认:

文本的字体粗细。查看 Text.set_weight 以获取可能的值。

返回:

文本

标题的 Text 实例。

其他参数:

fontpropertiesNone 或 dict，可选

字体属性的字典。如果给出了 fontproperties ，则字体大小和粗细的默认值取自 FontProperties 的默认值。在这种情况下，rcParams["figure.titlesize"] (default: 'large') 和 rcParams["figure.titleweight"] (default: 'normal') 将被忽略。

**kwargs

额外的 kwargs 是 matplotlib.text.Text 属性。

supxlabel(t, **kwargs)

为图形添加一个居中的 supxlabel。

参数:

tstr

supxlabel 文本。

xfloat, 默认值: 0.5

文本在图形坐标中的x位置。

yfloat, 默认值: 0.01

文本在图形坐标中的y位置。

horizontalalignment, ha{'center', 'left', 'right'}, 默认: center

文本相对于 (x, y) 的水平对齐方式。

垂直对齐, va{'top', 'center', 'bottom', 'baseline'}，默认值：bottom

文本相对于 (x, y) 的垂直对齐方式。

字体大小, 大小 : 默认值: rcParams["figure.labelsize"] (default: 'large')默认:

文本的字体大小。查看 Text.set_size 以获取可能的值。

字体粗细, 粗细 : 默认值: rcParams["figure.labelweight"] (default: 'normal')默认:

文本的字体粗细。查看 Text.set_weight 以获取可能的值。

返回:

文本

Text 实例的 supxlabel。

其他参数:

fontpropertiesNone 或 dict，可选

字体属性的字典。如果给出了 fontproperties ，则字体大小和粗细的默认值取自 FontProperties 的默认值。在这种情况下，rcParams["figure.labelsize"] (default: 'large') 和 rcParams["figure.labelweight"] (default: 'normal') 将被忽略。

**kwargs

额外的 kwargs 是 matplotlib.text.Text 属性。

supylabel(t, **kwargs)

为图形添加一个居中的子标签。

参数:

tstr

The supylabel 文本。

xfloat, 默认值: 0.02

文本在图形坐标中的x位置。

yfloat, 默认值: 0.5

文本在图形坐标中的y位置。

horizontalalignment, ha{'center', 'left', 'right'}, 默认: left

文本相对于 (x, y) 的水平对齐方式。

垂直对齐, va{'top', 'center', 'bottom', 'baseline'}，默认值：center

文本相对于 (x, y) 的垂直对齐方式。

字体大小, 大小 : 默认值: rcParams["figure.labelsize"] (default: 'large')默认:

文本的字体大小。查看 Text.set_size 以获取可能的值。

字体粗细, 粗细 : 默认值: rcParams["figure.labelweight"] (default: 'normal')默认:

文本的字体粗细。查看 Text.set_weight 以获取可能的值。

返回:

文本

supylabel 的 Text 实例

其他参数:

fontpropertiesNone 或 dict，可选

字体属性的字典。如果给出了 fontproperties ，则字体大小和粗细的默认值取自 FontProperties 的默认值。在这种情况下，rcParams["figure.labelsize"] (default: 'large') 和 rcParams["figure.labelweight"] (default: 'normal') 将被忽略。

**kwargs

额外的 kwargs 是 matplotlib.text.Text 属性。

text(x, y, s, fontdict=None, **kwargs)

添加文本到图形。

参数:

x, yfloat

文本放置的位置。默认情况下，这是在图形坐标中，浮点数在 [0, 1] 范围内。可以使用 transform 关键字更改坐标系。

sstr

文本字符串。

fontdict字典，可选

一个用于覆盖默认文本属性的字典。如果没有给出，默认值由 rcParams["font.*"] 决定。作为 kwargs 传递的属性会覆盖 fontdict 中相应的属性。

返回:

Text

其他参数:

**kwargs : Text 属性文本属性

其他杂项文本参数。

属性	描述
agg_filter	一个过滤函数，它接收一个 (m, n, 3) 浮点数组和一个 dpi 值，并返回一个 (m, n, 3) 数组和两个从图像左下角开始的偏移量
alpha	标量或无
animated	布尔值
抗锯齿	布尔值
backgroundcolor	color
bbox	带有属性的字典用于 patches.FancyBboxPatch
clip_box	未知
clip_on	未知
clip_path	未知
颜色 或 c	color
figure	Figure 或 SubFigure
fontfamily 或 family 或 fontname	{FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'}
fontproperties 或 font 或 font_properties	font_manager.FontProperties 或 str 或 pathlib.Path
字体大小 或大小	float 或 {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}
fontstretch 或 stretch	{一个数值范围在0-1000之间, '超浓缩', '特浓缩', '浓缩', '半浓缩', '正常', '半扩展', '扩展', '特扩展', '超扩展'}
fontstyle 或样式	{'normal', 'italic', 'oblique'}
fontvariant 或 variant	{'normal', 'small-caps'}
fontweight 或 weight	{一个数值范围在0-1000之间, '超轻', '轻', '正常', '常规', '书', '中等', '罗马', '半粗', '次粗', '半', '粗', '重', '特粗', '黑'}
gid	str
horizontalalignment 或 ha	{'left', 'center', 'right'}
in_layout	布尔值
标签	对象
行间距	浮动（字体大小的倍数）
math_fontfamily	str
鼠标悬停	布尔值
多重对齐 或 ma	{'left', 'right', 'center'}
parse_math	布尔值
path_effects	AbstractPathEffect 的列表
picker	None 或 bool 或 float 或 callable
位置	(浮点数, 浮点数)
光栅化	布尔值
旋转	float 或 {'vertical', 'horizontal'}
rotation_mode	{None, 'default', 'anchor'}
sketch_params	(scale: float, length: float, randomness: float)
snap	布尔值或无
文本	对象
transform	Transform
transform_rotates_text	布尔值
url	str
usetex	bool, 默认值: rcParams["text.usetex"] (default: False)
垂直对齐 或 va	{'baseline', 'bottom', 'center', 'center_baseline', 'top'}
visible	布尔值
wrap	布尔值
x	float
y	float
zorder	float

参见

Axes.text

pyplot.text

辅助函数

matplotlib.figure.figaspect(arg)

计算具有指定宽高比的图像的宽度和高度。

虽然高度取自 rcParams["figure.figsize"] (default: [6.4, 4.8])，但宽度会调整以匹配所需的宽高比。此外，确保宽度在 [4., 16.] 范围内，高度在 [2., 16.] 范围内。如有必要，默认高度会进行调整以确保这一点。

参数:

参数浮点数或二维数组

如果是一个浮点数，这定义了宽高比（即高度/宽度）。如果是数组，则宽高比为行数/列数，以便数组可以无失真地适应图形。

返回:

宽度, 高度float

图形的尺寸，单位为英寸。

注释

如果你想在图形中创建一个保持纵横比的 Axes，请确保以相同的宽度和高度创建它。请参见下面的示例。

感谢 Fernando Perez 提供此功能。

示例

制作一个高度是宽度两倍的图形:

w, h = figaspect(2.)
fig = Figure(figsize=(w, h))
ax = fig.add_axes([0.1, 0.1, 0.8, 0.8])
ax.imshow(A, **kwargs)

为数组制作一个适当比例的图形:

A = rand(5, 3)
w, h = figaspect(A)
fig = Figure(figsize=(w, h))
ax = fig.add_axes([0.1, 0.1, 0.8, 0.8])
ax.imshow(A, **kwargs)