matplotlib.pyplot.legend

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

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

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

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

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

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

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

Legend

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

locстрока или пара чисел с плавающей точкой, по умолчанию: rcParams["legend.loc"] (по умолчанию: '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', и каждое расположение "строка" также может быть задано как числовое значение:

Расположение (строка)	Код расположения
'лучшее' (только для осей)	0
'вверху справа'	1
'вверху слева'	2
'внизу слева'	3
'внизу справа'	4
'справа'	5
'по центру слева'	6
'по центру справа'	7
'внизу по центру'	8
'вверху по центру'	9
'по центру'	10

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.

выравнивание{'center', 'left', 'right'}, по умолчанию: 'center': Выравнивание заголовка легенды и блока элементов. Элементы выравниваются как единый блок, так что маркеры всегда выстраиваются в одну линию.
borderpadfloat, по умолчанию: rcParams["legend.borderpad"] (по умолчанию: 0.4): Пробел внутри границы легенды, в единицах размера шрифта.
labelspacingfloat, по умолчанию: rcParams["legend.labelspacing"] (по умолчанию: 0.5): Вертикальное расстояние между элементами легенды, в единицах размера шрифта.
handlelengthfloat, по умолчанию: rcParams["legend.handlelength"] (по умолчанию: 2.0): Длина маркеров легенды, в единицах размера шрифта.
handleheightfloat, по умолчанию: rcParams["legend.handleheight"] (по умолчанию: 0.7): Высота маркеров легенды, в единицах размера шрифта.
handletextpadfloat, по умолчанию: rcParams["legend.handletextpad"] (по умолчанию: 0.8): Отступ между маркером легенды и текстом, в единицах размера шрифта.
borderaxespadfloat, по умолчанию: rcParams["legend.borderaxespad"] (по умолчанию: 0.5): Отступ между областью графика и границей легенды, в единицах размера шрифта.
columnspacingfloat, по умолчанию: rcParams["legend.columnspacing"] (по умолчанию: 2.0): Отступ между столбцами, в единицах размера шрифта.
handler_mapdict или None: Пользовательский словарь, сопоставляющий экземпляры или типы с обработчиком легенды. Этот handler_map обновляет стандартный словарь обработчиков, который можно найти по адресу matplotlib.legend.Legend.get_legend_handler_map.
draggablebool, по умолчанию: False: Можно ли перетаскивать легенду мышкой.

См. также

Figure.legend

Примечания

Примечание

Это обертка pyplot для axes.Axes.legend.

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

Примеры

(Source code, 2x.png, png)

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

Выбор пределов для столбцов погрешностей

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

Построение графиков с пропущенными значениями и NaN

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

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

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

Контурные диаграммы с заливкой и штриховкой

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

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

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

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

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

Руководство по быстрому началу

matplotlib.pyplot.legend

Примечания

Примеры

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

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