`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 嵌入图形用户界面）。有关图形的更多信息，请参阅图形简介。

图形 (Figure)#

Figure 类#

Figure

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

添加 Axes（坐标轴）和 SubFigures（子图形）#

`Figure.add_axes`	向图形中添加一个 `Axes`。
`Figure.add_subplot`	作为子图排列的一部分，向图形中添加一个 `Axes`。
`Figure.subplots`	向此图形添加一组子图。
`Figure.subplot_mosaic`	根据 ASCII 艺术或嵌套列表构建 Axes 布局。
`Figure.add_gridspec`	用于创建以该图形为父级的 `GridSpec` 的底层 API。
`Figure.get_axes`	图形中 Axes 的列表。
`Figure.axes`	图形中 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`	向图形添加一个居中的超大 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`	返回是否正在使用受限布局（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`	获取美工对象在显示空间中的边界框，忽略裁剪。
`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

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

添加 Axes 和 SubFigures#

`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`	向图形添加一个居中的超大 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。

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

参数:

artistArtist: 要添加到图形的 artist。如果添加的 artist 之前没有设置变换，其变换将设置为 figure.transSubfigure。
clipbool, 默认值: False: 添加的 artist 是否应被图形补丁裁剪。

返回:

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`	`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)
`xinverted`	未知
`xlabel`	str
`xlim`	(left: float, right: float)
`xmargin`	float 大于 -0.5
`xscale`	未知
`xticklabels`	未知
`xticks`	未知
`ybound`	(lower: float, upper: float)
`yinverted`	未知
`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 也可以是一个二元组，指定子图的（first, last）索引（基于 1，包含 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 将导致“线性”投影。

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`	`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)
`xinverted`	未知
`xlabel`	str
`xlim`	(left: float, right: float)
`xmargin`	float 大于 -0.5
`xscale`	未知
`xticklabels`	未知
`xticks`	未知
`ybound`	(lower: float, upper: float)
`yinverted`	未知
`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 的列表: 用于对齐 xlabels 的可选 Axes 列表（或 ndarray）。默认是水平对齐图形上的所有 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)
axs[0].tick_params(axis='x', 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 的列表: 用于对齐 ylabels 的可选 Axes 列表（或 ndarray）。默认是水平对齐图形上的所有 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 轴是日期数据。刻度标签通常很长，旋转底部子图上的标签并关闭其他子图上的标签，以及关闭 xlabels，会有所帮助。

参数:

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.colorizer.ColorizingArtist（即 AxesImage, ContourSet 等）。此参数对于 Figure.colorbar 方法是强制性的，但对于 pyplot.colorbar 函数是可选的，该函数将当前图像作为默认值。

请注意，可以“即时”创建一个 colorizer.ColorizingArtist 来生成未附加到先前绘制的 artist 的颜色条，例如：

cr = colorizer.Colorizer(norm=norm, cmap=cmap)
fig.colorbar(colorizer.ColorizingArtist(cr), ax=ax)

caxAxes，可选

绘制色标所在的坐标轴 (Axes)。如果为 None，则会创建一个新的坐标轴，并从 ax 参数指定的坐标轴中划出空间。

axAxes 或可迭代对象或 numpy.ndarray 的 Axes，可选

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

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

use_gridspecbool, 可选

如果 cax 为 None，则会创建一个新的 cax 作为坐标轴实例。如果 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

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

drawedgesbool

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

labelstr

颜色条长轴上的标签。

boundaries, valuesNone 或序列

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

spacing{'uniform', 'proportional'}

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

备注

如果 mappable 是一个 ContourSet，其 extend 关键字参数将自动包含。

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；更新当前 Axes。

draw(renderer)[源码]#

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

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

参数:

rendererRendererBase 子类。

备注

此方法在 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，请检查 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)[源码]#

返回 (Sub)Figure 所属的 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)[源码]#

获取美工对象在显示空间中的边界框，忽略裁剪。

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

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

警告

范围可能会由于变换栈的任何更改而改变，例如更改坐标轴限制、图形大小、使用的画布（保存图形时）或 DPI。

依赖于一次性获取的窗口范围可能会在某些情况下导致意外行为，例如交互式图形被调整大小或移动到具有不同 DPI 的屏幕，或者在屏幕上看起来没问题的图形在保存到文件时渲染不正确。

为了获得准确的结果，您可能需要手动调用 savefig 或 draw_without_rendering，让 Matplotlib 计算渲染大小。

参数:

rendererRendererBase, 可选: 用于绘制图形的渲染器（即 fig.canvas.get_renderer()）。

另请参阅

Artist.get_tightbbox: 获取美工边界框，考虑裁剪。

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 一起使用此参数。

返回:

Legend

其他参数:

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

图例的位置。

字符串位置参数将图例放置在边界框内的相应位置，边界框默认为整个图形区域。可以通过 bbox_to_anchor 修改边界框。

位置示意图如下所示

+--------------+--------------+---------------+
| 'upper left' |'upper center'| 'upper right' |
+--------------+--------------+---------------+
|'center left' |   'center'   |'center right' |
+--------------+--------------+---------------+
| 'lower left' |'lower center'| 'lower right' |
+--------------+--------------+---------------+

位置也可以是一个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 放置图例的框。这是一个用于自由放置图例的高级选项。对于大多数用例，仅使用 loc 就足够了。

默认为 axes.bbox（如果作为 Axes.legend 的方法调用）或 figure.bbox（如果作为 figure.legend）。

Bbox 坐标由 bbox_transform 给定的坐标系解释，默认变换取决于调用 legend 的是 Axes 还是 Figure 坐标。

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

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

二元组 (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'），也可以是颜色字符串列表。labelcolor 还可以通过使用 'linecolor'、'markerfacecolor'（或 'mfc'）或 'markeredgecolor'（或 'mec'）来匹配线条或标记的颜色。

可以使用 rcParams["legend.labelcolor"] (默认: 'None') 全局设置 Labelcolor。如果为 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')。

linewidthfloat 或 None，默认: rcParams["legend.linewidth"] (默认: None)

图例背景补丁边缘的线宽。如果为 None，使用 rcParams["patch.linewidth"] (默认: 1.0)。

于版本 3.11 新增。

mode{"expand", None}

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

bbox_transformNone 或 Transform

边界框（bbox_to_anchor）的变换。对于 None（默认值），将使用 Axes 的 matplotlib.axes.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

备注

此函数不支持某些艺术家对象（artists）。详情请参阅图例指南。

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>)[源代码]#

一次性设置多个属性。

a.set(a=A, b=B, c=C)

等同于

a.set_a(A)
a.set_b(B)
a.set_c(C)

除全名属性外，还支持别名，例如 set(lw=2) 等同于 set(linewidth=2)，但同时传入两者会报错。

各个 setter 的调用顺序与 set() 中的参数顺序一致。然而，大多数属性并不相互依赖，因此顺序通常无关紧要。

支持的属性包括：

属性

描述

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

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，此方法将引发异常。将来它将始终引发异常。

set_frameon(b)[源代码]#

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

参数:

bbool

set_linewidth(linewidth)[源代码]#

设置 Figure 矩形的线宽。

参数:

linewidth数字

subfigures(nrows=1, ncols=1, squeeze=True, wspace=None, hspace=None, width_ratios=None, height_ratios=None, **kwargs)[源代码]#

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

子图拥有与图形相同的艺术家方法，且逻辑上与图形相同，但无法自行打印。请参阅图形子图 (Figure subfigures)。

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

参数:

nrows, ncols整型, 默认值: 1: 子图网格的行/列数。
squeeze布尔型, 默认值: True: 如果为 True，则从返回的子图数组中挤压掉额外的维度。
wspace, hspace浮点数，默认值：None: 为子图之间的空间保留的宽度/高度量，表示为平均子图宽度/高度的分数。如果未提供，则在使用约束布局 (constrained layout) 时将从 rcParams 推断这些值（参见 ConstrainedLayoutEngine），如果不使用布局引擎，则为零。
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]"] 给出。

(源代码, png)

参数:

left浮点型，可选: 子图左边缘的位置，以图宽度的一个分数表示。
right浮点型，可选: 子图右边缘的位置，以图宽度的一个分数表示。
bottomfloat, optional: 子图底边缘的位置，以图高度的一个分数表示。
topfloat, optional: 子图顶边缘的位置，以图高度的一个分数表示。
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`	包含 `FancyBboxPatch` 属性的字典或 None
`clip_box`	未知
`clip_on`	未知
`clip_path`	未知
`color` 或 `c`	color
`figure`	`Figure` 或 `SubFigure`
`fontfamily` 或 `family` 或 `fontname`	{FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'}
`fontfeatures`	字符串列表、字符串元组或 None
`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` or `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
`language`	str 或 None
`linespacing`	'normal' 或浮点数，默认：'normal'
`math_fontfamily`	str
`mouseover`	布尔值
`multialignment` 或 `ma`	{'left', 'right', 'center'}
`parse_math`	布尔值
`path_effects`	`AbstractPathEffect` 的列表
`picker`	None 或布尔值或浮点数或可调用对象
`position`	(浮点数, 浮点数)
`rasterized`	布尔值
`rotation`	float 或 {'vertical', 'horizontal'}
`rotation_mode`	{None, 'default', 'anchor', 'xtick', 'ytick'}
`sketch_params`	(scale: 浮点数, length: 浮点数, randomness: 浮点数)
`snap`	布尔值或 None
`text`	object
`transform`	`变换`
`transform_rotates_text`	布尔值
`url`	str
`usetex`	布尔值，默认：`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.] 范围内。如有必要，将调整默认高度以确保符合此要求。

参数:

arg浮点数或二维数组: 如果是浮点数，这定义了长宽比（即高度/宽度的比值）。如果是数组，长宽比为行数/列数，以便数组能无畸变地放入图形中。

返回:

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)

matplotlib.figure#

图形 (Figure)#

Figure 类#

添加 Axes（坐标轴）和 SubFigures（子图形）#

保存#

标注#

图形几何结构#

子图布局#

不推荐或已弃用#

交互式#

修改外观#

添加和获取 Artists#

获取和修改状态#

SubFigure#

SubFigure 类#

添加 Axes 和 SubFigures#

标注#

添加和获取 Artists#

修改外观#

透传方法#

FigureBase 父类#

辅助函数#

`matplotlib.figure`#