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: 'upper right'

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

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

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

bbox_to_anchor : BboxBase or pair of floats

Задайте любое произвольное расположение легенды в bbox_transform координатах (по умолчанию координаты осей).

Например, чтобы поместить верхний правый угол легенды в центр осей, можно использовать следующие ключевые слова:

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).

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().