matplotlib.pyplot.legend

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

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

Подписи вызова:

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

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

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

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

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

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. Явное определение элементов в легенде

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

ax.legend([line1, line2, line3], ['label1', 'label2', 'label3'])

Параметры:

Параметры:	handlesпоследовательность `Artist`, необязательно Список графических элементов (линий, областей) для добавления в легенду. Используйте это вместе с labels, если вам нужен полный контроль над тем, что отображается в легенде, и автоматический механизм, описанный выше, недостаточен. Длина handles и labels в этом случае должна быть одинаковой. Если это не так, они обрезаются до меньшей длины. labelsсписок str, необязательно Список меток, которые будут отображаться рядом с графическими элементами. Используйте это вместе с handles, если вам нужен полный контроль над тем, что отображается в легенде, и автоматический механизм, описанный выше, недостаточен.
Возвращает:	`Legend`

handlesпоследовательность Artist, необязательно

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

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

labelsсписок str, необязательно

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

Возвращает:

Legend

END_OF_DOCUMENT_MARKER

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

locстрока или пара чисел с плавающей точкой, по умолчанию: rcParams["legend.loc"] (по умолчанию: 'best') ('best' для осей, 'верхний правый' для фигур)

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

Строки '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_anchorBboxBase, 2-кортеж или 4-кортеж чисел с плавающей точкой

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

Координаты прямоугольника интерпретируются в системе координат, заданной 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целое число, по умолчанию: 1

Количество столбцов в легенде.

propNone или matplotlib.font_manager.FontProperties или словарь

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

fontsizeцелое число или {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}

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

labelcolorстрока или список

Цвет текста в легенде. Либо допустимая строка цвета (например, 'red'), либо список строк цвета. Цвет метки также может быть сделан соответствующим цвету линии или маркера, используя 'linecolor', 'markerfacecolor' (или 'mfc'), или 'markeredgecolor' (или 'mec').

numpointsцелое число, по умолчанию: rcParams["legend.numpoints"] (по умолчанию: 1)

Количество точек маркера в легенде при создании записи легенды для Line2D (линия).

scatterpointsцелое число, по умолчанию: rcParams["legend.scatterpoints"] (по умолчанию: 1)

Количество точек маркера в легенде при создании записи легенды для PathCollection (разброс точек).

scatteryoffsetsитерируемый список чисел с плавающей точкой, по умолчанию: [0.375, 0.5, 0.3125]

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

markerscaleчисло с плавающей точкой, по умолчанию: rcParams["legend.markerscale"] (по умолчанию: 1.0)

Относительный размер маркеров легенды по сравнению с исходно нарисованными.

markerfirstбулево значение, по умолчанию: True

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

frameonбулево значение, по умолчанию: rcParams["legend.frameon"] (по умолчанию: True)

Определяет, должна ли легенда быть нарисована на области (рамке).

fancyboxбулево значение, по умолчанию: rcParams["legend.fancybox"] (по умолчанию: True)

Определяет, должны ли быть активированы округлые углы вокруг FancyBboxPatch, который образует фон легенды.

shadowбулево значение, по умолчанию: rcParams["legend.shadow"] (по умолчанию: False)

Определяет, нужно ли рисовать тень за легендой.

framealphaчисло с плавающей точкой, по умолчанию: rcParams["legend.framealpha"] (по умолчанию: 0.8)

Альфа-прозрачность фона легенды. Если shadow активирован и framealpha равно None, значение по умолчанию игнорируется.

facecolor"inherit" или цвет, по умолчанию: rcParams["legend.facecolor"] (по умолчанию: 'inherit')

Цвет фона легенды. Если "inherit", использовать rcParams["axes.facecolor"] (по умолчанию: 'white').

edgecolor"inherit" или цвет, по умолчанию: rcParams["legend.edgecolor"] (по умолчанию: '0.8')

Цвет края фона легенды. Если "inherit", использовать значение rcParams["axes.edgecolor"] (по умолчанию: 'black').

mode{"expand", None}

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

bbox_transformNone или matplotlib.transforms.Transform

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

titleстрока или None

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

title_fontsizeцелое число или {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}, по умолчанию: rcParams["legend.title_fontsize"] (по умолчанию: None)

Размер шрифта заголовка легенды.

borderpadчисло с плавающей точкой, по умолчанию: rcParams["legend.borderpad"] (по умолчанию: 0.4)

Пробел внутри рамки легенды в единицах размера шрифта.

labelspacingчисло с плавающей точкой, по умолчанию: rcParams["legend.labelspacing"] (по умолчанию: 0.5)

Вертикальное расстояние между записями легенды в единицах размера шрифта.

handlelengthчисло с плавающей точкой, по умолчанию: rcParams["legend.handlelength"] (по умолчанию: 2.0)

Длина рукояток легенды в единицах размера шрифта.

handletextpadчисло с плавающей точкой, по умолчанию: rcParams["legend.handletextpad"] (по умолчанию: 0.8)

Отступ между рукояткой легенды и текстом в единицах размера шрифта.

borderaxespadчисло с плавающей точкой, по умолчанию: rcParams["legend.borderaxespad"] (по умолчанию: 0.5)

Отступ между осями и рамкой легенды в единицах размера шрифта.

columnspacingчисло с плавающей точкой, по умолчанию: rcParams["legend.columnspacing"] (по умолчанию: 2.0)

Расстояние между столбцами в единицах размера шрифта.

handler_mapсловарь или None

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