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, = 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'))

Параметры:

handlessequence of Artist, optional

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

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

labelslist of str, optional

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

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

Legend

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

locstr or pair of floats, default: rcParams["legend.loc"] (default: 'best') ('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_anchorBboxBase, 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)

ncolint, default: 1

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

propNone or matplotlib.font_manager.FontProperties or dict

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

fontsizeint or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}

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

labelcolorstr or list

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

numpointsint, default: rcParams["legend.numpoints"] (default: 1)

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

scatterpointsint, default: rcParams["legend.scatterpoints"] (default: 1)

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

scatteryoffsetsiterable of floats, default: [0.375, 0.5, 0.3125]

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

markerscalefloat, default: rcParams["legend.markerscale"] (default: 1.0)

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

markerfirstbool, default: True

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

frameonbool, default: rcParams["legend.frameon"] (default: True)

Нужно ли рисовать легенду на области (рамке).

fancyboxbool, default: rcParams["legend.fancybox"] (default: True)

Нужно ли включать скругленные углы вокруг FancyBboxPatch, образующего фон легенды.

shadowbool, default: rcParams["legend.shadow"] (default: False)

Нужно ли рисовать тень позади легенды.

framealphafloat, default: rcParams["legend.framealpha"] (default: 0.8)

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

facecolor"inherit" or color, default: rcParams["legend.facecolor"] (default: 'inherit')

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

edgecolor"inherit" or color, default: rcParams["legend.edgecolor"] (default: '0.8')

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

mode{"expand", None}

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

bbox_transformNone or matplotlib.transforms.Transform

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

titlestr or None

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

title_fontsizeint or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}, default: rcParams["legend.title_fontsize"] (default: None)

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

borderpadfloat, default: rcParams["legend.borderpad"] (default: 0.4)

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

labelspacingfloat, default: rcParams["legend.labelspacing"] (default: 0.5)

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

handlelengthfloat, default: rcParams["legend.handlelength"] (default: 2.0)

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

handletextpadfloat, default: rcParams["legend.handletextpad"] (default: 0.8)

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

borderaxespadfloat, default: rcParams["legend.borderaxespad"] (default: 0.5)

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

columnspacingfloat, default: rcParams["legend.columnspacing"] (default: 2.0)

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

handler_mapdict or None

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