matplotlib.legend

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

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

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

Дополнительную информацию см. в :ref`<legend_guide>`.

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

Bases: DraggableOffsetBox

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

Parameters:

legendLegend

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

use_blitbool, optional

Использовать blitting для ускорения композиции изображения. Подробнее см. 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, reverse=False, scatterpoints=None, scatteryoffsets=None, prop=None, fontsize=None, labelcolor=None, ...)[source]

Bases: Artist

Размещение легенды на фигуре/осях.

Parameters:

parentAxes или Figure

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

handlesсписок (Artist или кортеж из Artist)

Список графических объектов (линии, области) для добавления в легенду.

labelsсписок str

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

Attributes:

legend_handles

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

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

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

Расположение (строка)	Код расположения
'best' (только для осей)	0
'верхний правый'	1
'верхний левый'	2
'нижний левый'	3
'нижний правый'	4
'правый'	5
'центр слева'	6
'центр справа'	7
'нижний центр'	8
'верхний центр'	9
'центр'	10

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

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)

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'), или список строк цвета. Цвет метки также можно сделать совпадающим с цветом линии или маркера, используя 'linecolor', 'markerfacecolor' (или 'mfc'), или 'markeredgecolor' (или 'mec').

Цвет метки можно установить глобально, используя 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)

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

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

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

reversebool, по умолчанию: False

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

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

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

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

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

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

shadowNone, bool или словарь, по умолчанию: 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", легенда будет горизонтально расширена, чтобы заполнить область осей (или bbox_to_anchor, если он определяет размер легенды).

bbox_transformNone или Transform

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

titleстрока или None

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

title_fontpropertiesNone или 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, по умолчанию: rcParams["legend.handleheight"] (по умолчанию: 0.7)

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

handletextpadfloat, по умолчанию: rcParams["legend.handletextpad"] (по умолчанию: 0.8)

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

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

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

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

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

handler_mapdict или None

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

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

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

Parameters:

mouseeventMouseEvent

Returns:

containsbool

Является ли любая точка в радиусе.

detailsdict

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

draw(renderer)[source]

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

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

Parameters:

rendererRendererBase подкласс.

Примечания

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

draw_frame(b)[source]

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

get_alignment()[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 подкласс, необязательно

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

Возвращает:

Bbox или None

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

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

Устанавливает сразу несколько свойств.

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

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

set_alignment(alignment)[source]

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

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

Параметры:

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, необязательно

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

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

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

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

Возвращает:

DraggableLegend или None

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

set_frame_on(b)[source]

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

Параметры:

bbool

set_loc(loc=None)[source]

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

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

Параметры:

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

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

Строки '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

Если фигура использует менеджер ограничений макета, строковые коды аргумента loc могут обеспечить лучшую компоновку с использованием префикса 'outside'. Возникает неоднозначность в углах, поэтому 'outside верхний правый' создаст пространство для легенды над остальными осями в макете, а 'outside правый верхний' — пространство справа от макета. В дополнение к значениям loc, перечисленным выше, у нас есть 'outside правый верхний', 'outside правый нижний', 'outside левый верхний' и 'outside левый нижний'. См. Руководство по легендам для получения дополнительной информации.

set_ncols(ncols)[source]

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

set_title(title, prop=None)[source]

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

Параметры:

titleстрока

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

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

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

classmethodupdate_default_handler_map(handler_map)[source]

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

zorder=5