matplotlib.figure.SubFigure.legend

SubFigure.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

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

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', и каждое расположение "строкой" также может быть задано числовым значением:

Строка расположения	Код расположения
'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_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)

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

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

Примечания

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