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

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

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, пара чисел, или 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, которая формирует фон легенды.

shadowбулево значение, по умолчанию: 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_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

Примечания

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