Python matplotlib FigureBase.legend用法及代码示例

本文简要介绍 python 语言中 matplotlib.figure.FigureBase.legend 的用法。

用法

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. 标记现有的情节元素

灰心

不鼓励使用此调用签名，因为绘图元素和标签之间的关系仅由它们的顺序隐含并且很容易混淆。

要为所有轴上的所有艺术家制作图例，请使用可迭代的字符串调用此函数，每个图例项一个。例如：

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

在这种情况下，手柄和标签的长度应该相同。如果不是，则将它们截断为较小的长度。

labels str 列表，可选

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

返回：

Legend

其他参数：

loc str 或一对浮点数，默认值：'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' ，并且每个 "string" 位置也可以以数值形式给出：

位置字符串	位置代码
'best'(仅限轴)	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' 获得更好的布局行为。拐角处存在歧义，因此“右上外侧”将为布局中其余轴上方的图例留出空间，而“右上外侧”将为布局的右侧留出空间。除了上面列出的 loc 的值之外，我们还有“外侧右上”、“外侧右下”、“外侧左上”和“外侧左下”。有关更多详细信息，请参阅图例指南。

bbox_to_anchor BboxBase 、2 元组或 4 元组的浮点数

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

Bbox 坐标在 bbox_transform 给出的坐标系中解释，默认变换 Axes 或图形坐标，取决于调用哪个 legend。

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

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

2 元组 (x, y) 将由 loc 指定的图例的角放置在 x、y 处。例如，要将图例的右上角放在轴(或图形)的中心，可以使用以下关键字：

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

ncols 整数，默认值：1

图例的列数。

为了向后兼容，还支持拼写 ncol，但不鼓励这样做。如果两者都给出，则 ncols 优先。

prop 无或 FontProperties 或字典

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

fontsize int 或 {'xx-small'、'x-small'、'small', 'medium', 'large'、'x-large'、'xx-large'}

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

labelcolor str 或列表，默认：rcParams["legend.labelcolor"](默认：'None')

图例中文本的颜色。一个有效的颜色字符串(例如，'red')，或者一个颜色字符串列表。也可以使用'linecolor', 'markerfacecolor'(或'mfc')或'markeredgecolor'(或'mec')使标签颜色与线条或标记的颜色相匹配。

Labelcolor 可以使用 rcParams["legend.labelcolor"] 全局设置(默认值：'None')。如果没有，请使用 rcParams["text.color"](默认值：'black')。

numpoints int，默认值：rcParams["legend.numpoints"](默认值：1)

为 Line2D (行)创建图例条目时图例中的标记点数。

scatterpoints int，默认值：rcParams["legend.scatterpoints"](默认值：1)

为 PathCollection (散点图)创建图例条目时图例中的标记点数。

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

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

markerscale 浮点数，默认：rcParams["legend.markerscale"](默认：1.0)

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

markerfirst 布尔值，默认值：真

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

reverse 布尔值，默认值：假

如果 True ，图例标签将以与输入相反的顺序显示。如果是 False ，则图例标签的显示顺序与输入的顺序相同。

3.7 版中的新函数。

frameon 布尔值，默认值：rcParams["legend.frameon"](默认值：True)

图例是否应绘制在补丁(框架)上。

fancybox 布尔值，默认值：rcParams["legend.fancybox"](默认值：True)

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

shadow None、bool 或 dict，默认值：rcParams["legend.shadow"] (默认值：False )

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

framealpha 浮点数，默认：rcParams["legend.framealpha"](默认：0.8)

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

facecolor "inherit" 或颜色，默认：rcParams["legend.facecolor"](默认：'inherit')

图例的背景颜色。如果 "inherit" ，请使用 rcParams["axes.facecolor"] (默认值：'white' )。

edgecolor "inherit" 或颜色，默认：rcParams["legend.edgecolor"](默认：'0.8')

图例的背景补丁边颜色。如果 "inherit" ，请使用 rcParams["axes.edgecolor"] (默认值：'black' )。

mode {"expand"，无}

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

bbox_transform 无或 Transform

边界框的变换 (bbox_to_anchor)。对于 None(默认)的值，将使用轴的 transAxes 变换。

title str 或 None

传说的标题。默认为无标题 (None)。

title_fontproperties 无或 FontProperties 或字典

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

title_fontsize int 或 {'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'

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

borderpad 浮点数，默认：rcParams["legend.borderpad"](默认：0.4)

图例边框内的小数空格，以font-size 为单位。

labelspacing 浮点数，默认：rcParams["legend.labelspacing"](默认：0.5)

图例条目之间的垂直间距，以font-size 为单位。

handlelength 浮点数，默认：rcParams["legend.handlelength"](默认：2.0)

图例句柄的长度，以font-size 为单位。

handleheight 浮点数，默认：rcParams["legend.handleheight"](默认：0.7)

图例手柄的高度，以font-size 为单位。

handletextpad 浮点数，默认：rcParams["legend.handletextpad"](默认：0.8)

图例句柄和文本之间的填充，以font-size 为单位。

borderaxespad 浮点数，默认：rcParams["legend.borderaxespad"](默认：0.5)

轴和图例边框之间的填充，以font-size 为单位。

columnspacing 浮点数，默认：rcParams["legend.columnspacing"](默认：2.0)

列之间的间距，以font-size 为单位。

handler_map dict 或 None

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

draggable 布尔值，默认值：假

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

注意

此函数不支持某些艺术家。有关详细信息，请参阅图例指南。