matplotlib.axes.Axes.legend

Axes.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') ('лучшее' для осей, 'верхний правый' для графиков)

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

Строки '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', и каждое место расположения (строка) также может быть задано числовым значением:

Строка расположения	Код расположения
'лучшее'	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)

ncolint, по умолчанию: 1

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

propNone или matplotlib.font_manager.FontProperties или dict

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

fontsizeint или {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}

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

labelcolorstr или список, по умолчанию: rcParams["legend.labelcolor"] (по умолчанию: 'None')

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

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

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

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

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

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

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

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

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

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

markerfirstbool, по умолчанию: True

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

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

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

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

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

shadowbool, по умолчанию: 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.

titlestr или None

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

title_fontpropertiesNone или matplotlib.font_manager.FontProperties или dict

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

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

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

borderpadfloat, по умолчанию: rcParams["legend.borderpad"] (по умолчанию: 0.4)

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

labelspacingfloat, по умолчанию: rcParams["legend.labelspacing"] (по умолчанию: 0.5)

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

handlelengthfloat, по умолчанию: rcParams["legend.handlelength"] (по умолчанию: 2.0)

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

handleheightfloat, по умолчанию: rcParams["legend.handleheight"] (по умолчанию: 0.7)

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

handletextpadfloat, по умолчанию: rcParams["legend.handletextpad"] (по умолчанию: 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.axes.Axes.legend