matplotlib.axes.Axes.legend

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

Размещает легенду на оси.

Подписи:

legend()
legend(handles, labels)
legend(handles=handles)
legend(labels)

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

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

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

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

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

или:

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

Примечание

Конкретные объекты могут быть исключены из автоматического выбора элементов легенды, если их метка начинается с символа подчёркивания, "_". Строка, начинающаяся с подчёркивания, является стандартной меткой для всех объектов, поэтому вызов Axes.legend без аргументов и без ручного задания меток не приведет к отображению легенды.

2. Явное указание объектов и меток в легенде

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

ax.legend([line1, line2, line3], ['label1', 'label2', 'label3'])

3. Явное указание объектов в легенде

Это аналогично пункту 2, но метки берутся из свойств меток объектов. Пример:

line1, = ax.plot([1, 2, 3], label='label1')
line2, = ax.plot([1, 2, 3], label='label2')
ax.legend(handles=[line1, line2])

4. Присвоение меток существующим элементам графика

Не рекомендуется

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

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

ax.plot([1, 2, 3])
ax.plot([5, 6, 7])
ax.legend(['First line', 'Second line'])

Параметры:

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

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

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

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

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

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

Возвращает:

Legend

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

locstr or pair of floats, default: rcParams["legend.loc"] (default: 'best')

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

Строки '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
'верхний правый'	1
'верхний левый'	2
'нижний левый'	3
'нижний правый'	4
'правый'	5
'центр слева'	6
'центр справа'	7
'нижний центр'	8
'верхний центр'	9
'центр'	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 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, маркер легенды размещается справа от метки легенды.

reversebool, default: False

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

Доступно с версии 3.7.

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

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

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

Устанавливает, следует ли включить округлые края вокруг FancyBboxPatch, которая формирует фон легенды.

shadowNone, bool or dict, default: rcParams["legend.shadow"] (default: False)

Определяет, следует ли рисовать тень за легендой. Тень можно настроить, используя ключевые слова Patch. Настройка через rcParams["legend.shadow"] (по умолчанию 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 Transform

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

titlestr or None

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

title_fontpropertiesNone or 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.
draggablebool, default: False: Можно ли перетащить легенду мышью.

См. также

Figure.legend

Примечания

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

Примеры

(Source code, 2x.png, png)

Примеры использования `matplotlib.axes.Axes.legend`

Демонстрация цвета столбцов

Демонстрация меток столбцов

Столбчатая диаграмма с группами

Группированная столбчатая диаграмма с метками

Графики категориальных переменных

Заполнение области и альфа-канал

График шляп

Дискретное распределение в виде горизонтальной столбчатой диаграммы

Настройка стилей пунктирной линии

Линии с отметками

Диаграммы рассеяния с легендой

Графики столбцов и потоковые графики

Демонстрация ступенчатых функций

Контурные графики с штриховкой

Контурные графики и логарифмическая шкала цветов

Демонстрация триконтурных графиков

Вспомогательная ось

Построение эллипса доверия двумерного набора данных

Построение кумулятивных распределений

Функция гистограммы (hist) с несколькими наборами данных

Столбец-пирог

Метки на круговой и пончиковой диаграммах

Легенда на полярном графике

Создание пользовательских легенд

Легенда с предварительно определенными метками

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

Mathtext

Отображение математических уравнений с помощью TeX

Демонстрация размещения вставки

Простой паразит

Демонстрация паразитных осей

Демонстрация паразитной оси

Анатомия рисунка

Выбор легенды

Демонстрация эффекта пути

Эффект пути TickedStroke

Вывод 2D данных на 3D графике

Параметрическая кривая

Демонстрация Asinh

Множественные оси y со штифтами

Настройка формата меток для временных рядов

Групповая гистограмма с единицами

Простая легенда 01

Простая легенда 02

Быстрый старт

Анимация с помощью Matplotlib

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

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

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

Указание цветов

matplotlib.axes.Axes.legend

Примечания

Примеры

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

Примеры использования `matplotlib.axes.Axes.legend`