matplotlib.figure.Figure.legend

Figure.legend(*args, **kwargs)[source]

Разместить легенду на рисунке.

Возможные варианты вызова:

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, если вам нужен полный контроль над тем, что отображается в легенде, и описанный выше механизм автоматического создания недостаточно.

Длина списков handles и labels должна быть одинаковой. В противном случае списки будут усечены до меньшей длины.

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

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

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

Legend

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

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

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

Строки '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' (только для осей)	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 или словарь

Свойства шрифта легенды. Если 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, логическое значение или словарь, по умолчанию: 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", легенда будет расширена по горизонтали, чтобы заполнить область осей (или bbox_to_anchor, если определяет размер легенды).

bbox_transformNone или Transform

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

titleстрока или None

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

title_fontpropertiesNone или FontProperties или словарь

Свойства шрифта заголовка легенды. Если 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.

draggablebool, default: False

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

См. также

Axes.legend

Примечания

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

Примеры использования matplotlib.figure.Figure.legend

Демонстрация легенды для всей фигуры

Демонстрация легенды для всей фигуры

Руководство по легендам

Руководство по легендам

Руководство по ограничению размеров

Руководство по ограничению размеров