matplotlib.pyplot.figlegend

matplotlib.pyplot.figlegend(*args, **kwargs)[исходный код]

Размещает легенду на рисунке.

Сигнатуры вызова:

figlegend()
figlegend(handles, labels)
figlegend(handles=handles)
figlegend(labels)

Сигнатуры вызова соответствуют следующим способам использования этого метода:

1. Автоматическое определение элементов, отображаемых в легенде

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

В этом случае подписи берутся из графических объектов. Их можно задать при создании графического объекта или вызвав метод set_label() для графического объекта:

plt.plot([1, 2, 3], label='Inline label')
plt.figlegend()

или:

line, = plt.plot([1, 2, 3])
line.set_label('Label via method')
plt.figlegend()

Отдельные линии можно исключить из автоматического выбора элементов легенды, задав подпись, начинающуюся с символа подчёркивания. Это значение используется по умолчанию для всех графических объектов, поэтому вызов Figure.legend без аргументов и без ручной установки подписей приведёт к тому, что легенда не будет отображена.

2. Явное перечисление графических объектов и подписей в легенде

Чтобы полностью контролировать, для каких графических объектов будет создана запись в легенде, можно передать итерируемый объект с графическими объектами легенды, а затем итерируемый объект с подписями легенды:

plt.figlegend([line1, line2, line3], ['label1', 'label2', 'label3'])

3. Явное перечисление графических объектов в легенде

Этот способ похож на способ 2, но подписи берутся из свойств подписей графических объектов. Пример:

line1, = ax1.plot([1, 2, 3], label='label1')
line2, = ax2.plot([1, 2, 3], label='label2')
plt.figlegend(handles=[line1, line2])

4. Присвоение подписей существующим элементам графика

Не рекомендуется

Эта сигнатура вызова не рекомендуется, поскольку соответствие элементов графика и подписей задаётся только неявно — их порядком, который легко перепутать.

Чтобы создать легенду для всех графических объектов на всех областях Axes, вызовите эту функцию, передав итерируемый объект строк — по одной для каждого элемента легенды. Например:

fig, (ax1, ax2) = plt.subplots(1, 2)
ax1.plot([1, 3, 5], color='blue')
ax2.plot([2, 4, 6], color='red')
plt.figlegend(['the blues', 'the reds'])

Параметры:

handleslist of Artist, optional

Список объектов Artist (линий, фигур), которые нужно добавить в легенду. Используйте его вместе с labels, если требуется полностью контролировать отображение легенды и описанного выше автоматического механизма недостаточно.

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

labelslist of str, optional

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

Возвращает:

Legend

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

locstr or pair of floats, default: 'upper right'

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

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

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

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

В качестве расположения также можно передать кортеж из двух элементов с координатами нижнего левого угла легенды в координатах рисунка (в этом случае 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' резервирует место для легенды над остальными областями Axes в компоновке, а 'outside right upper' — справа от компоновки. Помимо перечисленных выше значений loc, доступны 'outside right upper', 'outside right lower', 'outside left upper' и 'outside left lower'. Подробнее см. в руководстве по легенде.

bbox_to_anchorBboxBase, 2-tuple, or 4-tuple of floats

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

Координаты Bbox интерпретируются в системе координат, задаваемой параметром bbox_transform. По умолчанию используются координаты Axes или рисунка — в зависимости от того, какой 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)

ncolsint, default: 1

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

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

propNone or FontProperties or dict

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

fontsizeint or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}

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

labelcolorstr or list, default: rcParams["legend.labelcolor"] (default: 'None')

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

Цвет подписей можно задать глобально с помощью rcParams["legend.labelcolor"] (по умолчанию: 'None'). Если значение равно None, используется rcParams["text.color"] (по умолчанию: 'black').

numpointsint, default: rcParams["legend.numpoints"] (default: 1)

Количество точек-маркеров в записи легенды для Line2D (линии).

scatterpointsint, default: rcParams["legend.scatterpoints"] (default: 1)

Количество точек-маркеров в записи легенды для PathCollection (диаграммы рассеяния).

scatteryoffsetsiterable of floats, default: [0.375, 0.5, 0.3125]

Вертикальное смещение (относительно размера шрифта) маркеров, создаваемых для записи легенды диаграммы рассеяния. Значение 0.0 соответствует основанию текста легенды, а 1.0 — его верхнему краю. Чтобы расположить все маркеры на одной высоте, задайте [0.5].

markerscalefloat, default: rcParams["legend.markerscale"] (default: 1.0)

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

markerfirstbool, default: True

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

reversebool, default: False

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

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

frameonbool, default: rcParams["legend.frameon"] (default: True)

Следует ли отображать легенду на плашке (рамке).

fancyboxbool, default: rcParams["legend.fancybox"] (default: True)

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

shadowNone, bool or dict, default: rcParams["legend.shadow"] (default: False)

Следует ли отрисовывать тень за легендой. Тень можно настроить с помощью ключевых слов Patch. Настройка с помощью rcParams["legend.shadow"] (по умолчанию: False) в настоящее время не поддерживается.

framealphafloat, default: rcParams["legend.framealpha"] (default: 0.8)

Прозрачность фона легенды. Если включена shadow, а значение framealpha равно None, значение по умолчанию игнорируется.

facecolor"inherit" or color, default: rcParams["legend.facecolor"] (default: 'inherit')

Цвет фона легенды. Если задано "inherit", используется rcParams["axes.facecolor"] (по умолчанию: 'white').

edgecolor"inherit" or color, default: rcParams["legend.edgecolor"] (default: '0.8')

Цвет края фоновой плашки легенды. Если задано "inherit", используется rcParams["axes.edgecolor"] (по умолчанию: 'black').

mode{"expand", None}

Если для mode задано значение "expand", легенда будет растянута по горизонтали, чтобы заполнить область Axes (или bbox_to_anchor, если он задаёт размер легенды).

bbox_transformNone or Transform

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

titlestr or None

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

title_fontpropertiesNone or FontProperties or dict

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

Расстояние между областью Axes и рамкой легенды, выраженное в долях размера шрифта.

columnspacingfloat, default: rcParams["legend.columnspacing"] (default: 2.0)

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

handler_mapdict or None

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

draggablebool, default: False

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

См. также

Axes.legend

Примечания

Эта функция поддерживает не все графические объекты. Подробности см. в руководстве по легенде.