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

Расположение (строка)	Код расположения
'best' (только для осей)	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.

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: Можно ли перетаскивать легенду мышкой.