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
'верхний правый'	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)

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

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

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

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 (график рассеяния).

scatteryoffsetsитерируемый объект чисел с плавающей точкой, по умолчанию: [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.

alignment{'center', 'left', 'right'}, по умолчанию: 'center'

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

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

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

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

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

handlelengthчисло с плавающей точкой, по умолчанию: rcParams["legend.handlelength"] (по умолчанию: 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.

См. также

Figure.legend

Примечания

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

Примеры

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

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

Выбор пределов для errorbar

Вывод замаскированных и NaN значений

Руководство по легендам

matplotlib.pyplot.legend

Примечания

Примеры

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

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