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

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

Список графических объектов (линий, фигур), которые нужно добавить в легенду. Используйте вместе с параметром 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, что формирует фон легенды.

shadowbool, default: rcParams["legend.shadow"] (default: 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, png)

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

Выбор границ для ошибок

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

Вывод маскрованных и NaN значений

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

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

Пример функции step

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

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

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

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

Легенда для полярных диаграмм

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

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

matplotlib.pyplot.legend

Примечания

Примеры

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

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