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

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

ncolsint, default: 1

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

Для обратной совместимости также поддерживается написание ncol, но это не рекомендуется. Если оба параметра заданы, ncols имеет приоритет.

propNone or FontProperties or dict

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

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

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

labelcolorstr or list, default: rcParams["legend.labelcolor"] (default: 'None')

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

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

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, маркер легенды размещается справа от метки легенды.

reversebool, default: False

Если True, метки легенды отображаются в обратном порядке от входных данных. Если False, метки легенды отображаются в том же порядке, что и входные данные.

Новое в версии 3.7.

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 Transform

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

titlestr or None

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

title_fontpropertiesNone or FontProperties or dict

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

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

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

alignment{'center', 'left', 'right'}, default: 'center'

Выравнивание заголовка легенды и блока записей. Записи выравниваются как единый блок, так что маркеры всегда выстраиваются в линию.

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

Дробное отступы внутри границы легенды, в единицах размера шрифта.
labelspacingfloat, default: rcParams["legend.labelspacing"] (default: 0.5): Вертикальное расстояние между элементами легенды, в единицах размера шрифта.
handlelengthfloat, default: rcParams["legend.handlelength"] (default: 2.0): Длина маркеров легенды, в единицах размера шрифта.
handleheightfloat, default: rcParams["legend.handleheight"] (default: 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.
draggablebool, default: False: Можно ли перетаскивать легенду мышкой.