matplotlib.axes.Axes.legend

Axes.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, если вам нужен полный контроль над отображаемыми элементами в легенде, и автоматический механизм, описанный выше, недостаточен.

Длина маркёров и меток должна быть одинаковой. В противном случае они будут урезаны до меньшей длины.

labels : sequence of strings, optional

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

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

: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, он определяет прямоугольник (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().