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.set_label('Label via method')
line, = ax.plot([1, 2, 3])
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 : sequence of strings, optional

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

Возвращает:

экземпляр :class:`matplotlib.legend.Legend`

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

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

Расположение легенды. Возможные коды:

Строка расположения	Код расположения
'best'	0
'верхний правый'	1
'верхний левый'	2
'нижний левый'	3
'нижний правый'	4
'правый'	5
'центр слева'	6
'центр справа'	7
'нижний центр'	8
'верхний центр'	9
'центр'	10

В качестве альтернативы может быть 2-кортеж, задающий x, y левого нижнего угла легенды в координатах осей (в этом случае bbox_to_anchor будет проигнорировано).

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, он определяет Bbox (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().