matplotlib.pyplot.figlegend

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

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

Вызовы:

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

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

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

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

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

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

или:

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

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

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

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

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

Параметры:

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

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

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

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

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

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

Legend

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

locstr или пара чисел с плавающей точкой, по умолчанию: 'верхний правый'

Расположение легенды.

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

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

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

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

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

Строка расположения	Код расположения
'лучшее' (только для Axes)	0
'верхний правый'	1
'верхний левый'	2
'нижний левый'	3
'нижний правый'	4
'правый'	5
'центр слева'	6
'центр справа'	7
'нижний центр'	8
'верхний центр'	9
'центр'	10

Если фигура использует менеджер ограниченной компоновки, строковые коды аргумента ключевого слова loc могут обеспечить лучшее поведение компоновки с префиксом 'outside'. Возникает неоднозначность в углах, поэтому 'outside верхний правый' создаст место для легенды над остальной частью осей в компоновке, а 'outside правый верхний' создаст место справа в компоновке. Помимо значений loc, перечисленных выше, у нас также есть 'outside правый верхний', 'outside правый нижний', 'outside левый верхний' и 'outside левый нижний'. Для получения дополнительной информации см. Руководство по легендам.

bbox_to_anchorBboxBase, 2-кортеж или 4-кортеж чисел с плавающей точкой

Прямоугольник, используемый для позиционирования легенды совместно с 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)

ncolsцелое число, по умолчанию: 1

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

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

propNone или FontProperties или dict

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

fontsizeцелое число или {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}

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

labelcolorстрока или список, по умолчанию: rcParams["legend.labelcolor"] (по умолчанию: 'None')

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

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

numpointsцелое число, по умолчанию: rcParams["legend.numpoints"] (по умолчанию: 1)

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

scatterpointsцелое число, по умолчанию: 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

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

reverseбулево значение, по умолчанию: False

Если True, метки легенды отображаются в обратном порядке от входных данных. Если False, метки легенды отображаются в том же порядке, что и входные данные.

Добавлено в версии 3.7.

frameonбулево значение, по умолчанию: rcParams["legend.frameon"] (по умолчанию: True)

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

fancyboxбулево значение, по умолчанию: rcParams["legend.fancybox"] (по умолчанию: True)

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

shadowNone, булево значение или dict, по умолчанию: rcParams["legend.shadow"] (по умолчанию: False)

Определяет, должна ли легенда рисовать тень. Тень можно настроить, используя ключевые слова Patch. Настройка через rcParams["legend.shadow"] (по умолчанию: False) в настоящее время не поддерживается.

framealphaчисло с плавающей точкой, по умолчанию: rcParams["legend.framealpha"] (по умолчанию: 0.8)

Альфа-прозрачность фона легенды. Если 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", None}

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

bbox_transformNone или Transform

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

titleстрока или None

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

title_fontpropertiesNone или FontProperties или dict

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

title_fontsizeцелое число или {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}, по умолчанию: rcParams["legend.title_fontsize"] (по умолчанию: 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.

draggablebool, default: False

Можно ли перетаскивать легенду мышкой?

См. также

Axes.legend

Примечания

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