matplotlib.legend

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

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

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

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

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 or Figure

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

handleslist of Artist

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

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

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

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

markerfirstбулево значение, по умолчанию: True

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

reverseбулево значение, по умолчанию: False

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

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

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

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

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

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

shadowбулево значение, по умолчанию: 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 or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}, default: rcParams["legend.title_fontsize"] (default: None)

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

alignment{'center', 'left', 'right'}, default: 'center'

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

borderpadfloat, default: rcParams["legend.borderpad"] (default: 0.4)

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

labelspacingfloat, default: rcParams["legend.labelspacing"] (default: 0.5)

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

handlelengthfloat, default: rcParams["legend.handlelength"] (default: 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.

draggablebool, default: 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(event)[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

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

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>, 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	{'центр', 'слева', 'справа'}.
alpha	скаляр или None
animated	логическое значение
bbox_to_anchor	BboxBase или кортеж
clip_box	Bbox
clip_on	логическое значение
clip_path	Объект Patch или (Path, Transform) или None
draggable	логическое значение
figure	Figure
frame_on	логическое значение
gid	строка
in_layout	логическое значение
label	объект
mouseover	логическое значение
ncols	неизвестно
path_effects	AbstractPathEffect
picker	None или логическое значение или число с плавающей точкой или вызываемая функция
rasterized	логическое значение
sketch_params	(масштаб: число с плавающей точкой, длина: число с плавающей точкой, случайность: число с плавающей точкой)
snap	логическое значение или None
title	строка
transform	Transform
url	строка
visible	логическое значение
zorder	число с плавающей точкой

set_alignment(alignment)[source]

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

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

Параметры:

alignment{'центр', 'слева', 'справа'}.

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

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

classmethodupdate_default_handler_map(handler_map)[source]

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

zorder=5