matplotlib.axes.Axes.legend

Axes.legend(self, *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
'верхний правый'	1
'верхний левый'	2
'нижний левый'	3
'нижний правый'	4
'правый'	5
'центр слева'	6
'центр справа'	7
'нижний центр'	8
'верхний центр'	9
'центр'	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().