matplotlib.pyplot.legend

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

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

Подписи функций:

legend()
legend(handles, labels)
legend(handles=handles)
legend(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. Явное указание объектов-графических элементов и меток в легенде

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

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

3. Явное указание объектов-графических элементов в легенде

Это аналогично пункту 2, но метки берутся из свойств меток объектов-графических элементов. Пример:

line1, = ax.plot([1, 2, 3], label='label1')
line2, = ax.plot([1, 2, 3], label='label2')
ax.legend(handles=[line1, line2])

4. Подпись существующих элементов графика

Не рекомендуется

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

Чтобы создать легенду для всех объектов-графических элементов на оси, вызовите эту функцию с итерируемым объектом строк, по одной строке для каждого элемента легенды. Например:

ax.plot([1, 2, 3])
ax.plot([5, 6, 7])
ax.legend(['First line', 'Second line'])

Параметры

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

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

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

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

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

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

Legend

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

locstr или пара чисел с плавающей точкой, по умолчанию: 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
'upper right'	1
'upper left'	2
'lower left'	3
'lower right'	4
'right'	5
'center left'	6
'center right'	7
'lower center'	8
'upper center'	9
'center'	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строка или список, по умолчанию: rcParams["legend.labelcolor"] (по умолчанию: 'None')

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

Цвет метки можно задать глобально с помощью rcParams["legend.labelcolor"] (по умолчанию: 'None'). Если None, используется rcParams["text.color"] (по умолчанию: 'black').

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_fontpropertiesNone или matplotlib.font_manager.FontProperties или словарь

Свойства шрифта заголовка легенды. Если None (по умолчанию), будет использован аргумент title_fontsize, если он указан; если title_fontsize также None, будут использоваться текущие rcParams["legend.title_fontsize"] (по умолчанию: None).

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

Размер шрифта заголовка легенды. Примечание: это нельзя комбинировать с title_fontproperties. Если нужно задать размер шрифта вместе с другими его свойствами, используйте параметр size в title_fontproperties.

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

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

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

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

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

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

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

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

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.

См. также

Figure.legend

Примечания

Некоторые объекты графики не поддерживаются этой функцией. Подробности см. в Руководстве по легендам.

Примеры

(Исходный код, png, pdf)

Примеры использования matplotlib.pyplot.legend