matplotlib.pyplot.legend

matplotlib.pyplot.legend(*args, **kwargs) [source]

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

Варианты вызова:

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

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

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

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

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

line, = 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. Присвоение меток существующим элементам графика

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

ax.plot([1, 2, 3])
ax.legend(['A simple line'])

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

3. Явное определение элементов в легенде

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

legend((line1, line2, line3), ('label1', 'label2', 'label3'))

Параметры:

handles : sequence of Artist, optional

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

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

labels : sequence of strings, optional

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

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

matplotlib.legend.Legend instance

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

loc : str or pair of floats, default: rcParams["legend.loc"] ('best' for axes, 'upper right' for figures)

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

Строки '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
'upper right'	1
'upper left'	2
'lower left'	3
'lower right'	4
'right'	5
'center left'	6
'center right'	7
'lower center'	8
'upper center'	9
'center'	10

bbox_to_anchor : BboxBase, 2-tuple, or 4-tuple of floats

Прямоугольник, используемый для позиционирования легенды в сочетании с loc. По умолчанию axes.bbox (если вызывается как метод для Axes.legend) или figure.bbox (если Figure.legend). Этот аргумент позволяет произвольное размещение легенды.

Координаты Bbox интерпретируются в системе координат, заданной 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)

ncol : integer

Количество столбцов в легенде. По умолчанию 1.

prop : None or matplotlib.font_manager.FontProperties or dict

Свойства шрифта легенды. Если None (по умолчанию), будут использоваться текущие значения matplotlib.rcParams.

fontsize : int or float or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}

Управляет размером шрифта легенды. Если значение является числовым, размер будет абсолютным размером шрифта в пунктах. Строковые значения являются относительными по отношению к текущему размеру шрифта по умолчанию. Этот аргумент используется только если prop не указан.

numpoints : None or int

Количество маркеров на точке в легенде при создании записи легенды для Line2D (линия). По умолчанию None, которое будет принимать значение из rcParams["legend.numpoints"].

scatterpoints : None or int

Количество маркеров на точке в легенде при создании записи легенды для PathCollection (диаграмма рассеяния). По умолчанию None, которое будет принимать значение из rcParams["legend.scatterpoints"].

scatteryoffsets : iterable of floats

Вертикальное смещение (относительно размера шрифта) для маркеров, созданных для записи легенды диаграммы рассеяния. 0.0 соответствует основанию текста легенды, а 1.0 — верху. Чтобы разместить все маркеры на одной высоте, установите значение в [0.5]. По умолчанию [0.375, 0.5, 0.3125].

markerscale : None or int or float

Относительный размер маркеров легенды по сравнению с исходными. По умолчанию None, которое будет принимать значение из rcParams["legend.markerscale"].

markerfirst : bool

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

frameon : None or bool

Управление отображением легенды на блоке (рамке). По умолчанию None, которое будет принимать значение из rcParams["legend.frameon"].

fancybox : None or bool

Управление включением скругленных углов вокруг FancyBboxPatch, формирующего фон легенды. По умолчанию None, которое будет принимать значение из rcParams["legend.fancybox"].

shadow : None or bool

Управление отображением тени за легендой. По умолчанию None, которое будет принимать значение из rcParams["legend.shadow"].

framealpha : None or float

Управление альфа-прозрачностью фона легенды. По умолчанию None, которое будет принимать значение из rcParams["legend.framealpha"]. Если тень включена и framealpha — None, значение по умолчанию игнорируется.

facecolor : None or "inherit" or a color spec

Управление цветом фона легенды. По умолчанию None, которое будет принимать значение из rcParams["legend.facecolor"]. Если "inherit", оно будет принимать rcParams["axes.facecolor"].

edgecolor : None or "inherit" or a color spec

Управление цветом границы фона легенды. По умолчанию None, которое будет принимать значение из rcParams["legend.edgecolor"] Если "inherit", оно будет принимать rcParams["axes.edgecolor"].

mode : {"expand", None}

Если mode установлено в "expand", легенда будет расширена по горизонтали для заполнения области осей (или bbox_to_anchor если определяет размер легенды).

bbox_transform : None or matplotlib.transforms.Transform

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

title : str or None

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

title_fontsize: str или None

Размер шрифта заголовка легенды. По умолчанию размер шрифта по умолчанию.

borderpad : float or None

Пространство внутри рамки легенды. Измеряется в единицах размера шрифта. По умолчанию None, которое будет принимать значение из rcParams["legend.borderpad"].

labelspacing : float or None

Вертикальное расстояние между записями легенды. Измеряется в единицах размера шрифта. По умолчанию None, которое будет принимать значение из rcParams["legend.labelspacing"].

handlelength : float or None

Длина маркеров легенды. Измеряется в единицах размера шрифта. По умолчанию None, которое будет принимать значение из rcParams["legend.handlelength"].

handletextpad : float or None

Отступ между маркером легенды и текстом. Измеряется в единицах размера шрифта. По умолчанию None, которое будет принимать значение из rcParams["legend.handletextpad"].

borderaxespad : float or None

Отступ между осями и рамкой легенды. Измеряется в единицах размера шрифта. По умолчанию None, которое будет принимать значение из rcParams["legend.borderaxespad"].

columnspacing : float or None

Интервал между столбцами. Измеряется в единицах размера шрифта. По умолчанию None, которое будет принимать значение из rcParams["legend.columnspacing"].

handler_map : dict or None

Пользовательский словарь, сопоставляющий экземпляры или типы с обработчиком легенды. Этот handler_map обновляет словарь обработчиков по умолчанию, который находится по адресу matplotlib.legend.Legend.get_legend_handler_map().