matplotlib.legend

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

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

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

Дополнительную информацию см. в руководстве по легендам.

classmatplotlib.legend.DraggableLegend(legend, use_blit=False, update='loc')[source]

Bases: DraggableOffsetBox

Обёртка над Legend для поддержки перетаскивания мышью.

Параметры:

legendLegend

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

use_blitbool, optional

Использовать кеширование для более быстрого отображения. Дополнительные сведения см. в FuncAnimation.

update{'loc', 'bbox'}, optional

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

finalize_offset()[source]

classmatplotlib.legend.Legend(parent, handles, labels, *, loc=None, numpoints=None, markerscale=None, markerfirst=True, 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)[source]

Bases: Artist

Размещает легенду на осях в указанном месте.

Параметры:

parentAxes или Figure

Элемент, содержащий легенду.

handlesсписок Artist

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

labelsсписок str

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

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

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].

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

Определяет, должна ли быть нарисована тень за легендой.

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

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

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

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

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

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

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

Примечания

Пользователи могут указать произвольную позицию легенды с помощью ключевого аргумента bbox_to_anchor. bbox_to_anchor может быть BboxBase (или производной от него) или кортежем из 2 или 4 чисел с плавающей точкой. Более подробная информация приведена в set_bbox_to_anchor.

Расположение легенды можно указать, задав loc с кортежем из 2 чисел с плавающей точкой, которое интерпретируется как левый нижний угол легенды в нормализованных координатах оси.

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(event)[source]

Проверка, содержит ли элемент графический объект событие мыши.

Параметры:

mouseeventmatplotlib.backend_bases.MouseEvent

Возвращает:

containsbool

Является ли значение внутри радиуса.

detailsdict

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

draw(renderer)[source]

Отрисовка элемента (и его дочерних элементов) с помощью заданного рендерера.

Если элемент не видим (Artist.get_visible возвращает False), это не имеет эффекта.

Параметры:

rendererRendererBase подкласс.

Примечания

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

draw_frame(b)[source]

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

Параметры:

bbool

get_alignment()[source]

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

get_bbox_to_anchor()[source]

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

get_children()[source]

Возвращает список дочерних элементов Artist этого Artist.

classmethodget_default_handler_map()[source]

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

get_draggable()[source]

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

get_frame()[source]

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

get_frame_on()[source]

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

staticget_legend_handler(legend_handler_map, orig_handle)[source]

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

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

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

get_legend_handler_map()[source]

Возвращает словарь обработчиков для этой легенды.

get_lines()[source]

Возвращает список Line2D в легенде.

get_patches()[source]

Возвращает список Patch в легенде.

get_texts()[source]

Возвращает список Text в легенде.

get_tightbbox(renderer=None)[source]

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

Параметры:

rendererRendererBase подкласс

renderer, который будет использоваться для отрисовки графиков (т.е. fig.canvas.get_renderer())

Возвращает:

Bbox

Охватывающая область (в пикселях координат фигуры).

get_title()[source]

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

get_window_extent(renderer=None)[source]

Получает область объекта-графического элемента в пространстве отображения.

Ширина и высота области имеют неотрицательные значения.

Подклассы должны переопределять для включения в вычисление "плотной" области. По умолчанию возвращается пустая область в 0, 0.

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

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>, 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>)[source]

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

Поддерживаемые свойства:

Свойство	Описание
agg_filter	функция фильтра, которая принимает массив float (m, n, 3) и значение dpi, и возвращает массив (m, n, 3) и два смещения от нижнего левого угла изображения
alignment	{'center', 'left', 'right'}.
alpha	скаляр или None
animated	bool
bbox_to_anchor	BboxBase или кортеж
clip_box	Bbox
clip_on	bool
clip_path	Фигура или (путь, преобразование) или None
draggable	bool
figure	Figure
frame_on	bool
gid	str
in_layout	bool
label	объект
mouseover	bool
ncols	неизвестно
path_effects	AbstractPathEffect
picker	None или bool или float или вызываемый объект
rasterized	bool
sketch_params	(масштаб: float, длина: float, случайность: float)
snap	bool или None
title	str
transform	Transform
url	str
visible	bool
zorder	float

set_alignment(alignment)[source]

Устанавливает выравнивание заголовка легенды и блока записей.

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

Parameters:

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

set_bbox_to_anchor(bbox, transform=None)[source]

Установить область, к которой будет привязана легенда.

Параметры:

bboxBboxBase или кортеж

Прямоугольник может быть задан следующими способами:

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

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

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

classmethodset_default_handler_map(handler_map)[source]

Установить глобальную карту обработчиков, используемую всеми легендами.

set_draggable(state, use_blit=False, update='loc')[source]

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

Параметры:

statebool

Включить или отключить перетаскивание мышкой.

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

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

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

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

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

Возвращает:

DraggableLegend или None

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

set_frame_on(b)[source]

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

Параметры:

bbool

set_ncols(ncols)[source]

Установить количество столбцов.

set_title(title, prop=None)[source]

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

Параметры:

titlestr

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

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

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

classmethodupdate_default_handler_map(handler_map)[source]

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

zorder=5