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

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

在某些情况下，需要直接实例化 Figure 类，通常是在某种应用程序中（示例列表请参阅 将 Matplotlib 嵌入到图形用户界面中）。有关 Figures 的更多信息，请参阅 Figures 简介。

Figure

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；更新当前坐标轴。
Figure.subfigures	向此图形或子图形添加一组子图形。
Figure.add_subfigure	向图形添加一个 SubFigure 作为子图排列的一部分。

保存

Figure.savefig

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

注释

Figure.colorbar	向绘图添加一个颜色条。
Figure.legend	在图形上放置图例。
Figure.text	向图形添加文本。
Figure.suptitle	向图形添加一个居中的总标题。
Figure.get_suptitle	返回总标题字符串，如果未设置则返回空字符串。
Figure.supxlabel	向图形添加一个居中的超大 x 轴标签。
Figure.get_supxlabel	返回超大 x 轴标签字符串，如果未设置则返回空字符串。
Figure.supylabel	向图形添加一个居中的超大 y 轴标签。
Figure.get_supylabel	返回超大 y 轴标签字符串，如果未设置则返回空字符串。
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.get_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 矩形的线宽。
Figure.get_linewidth	获取 Figure 矩形的线宽。
Figure.set_facecolor	设置 Figure 矩形的填充颜色。
Figure.get_facecolor	获取 Figure 矩形的填充颜色。
Figure.set_edgecolor	设置 Figure 矩形的边框颜色。
Figure.get_edgecolor	获取 Figure 矩形的边框颜色。

添加和获取 Artists

Figure.add_artist	向图形添加一个 Artist。
Figure.get_children	获取图形中包含的 artist 列表。
Figure.figimage	向图形添加非重采样图像。

获取和修改状态

另请参阅

• 交互式图形

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

SubFigure

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

(源代码, 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；更新当前坐标轴。
SubFigure.add_subfigure	向图形添加一个 SubFigure 作为子图排列的一部分。
SubFigure.subfigures	向此图形或子图形添加一组子图形。

注释

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

添加和获取 Artists

SubFigure.add_artist	向图形添加一个 Artist。
SubFigure.get_children	获取图形中包含的 artist 列表。

修改外观

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

直通

SubFigure.set_dpi	设置父图形的分辨率（每英寸点数）。
SubFigure.get_dpi	以浮点数返回父图形的分辨率（每英寸点数）。

FigureBase 父类

class matplotlib.figure.FigureBase(**kwargs)

Figure 和 SubFigure 的基类，包含向图形或子图形添加 artist、创建 Axes 等方法。

add_artist(artist, clip=False)

向图形添加一个 Artist。

通常，artist 是使用 Axes.add_artist 添加到 Axes 对象的；在需要直接向图形添加 artist 的罕见情况下，可以使用此方法。

参数:

artistArtist

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

clipbool, 默认值: False

添加的 artist 是否应被图形补丁裁剪。

返回:

艺术家

添加的 artist。

add_axes(*args, **kwargs)

向图形添加一个 Axes。

调用签名

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

参数:

rect元组 (left, bottom, width, height)

新 Axes 的尺寸（左、下、宽、高）。所有量均以图形宽度和高度的分数表示。

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

Axes 的投影类型。str 是自定义投影的名称，请参阅 projections。默认值 None 导致“rectilinear”投影。

polarbool, 默认值: False

如果为 True，相当于 projection='polar'。

axes_classAxes 的子类类型, 可选

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

sharex, shareyAxes, 可选

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

labelstr

返回的 Axes 的标签。

返回:

Axes，或 Axes 的子类

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

其他参数:

**kwargs

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

属性	描述
adjustable	{'box', 'datalim'}
agg_filter	一个过滤函数，它接受一个 (m, n, 3) 浮点数组和一个 dpi 值，并返回一个 (m, n, 3) 数组以及图像左下角的两个偏移量
alpha	浮点数或 None
anchor	(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	浮点数或 None
clip_box	BboxBase 或 None
clip_on	布尔值
clip_path	Patch 或 (Path, Transform) 或 None
facecolor 或 fc	color
figure	Figure 或 SubFigure
forward_navigation_events	bool 或 "auto"
frame_on	布尔值
gid	str
in_layout	布尔值
label	object
mouseover	布尔值
navigate	布尔值
navigate_mode	未知
path_effects	list of AbstractPathEffect
picker	None 或 布尔值 或 浮点数 或 可调用对象
position	[left, bottom, width, height] 或 Bbox
prop_cycle	Cycler
rasterization_zorder	浮点数或 None
rasterized	布尔值
sketch_params	(scale: 浮点数, length: 浮点数, randomness: 浮点数)
snap	布尔值或 None
subplotspec	未知
title	str
transform	变换
url	str
visible	布尔值
xbound	(lower: float, upper: float)
xlabel	str
xlim	(left: float, right: float)
xmargin	float 大于 -0.5
xscale	未知
xticklabels	未知
xticks	未知
ybound	(lower: float, upper: float)
ylabel	str
ylim	(bottom: float, top: float)
ymargin	float 大于 -0.5
yscale	未知
yticklabels	未知
yticks	未知
zorder	浮点数

另请参阅

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 并随后根据 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

定义了父 gridspec 中子图形的放置区域。

返回:

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

参数:

*argsint, (int, int, index), 或 SubplotSpec, 默认值: (1, 1, 1)

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

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

• 一个 3 位整数。数字将被解释为单独给出三个单数字整数，即 fig.add_subplot(235) 与 fig.add_subplot(2, 3, 5) 相同。请注意，这只能在子图数量不超过 9 个时使用。

• 一个 SubplotSpec。

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

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

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

polarbool, 默认值: False

如果为 True，相当于 projection='polar'。

axes_classAxes 的子类类型, 可选

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

sharex, shareyAxes, 可选

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

labelstr

返回的 Axes 的标签。

返回:

Axes

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

其他参数:

**kwargs

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

属性	描述
adjustable	{'box', 'datalim'}
agg_filter	一个过滤函数，它接受一个 (m, n, 3) 浮点数组和一个 dpi 值，并返回一个 (m, n, 3) 数组以及图像左下角的两个偏移量
alpha	浮点数或 None
anchor	(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	浮点数或 None
clip_box	BboxBase 或 None
clip_on	布尔值
clip_path	Patch 或 (Path, Transform) 或 None
facecolor 或 fc	color
figure	Figure 或 SubFigure
forward_navigation_events	bool 或 "auto"
frame_on	布尔值
gid	str
in_layout	布尔值
label	object
mouseover	布尔值
navigate	布尔值
navigate_mode	未知
path_effects	list of AbstractPathEffect
picker	None 或 布尔值 或 浮点数 或 可调用对象
position	[left, bottom, width, height] 或 Bbox
prop_cycle	Cycler
rasterization_zorder	浮点数或 None
rasterized	布尔值
sketch_params	(scale: 浮点数, length: 浮点数, randomness: 浮点数)
snap	布尔值或 None
subplotspec	未知
title	str
transform	变换
url	str
visible	布尔值
xbound	(lower: float, upper: float)
xlabel	str
xlim	(left: float, right: float)
xmargin	float 大于 -0.5
xscale	未知
xticklabels	未知
xticks	未知
ybound	(lower: float, upper: float)
ylabel	str
ylim	(bottom: float, top: float)
ymargin	float 大于 -0.5
yscale	未知
yticklabels	未知
yticks	未知
zorder	浮点数

另请参阅

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 轴标签。

对齐在此调用后会持续到绘制事件。

参数:

axsAxes 列表

可选的 Axes 列表（或 ndarray），用于对齐标签。默认是对齐图形上的所有 Axes。

另请参阅

matplotlib.figure.Figure.align_xlabels

matplotlib.figure.Figure.align_ylabels

matplotlib.figure.Figure.align_titles

备注

这假定 axs 中的所有 Axes 都来自同一个 GridSpec，因此它们的 SubplotSpec 位置对应于图形位置。

align_titles(axs=None)

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

对齐在此调用后会持续到绘制事件。

参数:

axsAxes 列表

可选的 Axes 列表（或 ndarray），用于对齐标题。默认是对齐图形上的所有 Axes。

另请参阅

matplotlib.figure.Figure.align_xlabels

matplotlib.figure.Figure.align_ylabels

matplotlib.figure.Figure.align_labels

备注

这假定 axs 中的所有 Axes 都来自同一个 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 上的标签对齐。

参数:

axsAxes 列表

可选的 Axes 列表（或 ndarray），用于对齐 x 轴标签。默认是对齐图形上的所有 Axes。

另请参阅

matplotlib.figure.Figure.align_ylabels

matplotlib.figure.Figure.align_titles

matplotlib.figure.Figure.align_labels

备注

这假定 axs 中的所有 Axes 都来自同一个 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 上的标签对齐。

参数:

axsAxes 列表

可选的 Axes 列表（或 ndarray），用于对齐 y 轴标签。默认是对齐图形上的所有 Axes。

另请参阅

matplotlib.figure.Figure.align_xlabels

matplotlib.figure.Figure.align_titles

matplotlib.figure.Figure.align_labels

备注

这假定 axs 中的所有 Axes 都来自同一个 GridSpec，因此它们的 SubplotSpec 位置对应于图形位置。

示例

带有大 yticks 标签的示例

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 轴标签会有所帮助。

参数:

bottomfloat, 默认值: 0.2

用于 subplots_adjust 的子图底部。

rotationfloat, 默认值: 30 度

xtick 标签的旋转角度（度）。

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

xticklabels 的水平对齐方式。

which{'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)

向绘图添加一个颜色条。

参数:

mappable

此颜色条描述的 matplotlib.cm.ScalarMappable（即 AxesImage、ContourSet 等）。此参数对于 Figure.colorbar 方法是强制性的，但对于 pyplot.colorbar 函数是可选的，后者将默认值设置为当前图像。

请注意，可以“动态”创建一个 ScalarMappable 以生成未附加到先前绘制的 artist 的颜色条，例如：

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

caxAxes, 可选

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

axAxes 或可迭代对象 或 numpy.ndarray of Axes, 可选

将从中窃取空间以创建新颜色条 Axes 的一个或多个父 Axes。此参数仅在未设置 cax 时使用。

默认为包含用于创建颜色条的 mappable 的 Axes。

use_gridspecbool, 可选

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

返回:

colorbarColorbar

其他参数:

locationNone 或 {'left', 'right', 'top', 'bottom'}

相对于父 Axes 创建颜色条 Axes 的位置。它还决定颜色条的 orientation（左右颜色条是垂直的，上下颜色条是水平的）。如果为 None，则位置将来自 orientation（如果已设置）（垂直颜色条在右侧，水平颜色条在底部），如果 orientation 未设置，则默认为“right”。

orientationNone 或 {'vertical', 'horizontal'}

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

fractionfloat, 默认值: 0.15

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

shrinkfloat, 默认值: 1.0

颜色条大小的乘法因子。

aspectfloat, 默认值: 20

长短尺寸比。

padfloat, 默认值: 0.05 if vertical, 0.15 if horizontal

颜色条与新图像 Axes 之间的原始 Axes 比例。

anchor(float, float), 可选

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

panchor(float, float), 或 False, 可选

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

extend{'neither', 'both', 'min', 'max'}

为超出范围的值制作尖头末端（除非是 'neither'）。这些是通过 colormap 的 set_under 和 set_over 方法为给定 colormap 设置的。

extendfrac{None, 'auto', length, lengths}

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

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

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

extendrectbool

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

ticksNone 或 刻度列表 或 Locator

如果为 None，则刻度自动从输入中确定。

formatNone 或 str 或 Formatter

如果未设置，将以 0-1 比例显示颜色图。如果为序列，则 values 的长度必须比 boundaries 小 1。对于由 boundaries 中相邻条目限定的每个区域，将使用映射到 values 中相应值的颜色。每个区域的大小由 spacing 参数确定。通常仅对索引颜色（即 norm=NoNorm()）或其他不寻常情况有用。

drawedgesbool

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

labelstr

颜色条长轴上的标签。

boundaries, valuesNone 或 序列

如果未设置，将以 0-1 比例显示颜色图。如果为序列，则 values 的长度必须比 boundaries 少 1。对于由 boundaries 中相邻条目限定的每个区域，将使用映射到 values 中相应值的颜色。每个区域的大小由 spacing 参数确定。通常仅对索引颜色（即 norm=NoNorm()）或其他不寻常情况有用。

spacing{'uniform', 'proportional'}

对于离散颜色条（BoundaryNorm 或等高线），'uniform' 使每种颜色占用相同的空间；'proportional' 使空间与数据间隔成比例。

备注

如果 mappable 是 ContourSet，则其 extend kwarg 会自动包含在内。

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

为了更精确的控制，您可以手动指定绘制 mappable 和颜色条的 axes 对象的位置。在这种情况下，不要使用任何 Axes 属性 kwarg。

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

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

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

contains(mouseevent)

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

返回:

bool, {}

delaxes(ax)

从图形中删除 Axes ax；更新当前坐标轴。

draw(renderer)

使用给定的渲染器绘制 Artist（及其子对象）。

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

参数:

rendererRendererBase 子类。

备注

此方法在 Artist 子类中被覆盖。

property figure

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

property frameon

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

gca()

获取当前 Axes。

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

get_children()

获取图形中包含的 artist 列表。

get_default_bbox_extra_artists()

返回一个通常在 Figure.get_tightbbox 中使用的 Artist 列表。

get_edgecolor()

获取 Figure 矩形的边框颜色。

get_facecolor()

获取 Figure 矩形的填充颜色。

get_figure(root=None)

返回（子）图形所属的 Figure 或 SubFigure 实例。

参数:

rootbool, 默认值=True

如果为 False，则返回此 artist 所处的（子）图形。如果为 True，则返回嵌套 SubFigures 树的根 Figure。

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

get_frameon()

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

get_linewidth()

获取 Figure 矩形的线宽。

get_suptitle()

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

get_supxlabel()

返回超大 x 轴标签字符串，如果未设置则返回空字符串。

get_supylabel()

返回超大 y 轴标签字符串，如果未设置则返回空字符串。

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

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

请注意，FigureBase 与所有其他 artist 不同，后者返回它们的 Bbox 以像素为单位。

具有 artist.set_in_layout(False) 的艺术家对象不会包含在边界框中。

参数:

rendererRendererBase 子类

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

bbox_extra_artistsArtist 列表或 None

包含在紧密边界框中的 artist 列表。如果为 None（默认），则每个 Axes 的所有子 artist 都包含在紧密边界框中。

返回:

BboxBase

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

get_window_extent(renderer=None)

获取 artist 在显示空间中的边界框。

边界框的宽度和高度均为非负值。

子类应覆盖此方法，以便将其包含在边界框“紧密”计算中。默认返回一个位于 0, 0 的空边界框。

使用此函数时请小心，如果 artist 的窗口范围发生变化，结果将不会更新。范围可能因变换堆栈中的任何变化而变化，例如更改 Axes 限制、图形大小或使用的画布（如保存图形时所做）。这可能导致交互式图形在屏幕上看起来正常，但保存时会出错。

legend(*args, **kwargs)

在图形上放置图例。

调用签名

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

此方法的调用签名对应以下几种不同用法

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

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

在这种情况下，标签取自 artist。您可以在创建 artist 时指定它们，也可以通过调用 artist 上的 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()

可以通过定义以下划线开头的标签将特定行排除在自动图例元素选择之外。这是所有 artist 的默认设置，因此在不带任何参数且未手动设置标签的情况下调用 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 上的所有 artist 创建图例，请使用可迭代的字符串（每个图例项一个）调用此函数。例如：

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'])

参数:

handlesArtist 列表, 可选

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

在这种情况下，handles 和 labels 的长度应该相同。如果不同，它们将被截断为较小的长度。

labels字符串列表, 可选

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

返回:

图例

其他参数:

loc字符串或浮点数对，默认值: 'upper right'

图例的位置。

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

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

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

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

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

位置字符串	位置代码
'best'（仅限 Axes）	0
'upper right'（右上）	1
'upper left'（左上）	2
'lower left'（左下）	3
'lower right'（右下）	4
'right'（右）	5
'center left'（左中）	6
'center right'（右中）	7
'lower center'（下中）	8
'upper center'（上中）	9
'center'（中）	10

如果图形正在使用约束布局管理器，则 loc 关键字参数的字符串代码可以使用前缀“outside”获得更好的布局行为。角落处存在歧义，因此“outside upper right”将在布局中为图例腾出轴上方空间，而“outside right upper”将在布局右侧腾出空间。除了上面列出的 loc 值外，我们还有“outside right upper”、“outside right lower”、“outside left upper”和“outside left lower”。有关更多详细信息，请参阅 图例指南。

bbox_to_anchorBboxBase, 2-元组, 或 4-元组浮点数

与 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 优先。

propNone 或 FontProperties 或 dict

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

fontsize整数或 {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}

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

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

图例中文本的颜色。可以是有效的颜色字符串（例如，“red”），也可以是颜色字符串列表。标签颜色也可以与线条或标记的颜色匹配，使用“linecolor”、“markerfacecolor”（或“mfc”）或“markeredgecolor”（或“mec”）。

Labelcolor可以使用rcParams["legend.labelcolor"]（默认值：'None'）进行全局设置。如果为None，则使用rcParams["text.color"]（默认值：'black'）。

numpointsint, 默认值：rcParams["legend.numpoints"]（默认值：1）

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

scatterpointsint, 默认值：rcParams["legend.scatterpoints"]（默认值：1）

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

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

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

markerscalefloat, 默认值：rcParams["legend.markerscale"]（默认值：1.0）

图例标记相对于原始绘制标记的相对大小。

markerfirst布尔值，默认值：True

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

reverse布尔值，默认值：False

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

版本 3.7 新增。

frameonbool, 默认值：rcParams["legend.frameon"]（默认值：True）

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

fancyboxbool, 默认值：rcParams["legend.fancybox"]（默认值：True）

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

shadowNone, bool 或 dict, 默认值：rcParams["legend.shadow"]（默认值：False）

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

framealphafloat, 默认值：rcParams["legend.framealpha"]（默认值：0.8）

图例背景的 alpha 透明度。如果 shadow 被激活且 framealpha 为 None，则忽略默认值。

facecolor"inherit" 或 color, 默认值：rcParams["legend.facecolor"]（默认值：'inherit'）

图例的背景颜色。如果为"inherit"，则使用rcParams["axes.facecolor"]（默认值：'white'）。

edgecolor"inherit" 或 color, 默认值：rcParams["legend.edgecolor"]（默认值：'0.8'）

图例背景补丁的边缘颜色。如果为"inherit"，则使用rcParams["axes.edgecolor"]（默认值：'black'）。

mode{"expand", None}

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

bbox_transformNone 或 Transform

边界框（bbox_to_anchor）的变换。如果值为None（默认），将使用Axes的transAxes变换。

title字符串或 None

图例的标题。默认没有标题（None）。

title_fontpropertiesNone 或 FontProperties 或 dict

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

title_fontsizeint 或 {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}, 默认值：rcParams["legend.title_fontsize"]（默认值：None）

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

alignment{'center', 'left', 'right'}，默认值：'center'

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

borderpadfloat, 默认值：rcParams["legend.borderpad"]（默认值：0.4）

图例边框内的空白区域比例，以字体大小单位表示。

labelspacingfloat, 默认值：rcParams["legend.labelspacing"]（默认值：0.5）

图例条目之间的垂直间距，以字体大小单位表示。

handlelengthfloat, 默认值：rcParams["legend.handlelength"]（默认值：2.0）

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

handleheightfloat, 默认值：rcParams["legend.handleheight"]（默认值：0.7）

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

handletextpadfloat, 默认值：rcParams["legend.handletextpad"]（默认值：0.8）

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

borderaxespadfloat, 默认值：rcParams["legend.borderaxespad"]（默认值：0.5）

Axes 与图例边框之间的填充，以字体大小单位表示。

columnspacingfloat, 默认值：rcParams["legend.columnspacing"]（默认值：2.0）

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

handler_map字典或 None

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

draggable布尔值，默认值：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	浮点数或 None
animated	布尔值
clip_box	BboxBase 或 None
clip_on	布尔值
clip_path	Patch 或 (Path, Transform) 或 None
edgecolor	color
facecolor	color
figure	未知
frameon	布尔值
gid	str
in_layout	布尔值
label	object
linewidth	数值
mouseover	布尔值
path_effects	list of AbstractPathEffect
picker	None 或 布尔值 或 浮点数 或 可调用对象
rasterized	布尔值
sketch_params	(scale: 浮点数, length: 浮点数, randomness: 浮点数)
snap	布尔值或 None
transform	变换
url	str
visible	布尔值
zorder	浮点数

set_edgecolor(color)

设置 Figure 矩形的边框颜色。

参数:

color颜色

set_facecolor(color)

设置 Figure 矩形的填充颜色。

参数:

color颜色

set_figure(fig)

自3.10版本起已废弃： 目前，如果fig不是此（子）Figure所在的根Figure，此方法将引发异常。将来它将始终引发异常。

set_frameon(b)

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

参数:

bbool

set_linewidth(linewidth)

设置 Figure 矩形的线宽。

参数:

linewidthnumber

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

向此图形或子图形添加一组子图形。

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

3.10 版本中变更：子图现在以行优先顺序添加。

参数:

nrows, ncols整型, 默认值: 1

子图网格的行/列数。

squeeze布尔型, 默认值: 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 布局。

有关示例和完整的API文档，请参阅复杂和语义图组合 (subplot_mosaic)

参数:

mosaic可哈希或嵌套列表的列表，或字符串

一个可视化布局，说明您希望 Axes 如何以字符串形式排列。例如

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

生成 4 个 Axes

• 'A panel'（A 面板）高 1 行，跨前两列

• 'edge'（边缘）高 2 行，位于右边缘

• 'C panel'（C 面板）在左下角高 1 行、宽 1 列

• 底部中央有一个 1 行 1 列宽的空白区域

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

如果输入是 str，那么它可以是以下形式的多行字符串：

'''
AAE
C.E
'''

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

'AB;CC'

字符串表示法只允许使用单字符的 Axes 标签，不支持嵌套，但非常简洁。

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

sharex, sharey布尔值，默认值：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")。

版本 3.7 新增。

gridspec_kw字典，可选

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

empty_sentinel对象，可选

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

返回:

dict[label, Axes]

一个将标签映射到 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, ncols整型, 默认值: 1

子图网格的行/列数量。

sharex, sharey布尔型或 {'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将更新每个轴的新单位。

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

squeeze布尔型, 默认值: True

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

  • 如果只构造一个子图 (nrows=ncols=1)，则结果单个 Axes 对象将作为标量返回。

  • 对于 Nx1 或 1xM 子图，返回的对象是 Axes 对象的 1D numpy 对象数组。

  • 对于 NxM，N>1 且 M>1 的子图将作为 2D 数组返回。

• 如果为 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]"]给出。

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

参数:

left浮点型，可选

子图左边缘的位置，以图宽度的一个分数表示。

right浮点型，可选

子图右边缘的位置，以图宽度的一个分数表示。

bottomfloat, 可选

子图底边缘的位置，以图高度的一个分数表示。

topfloat, 可选

子图顶边缘的位置，以图高度的一个分数表示。

wspacefloat, 可选

子图之间填充的宽度，以平均Axes宽度的一个分数表示。

hspacefloat, 可选

子图之间填充的高度，以平均Axes高度的一个分数表示。

suptitle(t, **kwargs)

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

参数:

tstr

主标题文本。

xfloat, 默认值: 0.5

文本在图表坐标系中的X位置。

yfloat, 默认值: 0.98

文本在图表坐标系中的Y位置。

horizontalalignment, ha{'居中', '左对齐', '右对齐'}, 默认值: 居中

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

verticalalignment, va{'top', 'center', 'bottom', 'baseline'}, 默认值: top

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

fontsize, size默认值：rcParams["figure.titlesize"]（默认值：'large'）

文本的字体大小。可能的值请参见Text.set_size。

fontweight, weight默认值：rcParams["figure.titleweight"]（默认值：'normal'）

文本的字体粗细。可能的值请参见Text.set_weight。

返回:

text

主标题的Text实例。

其他参数:

fontpropertiesNone 或 dict, 可选

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

**kwargs

其他kwargs是matplotlib.text.Text属性。

supxlabel(t, **kwargs)

向图形添加一个居中的超大 x 轴标签。

参数:

tstr

超大X轴标签文本。

xfloat, 默认值: 0.5

文本在图表坐标系中的X位置。

yfloat, 默认值: 0.01

文本在图表坐标系中的Y位置。

horizontalalignment, ha{'居中', '左对齐', '右对齐'}, 默认值: 居中

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

verticalalignment, va{'顶部', '居中', '底部', '基线'}, 默认值: 底部

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

fontsize, size默认值：rcParams["figure.labelsize"]（默认值：'large'）

文本的字体大小。可能的值请参见Text.set_size。

fontweight, weight默认值：rcParams["figure.labelweight"]（默认值：'normal'）

文本的字体粗细。可能的值请参见Text.set_weight。

返回:

text

主x轴标签的Text实例。

其他参数:

fontpropertiesNone 或 dict, 可选

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

**kwargs

其他kwargs是matplotlib.text.Text属性。

supylabel(t, **kwargs)

向图形添加一个居中的超大 y 轴标签。

参数:

tstr

超级Y轴标签文本。

xfloat, 默认值: 0.02

文本在图表坐标系中的X位置。

yfloat, 默认值: 0.5

文本在图表坐标系中的Y位置。

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

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

verticalalignment, va{'top', 'center', 'bottom', 'baseline'}, 默认值: center

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

fontsize, size默认值：rcParams["figure.labelsize"]（默认值：'large'）

文本的字体大小。可能的值请参见Text.set_size。

fontweight, weight默认值：rcParams["figure.labelweight"]（默认值：'normal'）

文本的字体粗细。可能的值请参见Text.set_weight。

返回:

text

主y轴标签的Text实例。

其他参数:

fontpropertiesNone 或 dict, 可选

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

**kwargs

其他kwargs是matplotlib.text.Text属性。

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

向图形添加文本。

参数:

x, yfloat

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

sstr

文本字符串。

fontdict字典，可选

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

返回:

文本

其他参数:

**kwargsText属性

其他杂项文本参数。

属性	描述
agg_filter	一个过滤函数，它接受一个 (m, n, 3) 浮点数组和一个 dpi 值，并返回一个 (m, n, 3) 数组以及图像左下角的两个偏移量
alpha	浮点数或 None
animated	布尔值
antialiased	布尔值
backgroundcolor	color
bbox	包含patches.FancyBboxPatch属性的字典
clip_box	未知
clip_on	未知
clip_path	未知
color 或 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
fontsize 或 size	float 或 {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}
fontstretch 或 stretch	{0-1000 范围内的数值, 'ultra-condensed', 'extra-condensed', 'condensed', 'semi-condensed', 'normal', 'semi-expanded', 'expanded', 'extra-expanded', 'ultra-expanded'}
fontstyle 或 style	{'normal', 'italic', 'oblique'}
fontvariant 或 variant	{'normal', 'small-caps'}
fontweight 或 weight	{0-1000 范围内的数值, 'ultralight', 'light', 'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy', 'extra bold', 'black'}
gid	str
horizontalalignment 或 ha	{'left', 'center', 'right'}
in_layout	布尔值
label	object
linespacing	float (字体大小的倍数)
math_fontfamily	str
mouseover	布尔值
multialignment 或 ma	{'left', 'right', 'center'}
parse_math	布尔值
path_effects	list of AbstractPathEffect
picker	None 或 布尔值 或 浮点数 或 可调用对象
position	(浮点数, 浮点数)
rasterized	布尔值
rotation	float 或 {'vertical', 'horizontal'}
rotation_mode	{None, 'default', 'anchor'}
sketch_params	(scale: 浮点数, length: 浮点数, randomness: 浮点数)
snap	布尔值或 None
text	object
transform	变换
transform_rotates_text	布尔值
url	str
usetex	bool, 默认值：rcParams["text.usetex"]（默认值：False）
verticalalignment 或 va	{'baseline', 'bottom', 'center', 'center_baseline', 'top'}
visible	布尔值
wrap	布尔值
x	浮点数
y	浮点数
zorder	浮点数

另请参阅

Axes.text

pyplot.text

辅助函数

matplotlib.figure.figaspect(arg)

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

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

参数:

argfloat 或 2D 数组

如果为浮点数，则定义宽高比（即高度/宽度之比）。如果是数组，则宽高比为行数/列数，以便数组可以在图中不失真地拟合。

返回:

size(2,) 数组

图的宽度和高度（英寸）。

备注

如果你想在图中创建一个仍然保持宽高比的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)