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

Использовать блиттинг для более быстрого рендеринга. Подробнее см. 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, 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)[source]

Bases: Artist

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

Parameters:

parentAxes или Figure

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

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

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

labelsсписок str

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

Other Parameters:

locstr или пара чисел с плавающей точкой, по умолчанию: 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 слева внизу'. Для получения более подробной информации см. Руководство по легендам.

bbox_to_anchorBboxBase, пара чисел или 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)

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

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

bbox_transformNone или Transform

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

titleстрока или None

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

title_fontpropertiesNone или FontProperties или словарь

Свойства шрифта заголовка легенды. Если 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

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

Атрибуты:

legend_handles

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

Введено в версии 3.7.

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]

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

Параметры:

mouseeventMouseEvent

Возвращает:

containsbool

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

detailsdict

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

draw(renderer)[source]

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

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

Параметры:

rendererRendererBase подкласс.

Примечания

Этот метод переопределен в подклассах объекта художника.

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

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

Возвращает:

Bbox или None

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

get_title()[source]

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

get_window_extent(renderer=None)[source]

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

Ширина и высота области отображения неотрицательны.

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

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

propertylegendHandles[source]

[Устарело]

Примечания

Устарело начиная с версии 3.7: Используйте вместо этого legend_handles.

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	str
in_layout	bool
label	object
loc	str или пара чисел с плавающей запятой, по умолчанию: rcParams["legend.loc"] (по умолчанию: 'best') для Axes, 'upper right' для Figure
mouseover	bool
ncols	unknown
path_effects	список AbstractPathEffect
picker	None или bool или float или callable
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)[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, необязательно

Использовать ускорение blitting для более быстрого рендеринга. Подробности см. в 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') для Oси, 'верхний правый' для Рисунка

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

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

Расположение (строка)	Код расположения
'лучшее' (только для оси)	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. Если путь pathlib.Path, она интерпретируется как абсолютный путь к файлу шрифта.

classmethodupdate_default_handler_map(handler_map)[source]

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

zorder=5