matplotlib.legend

Модуль legend определяет класс Legend, отвечающий за отображение легенд, связанных с объектами Axes и/или фигурами.

Класс Legend — это контейнер для дескрипторов и текстовых меток легенды.

Карта обработчиков легенды определяет, как создавать дескрипторы легенды из графических объектов (линий, областей и т. д.) на объектах Axes или фигурах. Обработчики легенды по умолчанию определены в модуле legend_handler. Хотя обработчики легенды по умолчанию поддерживают не все типы графических объектов, можно определить собственные обработчики легенды для поддержки произвольных объектов.

Дополнительные сведения см. в :ref`<legend_guide>`.

classmatplotlib.legend.DraggableLegend(legend, use_blit=False, update='loc')[исходный код]

Базовые классы: DraggableOffsetBox

Обёртка над объектом Legend, обеспечивающая перетаскивание мышью.

Параметры:

legendLegend

Экземпляр Legend, который нужно обернуть.

use_blitbool, необязательный

Использовать блиттинг для ускорения композиции изображений. Подробности см. в FuncAnimation.

update{'loc', 'bbox'}, необязательный

Если задано значение "loc", при завершении обновляется параметр легенды loc. Если задано значение "bbox", обновляется параметр bbox_to_anchor.

finalize_offset()[исходный код]

classmatplotlib.legend.Legend(parent, handles, labels, *, loc=None, numpoints=None, markerscale=None, markerfirst=True, reverse=False, scatterpoints=None, scatteryoffsets=None, prop=None, fontsize=None, labelcolor=None, borderpad=None, labelspacing=None, handlelength=None, handleheight=None, handletextpad=None, borderaxespad=None, columnspacing=None, ncols=1, mode=None, fancybox=None, shadow=None, title=None, title_fontsize=None, framealpha=None, edgecolor=None, facecolor=None, bbox_to_anchor=None, bbox_transform=None, frameon=None, handler_map=None, title_fontproperties=None, alignment='center', ncol=1, draggable=False)[исходный код]

Базовые классы: Artist

Разместить легенду на рисунке/в осях.

Параметры:

parentAxes или Figure

Объект Artist, содержащий легенду.

handlesсписок (Artist или кортеж объектов Artist)

Список объектов Artist (линий, областей), которые нужно добавить в легенду.

labelsсписок строк

Список меток, отображаемых рядом с объектами Artist. Длина списков handles и labels должна быть одинаковой. Если это не так, более длинный список обрезается до длины более короткого.

Атрибуты:

legend_handles

Список объектов Artist, добавленных в качестве записей легенды.

Добавлено в версии 3.7.

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

locстрока или пара чисел с плавающей точкой, по умолчанию: rcParams["legend.loc"] (значение по умолчанию: 'best') для Axes, 'upper right' для Figure

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

Строки 'upper left', 'upper right', 'lower left', 'lower right' размещают легенду в соответствующем углу осей/рисунка.

Строки 'upper center', 'lower center', 'center left', 'center right' размещают легенду по центру соответствующего края осей/рисунка.

Строка 'center' размещает легенду по центру осей/рисунка.

Строка 'best' размещает легенду в одном из девяти определённых на данный момент мест так, чтобы она как можно меньше перекрывала другие нарисованные объекты Artist. Этот вариант может работать довольно медленно для графиков с большим объёмом данных; скорость построения графика может повыситься, если указать конкретное расположение.

Расположение также можно задать кортежем из двух элементов, указывающим координаты левого нижнего угла легенды в системе координат осей/рисунка (в этом случае bbox_to_anchor будет проигнорирован).

Для обратной совместимости 'center right' (но не любое другое расположение) также можно указать как 'right', а каждое расположение в виде «строки» можно также задать числовым значением:

Строка расположения	Код расположения
'best' (только Axes)	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

Если для рисунка используется менеджер компоновки constrained layout, строковые коды аргумента loc позволяют добиться более удачной компоновки с помощью префикса 'outside'. В углах возможна неоднозначность, поэтому 'outside upper right' оставит место для легенды над остальными осями в компоновке, а 'outside right upper' оставит место справа от компоновки. Помимо перечисленных выше значений loc, доступны 'outside right upper', 'outside right lower', 'outside left upper' и 'outside left lower'. Подробнее см. в руководстве по легендам.

bbox_to_anchorBboxBase, кортеж из 2 или 4 чисел с плавающей точкой

Область, которая используется для позиционирования легенды совместно с loc. По умолчанию axes.bbox (если вызвано как метод Axes.legend) или figure.bbox (если figure.legend). Этот аргумент позволяет размещать легенду в произвольном месте.

Координаты Bbox интерпретируются в системе координат, задаваемой параметром bbox_transform. По умолчанию используются координаты Axes или Figure — в зависимости от того, какой legend вызван.

Если задан кортеж из 4 элементов или BboxBase, он задаёт ограничивающую рамку bbox (x, y, width, height), в которой размещается легенда. Чтобы поместить легенду в наилучшее место в правом нижнем квадранте Axes (или рисунка):

loc='best', bbox_to_anchor=(0.5, 0., 0.5, 0.5)

Кортеж из 2 элементов (x, y) помещает угол легенды, заданный параметром loc, в точку x, y. Например, чтобы поместить верхний правый угол легенды в центр Axes (или рисунка), можно использовать следующие ключевые аргументы:

loc='upper right', bbox_to_anchor=(0.5, 0.5)

ncolsцелое число, по умолчанию: 1

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

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

propNone, FontProperties или словарь

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

fontsizeцелое число или {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}

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

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

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

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

reverseлогическое значение, по умолчанию: False

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

Добавлено в версии 3.7.

frameonлогическое значение, по умолчанию: rcParams["legend.frameon"] (значение по умолчанию: True)

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

fancyboxлогическое значение, по умолчанию: rcParams["legend.fancybox"] (значение по умолчанию: True)

Следует ли скруглить края объекта FancyBboxPatch, образующего фон легенды.

shadowNone, логическое значение или словарь, по умолчанию: rcParams["legend.shadow"] (значение по умолчанию: False)

Следует ли отбрасывать тень за легендой. Тень можно настроить с помощью ключевых аргументов Patch. Настройка через 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", легенда будет растянута по горизонтали, чтобы заполнить область Axes (или bbox_to_anchor, если он задаёт размер легенды).

bbox_transformNone или Transform

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

titleстрока или None

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

title_fontpropertiesNone, 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

handler_mapсловарь или None

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

draggableлогическое значение, по умолчанию: False

Можно ли перетаскивать легенду с помощью мыши.

codes={'best': 0, 'center': 10, 'center left': 6, 'center right': 7, 'lower center': 8, 'lower left': 3, 'lower right': 4, 'right': 5, 'upper center': 9, 'upper left': 2, 'upper right': 1}

contains(mouseevent)[источник]

Проверить, содержит ли объект Artist событие мыши.

Параметры:

mouseeventMouseEvent

Возвращает:

containsлогическое значение

Находится ли какое-либо значение в пределах радиуса.

detailsсловарь

Словарь сведений о контексте события, специфичный для объекта Artist, например о том, какие точки находятся в радиусе выбора. Подробности см. в описании соответствующих подклассов Artist.

draw(renderer)[источник]

Нарисовать объект Artist и его дочерние объекты с помощью указанного средства визуализации.

Метод ничего не делает, если объект Artist невидим (метод Artist.get_visible возвращает False).

Параметры:

rendererподкласс RendererBase.

Примечания

Этот метод переопределён в подклассах Artist.

draw_frame(b)[источник]

Задать, следует ли рисовать область рамки легенды.

Параметры:

bлогическое значение

get_alignment()[источник]

Получить значение выравнивания рамки легенды

get_bbox_to_anchor()[источник]

Вернуть bbox, к которому будет привязана легенда.

get_children()[источник]

Вернуть список дочерних объектов Artist этого объекта Artist.

classmethodget_default_handler_map()[источник]

Вернуть глобальную карту обработчиков по умолчанию, общую для всех легенд.

get_draggable()[источник]

Вернуть True, если легенду можно перетаскивать, и False в противном случае.

get_frame()[источник]

Вернуть объект Rectangle, используемый для создания рамки легенды.

get_frame_on()[источник]

Проверить, рисуется ли область рамки легенды.

staticget_legend_handler(legend_handler_map, orig_handle)[источник]

Вернуть обработчик легенды из legend_handler_map, соответствующий orig_handler.

legend_handler_map должен быть объектом словаря (возвращаемым методом get_legend_handler_map).

Сначала проверяется, является ли сам orig_handle ключом в legend_handler_map; если да, возвращается соответствующее значение. В противном случае проверяются все классы в порядке разрешения методов. Если подходящий ключ не найден, возвращается None.

get_legend_handler_map()[источник]

Вернуть карту обработчиков данного экземпляра легенды.

get_lines()[источник]

Вернуть список объектов Line2D в легенде.

get_patches()[источник]

Вернуть список объектов Patch в легенде.

get_texts()[источник]

Вернуть список объектов Text в легенде.

get_tightbbox(renderer=None)[источник]

Аналогично Artist.get_window_extent, но учитывает любое обрезание.

Параметры:

rendererподкласс RendererBase, необязательный

Средство визуализации, которое будет использоваться для рисования рисунков (то есть fig.canvas.get_renderer())

Возвращает:

Bbox или None

Охватывающая ограничивающая рамка (в пиксельных координатах рисунка). Возвращает None, если после обрезания пересечение отсутствует.

get_title()[источник]

Вернуть экземпляр Text для заголовка легенды.

get_window_extent(renderer=None)[источник]

Получить ограничивающую рамку объекта Artist в пространстве отображения.

Ширина и высота ограничивающей рамки неотрицательны.

Подклассы должны переопределять этот метод, чтобы включать объект в расчёт ограничивающей рамки «tight». По умолчанию возвращается пустая ограничивающая рамка в точке 0, 0.

Будьте осторожны при использовании этой функции: результаты не обновятся, если изменится область окна объекта Artist. Она может измениться из-за любых изменений в стеке преобразований, например при изменении пределов Axes, размера рисунка или используемого холста (как это происходит при сохранении рисунка). Это может привести к неожиданному поведению: интерактивный рисунок будет нормально выглядеть на экране, но сохранится некорректно.

set(*, agg_filter=<UNSET>, alignment=<UNSET>, alpha=<UNSET>, animated=<UNSET>, bbox_to_anchor=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, draggable=<UNSET>, frame_on=<UNSET>, gid=<UNSET>, in_layout=<UNSET>, label=<UNSET>, loc=<UNSET>, mouseover=<UNSET>, ncols=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, rasterized=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, title=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, zorder=<UNSET>)[исходный код]

Задать несколько свойств одновременно.

Поддерживаются следующие свойства:

Свойство	Описание
agg_filter	функция фильтра, которая принимает массив float размера (m, n, 3) и значение dpi, а возвращает массив размера (m, n, 3) и два смещения от левого нижнего угла изображения
alignment	{'center', 'left', 'right'}.
alpha	float или None
animated	bool
bbox_to_anchor	BboxBase или tuple
clip_box	BboxBase или None
clip_on	bool
clip_path	Patch или (Path, Transform) или None
draggable	bool
figure	Figure или SubFigure
frame_on	bool
gid	str
in_layout	bool
label	object
loc	str или пара чисел с плавающей запятой, по умолчанию: rcParams["legend.loc"] (по умолчанию: 'best') для Axes, 'upper right' для Figure
mouseover	bool
ncols	неизвестно
path_effects	список объектов AbstractPathEffect
picker	None, bool, float или вызываемый объект
rasterized	bool
sketch_params	(scale: float, length: float, randomness: float)
snap	bool или None
title	str
transform	Transform
url	str
visible	bool
zorder	float

set_alignment(alignment)[исходный код]

Задать выравнивание заголовка легенды и блока элементов.

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

Параметры:

alignment{'center', 'left', 'right'}.

set_bbox_to_anchor(bbox, transform=None)[исходный код]

Задать ограничивающую рамку, к которой будет привязана легенда.

Параметры:

bboxBboxBase или tuple

Ограничивающую рамку можно задать следующими способами:

• Экземпляр BboxBase
• Кортеж из (left, bottom, width, height) в заданном преобразовании (нормированные координаты осей, если значение равно None)
• Кортеж из (left, bottom), при этом ширина и высота будут считаться равными нулю.
• None, чтобы убрать привязку к ограничивающей рамке и использовать рамку родительского объекта.

transformTransform, необязательно

Преобразование, применяемое к ограничивающей рамке. Если не задано, используется преобразование ограничивающей рамки родительского объекта.

classmethodset_default_handler_map(handler_map)[исходный код]

Задать глобальную карту обработчиков по умолчанию, общую для всех легенд.

set_draggable(state, use_blit=False, update='loc')[исходный код]

Включить или отключить возможность перетаскивания легенды мышью.

Параметры:

statebool

Определяет, включено ли перетаскивание мышью.

use_blitbool, необязательно

Использовать blitting для более быстрой композиции изображения. Подробнее см. в разделе FuncAnimation.

update{'loc', 'bbox'}, необязательно

Параметр легенды, который будет изменяться при перетаскивании:

• 'loc': обновить параметр loc легенды
• 'bbox': обновить параметр bbox_to_anchor легенды

Возвращает:

DraggableLegend или None

Если state имеет значение True, возвращается вспомогательный экземпляр DraggableLegend. В противном случае возвращается None.

set_frame_on(b)[исходный код]

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

Параметры:

bbool

set_loc(loc=None)[исходный код]

Задать расположение легенды.

Добавлено в версии 3.8.

Параметры:

locstr или пара чисел с плавающей запятой, по умолчанию: rcParams["legend.loc"] (по умолчанию: 'best') для Axes, 'upper right' для Figure

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

Строки 'upper left', 'upper right', 'lower left', 'lower right' помещают легенду в соответствующий угол Axes/Figure.

Строки 'upper center', 'lower center', 'center left', 'center right' помещают легенду в центр соответствующего края Axes/Figure.

Строка 'center' помещает легенду в центр Axes/Figure.

Строка 'best' помещает легенду в одно из девяти указанных мест, где она будет меньше всего перекрывать другие нарисованные объекты. Этот вариант может работать довольно медленно для графиков с большим объемом данных; построение графика может быть быстрее, если задать конкретное расположение.

Расположение также можно задать кортежем из двух значений, определяющих координаты левого нижнего угла легенды в координатах Axes/Figure (в этом случае bbox_to_anchor будет игнорироваться).

Для обеспечения обратной совместимости 'center right' (но не другие варианты расположения) также можно записать как 'right', а каждое строковое значение расположения можно также задать числом:

Строковое значение расположения	Код расположения
'best' (только для Axes)	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

Если для Figure используется менеджер ограниченного макета, строковые значения аргумента loc могут обеспечить более удачное расположение, если добавить префикс 'outside'. В углах возникает неоднозначность: 'outside upper right' оставляет место для легенды над остальными осями в макете, а 'outside right upper' — справа от макета. Помимо перечисленных выше значений loc, можно использовать 'outside right upper', 'outside right lower', 'outside left upper' и 'outside left lower'. Подробнее см. в руководстве по легендам.

set_ncols(ncols)[исходный код]

Задать количество столбцов.

set_title(title, prop=None)[исходный код]

Задать заголовок легенды и его стиль.

Параметры:

titlestr

Заголовок легенды.

propfont_manager.FontProperties или str или pathlib.Path

Свойства шрифта заголовка легенды. Если задан объект str, он интерпретируется как шаблон fontconfig, разбираемый с помощью FontProperties. Если задан объект pathlib.Path, он интерпретируется как абсолютный путь к файлу шрифта.

classmethodupdate_default_handler_map(handler_map)[исходный код]

Обновить глобальную карту обработчиков по умолчанию, общую для всех легенд.

zorder=5