matplotlib.pyplot.figlegend

matplotlib.pyplot.figlegend(*args, **kwargs)[source]

Размещение легенды на рисунке.

Подписи вызовов:

figlegend()
figlegend(handles, labels)
figlegend(handles=handles)
figlegend(labels)

Подписи вызовов соответствуют различным способам использования этого метода:

1. Автоматическое определение элементов, которые нужно отобразить в легенде

Элементы, которые нужно добавить в легенду, определяются автоматически, если вы не передаёте дополнительных аргументов.

В этом случае метки берутся из объекта-графического элемента. Вы можете указать их при создании графического элемента или вызвав метод set_label() для этого элемента:

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

или:

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

Отдельные линии можно исключить из автоматического выбора элементов легенды, задав метку, начинающуюся с нижнего подчеркивания. Это значение по умолчанию для всех графических элементов, поэтому вызов Figure.legend без аргументов и без ручного задания меток не приведет к отображению легенды.

2. Явное указание графических элементов и меток в легенде

Для полного управления тем, какие графические элементы имеют запись в легенде, можно передать итерируемый объект из графических элементов легенды и итерируемый объект из меток легенды соответственно:

fig.figlegend([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.figlegend(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.figlegend(['the blues', 'the reds'])

Параметры:

handlesсписок Artist, необязательно

Список графических элементов (линий, областей) для добавления в легенду. Используйте это вместе с labels, если вам нужен полный контроль над тем, что отображается в легенде, и автоматический механизм, описанный выше, недостаточен.

Длина элементов handles и меток labels должна быть одинаковой в этом случае. Если они не совпадают, они усекаются до меньшей длины.

labelsсписок str, необязательно

Список меток, которые нужно отобразить рядом с графическими элементами. Используйте это вместе с handles, если вам нужен полный контроль над тем, что отображается в легенде, и автоматический механизм, описанный выше, недостаточен.

Возвращаемое значение:

Legend

Другие параметры:

locstr or pair of floats, default: rcParams["legend.loc"] (default: 'best') ('best' for axes, 'upper right' for figures)

Положение легенды.

Строки 'upper left', 'upper right', 'lower left', 'lower right' размещают легенду в соответствующем углу осей/графика.

Строки 'upper center', 'lower center', 'center left', 'center right' размещают легенду в центре соответствующей стороны осей/графика.

Строка 'center' размещает легенду в центре осей/графика.

Строка 'best' размещает легенду в позиции, среди девяти определённых позиций, с минимальным перекрытием с другими отрисованными элементами. Этот вариант может быть достаточно медленным для графиков с большим количеством данных; ваша скорость построения графиков может увеличиться, если вы укажете конкретное положение.

Положение также может быть 2-кортежем, задающим координаты левого нижнего угла легенды в координатах осей (в этом случае bbox_to_anchor будет проигнорирован).

Для обратной совместимости, 'center right' (но не другие положения) также может быть написано как 'right', и каждое "строковое" положение также может быть задано числовым значением:

Строковое обозначение положения	Код положения
'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

bbox_to_anchorBboxBase, 2-tuple, or 4-tuple of floats

Прямоугольник, используемый для позиционирования легенды совместно с loc. По умолчанию axes.bbox (если вызывается как метод для Axes.legend) или figure.bbox (если Figure.legend). Этот аргумент позволяет произвольное размещение легенды.

Координаты прямоугольника интерпретируются в системе координат, заданной bbox_transform, по умолчанию в координатах осей или графика, в зависимости от того, какой legend вызывается.

Если задан 4-кортеж или BboxBase, то он задаёт прямоугольник (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)

ncolsint, default: 1

Количество столбцов в легенде.

Для обратной совместимости, также поддерживается написание ncol, но это не рекомендуется. Если оба значения заданы, ncols имеет приоритет.

propNone or matplotlib.font_manager.FontProperties or dict

Свойства шрифта легенды. Если None (по умолчанию), будут использоваться текущие параметры matplotlib.rcParams.

fontsizeint or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}

Размер шрифта легенды. Если значение является числом, размер будет абсолютным размером шрифта в пунктах. Строковые значения относительны к текущему размеру шрифта по умолчанию. Этот аргумент используется только если prop не указан.

labelcolorstr or list, default: rcParams["legend.labelcolor"] (default: 'None')

Цвет текста в легенде. Может быть строкой (например, 'red') или списком строк с цветами. Цвет метки может быть задан, чтобы соответствовать цвету линии или маркера, используя 'linecolor', 'markerfacecolor' (или 'mfc'), или 'markeredgecolor' (или 'mec').

Цвет метки может быть задан глобально используя rcParams["legend.labelcolor"] (по умолчанию 'None'). Если None, используется rcParams["text.color"] (по умолчанию 'black').

numpointsint, default: rcParams["legend.numpoints"] (default: 1)

Количество маркеров в легенде при создании записи легенды для Line2D (линии).

scatterpointsint, default: rcParams["legend.scatterpoints"] (default: 1)

Количество маркеров в легенде при создании записи легенды для PathCollection (графика рассеяния).

scatteryoffsetsiterable of floats, default: [0.375, 0.5, 0.3125]

Вертикальное смещение (относительно размера шрифта) маркеров, созданных для записи легенды графика рассеяния. 0.0 - внизу текста легенды, 1.0 - вверху. Чтобы нарисовать все маркеры на одной высоте, установите значение [0.5].

markerscalefloat, default: rcParams["legend.markerscale"] (default: 1.0)

Относительный размер маркеров в легенде по сравнению с исходно нарисованными.

markerfirstbool, default: True

Если True, маркер легенды размещается слева от метки легенды. Если False, маркер легенды размещается справа от метки легенды.

frameonbool, default: rcParams["legend.frameon"] (default: True)

Определяет, должна ли легенда отображаться на области (рамке).

fancyboxbool, default: rcParams["legend.fancybox"] (default: True)

Определяет, должны ли быть включены закругленные углы вокруг FancyBboxPatch, формирующего фон легенды.

shadowbool, default: rcParams["legend.shadow"] (default: False)

Отображать ли тень за легендой.

framealphafloat, default: rcParams["legend.framealpha"] (default: 0.8)

Альфа-прозрачность фона легенды. Если shadow активирован и framealpha None, значение по умолчанию игнорируется.

facecolor"inherit" or color, default: rcParams["legend.facecolor"] (default: 'inherit')

Цвет фона легенды. Если "inherit", использовать rcParams["axes.facecolor"] (по умолчанию 'white').

edgecolor"inherit" or color, default: rcParams["legend.edgecolor"] (default: '0.8')

Цвет обводки фона легенды. Если "inherit", использовать значение rcParams["axes.edgecolor"] (по умолчанию 'black').

mode{"expand", None}

Если mode установлено в "expand", легенда будет горизонтально расширена для заполнения области осей (или bbox_to_anchor, если он определяет размер легенды).

bbox_transformNone or matplotlib.transforms.Transform

Преобразование для прямоугольника (bbox_to_anchor). Для значения None (по умолчанию) будет использоваться преобразование осей transAxes.

titlestr or None

Заголовок легенды. По умолчанию заголовок отсутствует (None).

title_fontpropertiesNone or matplotlib.font_manager.FontProperties or dict

Свойства шрифта заголовка легенды. Если None (по умолчанию), будет использован аргумент title_fontsize, если он присутствует; если title_fontsize также None, будут использоваться текущие rcParams["legend.title_fontsize"] (по умолчанию None).

title_fontsizeint or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}, default: rcParams["legend.title_fontsize"] (default: None)

Размер шрифта заголовка легенды. Примечание: не может быть использован вместе с title_fontproperties. Если вы хотите задать размер шрифта наряду с другими свойствами шрифта, используйте параметр size в title_fontproperties.

alignment{'center', 'left', 'right'}, default: 'center'

Выравнивание заголовка легенды и области записей. Записи выравниваются как единый блок, так что маркеры всегда выстроены.

borderpadfloat, default: rcParams["legend.borderpad"] (default: 0.4)

Пробел внутри рамки легенды, в единицах размера шрифта.

labelspacingfloat, default: rcParams["legend.labelspacing"] (default: 0.5)

Вертикальное расстояние между записями легенды, в единицах размера шрифта.

handlelengthfloat, default: rcParams["legend.handlelength"] (default: 2.0)

Длина рукояток легенды в единицах размера шрифта.

handleheightfloat, default: rcParams["legend.handleheight"] (default: 0.7)

Высота рукояток легенды в единицах размера шрифта.

handletextpadfloat, default: rcParams["legend.handletextpad"] (default: 0.8)

Отступ между рукояткой легенды и текстом в единицах размера шрифта.

borderaxespadfloat, default: rcParams["legend.borderaxespad"] (default: 0.5)

Отступ между осью и границей легенды в единицах размера шрифта.

columnspacingfloat, default: rcParams["legend.columnspacing"] (default: 2.0)

Интервал между столбцами в единицах размера шрифта.

handler_mapdict or None

Пользовательский словарь, сопоставляющий экземпляры или типы с обработчиком легенды. Этот handler_map обновляет стандартный словарь обработчиков, который находится в matplotlib.legend.Legend.get_legend_handler_map.

См. также

Axes.legend

Примечания

Некоторые объекты-артисты не поддерживаются этой функцией. Подробности см. в Руководстве по легендам.