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

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), необязательно

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

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

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

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

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

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

Legend

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

END_OF_DOCUMENT_MARKER

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

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

Простая паразит-ось

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

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

Структура графика

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

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

Эффект пути TickedStroke

Отображение 2D данных на 3D графике

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

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

Несколько осей Y со спинами

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

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

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

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

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

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

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

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

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

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

matplotlib.axes.Axes.legend

Примечания

Примеры

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

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