matplotlib

Объектно-ориентированная библиотека для построения графиков.

Процедурный интерфейс предоставляется сопутствующим модулем pyplot, который можно импортировать напрямую, например:

import matplotlib.pyplot as plt

или с помощью ipython:

ipython

в терминале, а затем ввести:

In [1]: %matplotlib
In [2]: import matplotlib.pyplot as plt

в командной строке ipython.

В большинстве случаев при программировании рекомендуется напрямую использовать явную объектно-ориентированную библиотеку; неявный интерфейс pyplot предназначен в первую очередь для интерактивной работы. Исключением из этой рекомендации являются функции pyplot pyplot.figure, pyplot.subplot, pyplot.subplots и pyplot.savefig, которые могут значительно упростить написание скриптов. Объяснение компромиссов между неявным и явным интерфейсами см. в разделе Интерфейсы приложения Matplotlib (API).

В состав входят модули:

matplotlib.axes: Класс Axes. Большинство функций pyplot являются обёртками для методов Axes. Модуль axes предоставляет наиболее высокий уровень объектно-ориентированного доступа к библиотеке.
matplotlib.figure: Класс Figure.
matplotlib.artist: Базовый класс Artist для всех классов, отвечающих за отрисовку объектов.
matplotlib.lines: Класс Line2D для рисования линий и маркеров.
matplotlib.patches: Классы для рисования многоугольников.
matplotlib.text: Классы Text и Annotation.
matplotlib.image: Классы AxesImage и FigureImage.
matplotlib.collections: Классы для эффективной отрисовки групп линий или многоугольников.
matplotlib.colors: Задание цветов и создание цветовых карт.
matplotlib.cm: Цветовые карты и класс-миксин ScalarMappable, предоставляющий другим классам функциональность отображения значений в цвета.
matplotlib.ticker: Вычисление расположения делений и форматирование их подписей.
matplotlib.backends: Подпакет с модулями для различных библиотек графического интерфейса и форматов вывода.

Базовое пространство имён matplotlib включает:

rcParams: Настройки конфигурации по умолчанию; их значения можно переопределить с помощью файла matplotlibrc.
use: Выбор бэкенда Matplotlib. Эту функцию следует вызвать до создания любых рисунков, поскольку после этого переключаться между различными бэкендами графического интерфейса невозможно.

Для настройки поведения можно использовать следующие переменные окружения:

MPLBACKEND: Эту необязательную переменную можно задать, чтобы выбрать бэкенд Matplotlib. См. раздел Что такое бэкенд?.
MPLCONFIGDIR: Этот каталог используется для хранения пользовательских настроек Matplotlib, а также некоторых кэшей для повышения производительности. Если переменная MPLCONFIGDIR не задана, в Linux используются HOME/.config/matplotlib и HOME/.cache/matplotlib, а на других платформах — HOME/.matplotlib, если эти каталоги доступны для записи. В противном случае стандартная библиотека Python использует tempfile.gettempdir, чтобы найти базовый каталог, в котором создаётся подкаталог matplotlib.

Первоначально Matplotlib была написана Джоном Д. Хантером (1968–2012); сейчас её разрабатывает и поддерживает большая команда специалистов.

Иногда во внутренней документации (строках документации Python) упоминается MATLAB®, зарегистрированный товарный знак The MathWorks, Inc.

Управление бэкендами

matplotlib.use(backend, *, force=True)[исходный код]

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

Если модуль pyplot уже импортирован, используется switch_backend; если новый бэкенд отличается от текущего, все рисунки будут закрыты.

Параметры:

backendstr

Бэкенд, на который нужно переключиться. Это может быть одно из стандартных имён бэкендов, регистр букв в которых не учитывается:

интерактивные бэкенды: GTK3Agg, GTK3Cairo, GTK4Agg, GTK4Cairo, MacOSX, nbAgg, notebook, QtAgg, QtCairo, TkAgg, TkCairo, WebAgg, WX, WXAgg, WXCairo, Qt5Agg, Qt5Cairo
неинтерактивные бэкенды: agg, cairo, pdf, pgf, ps, svg, template

или строка вида: module://my.module.name.

notebook — это синоним nbAgg.

Переключиться на интерактивный бэкенд нельзя, если уже запущен посторонний цикл обработки событий (например, переключиться на GTK3Agg нельзя, если уже открыто окно TkAgg). Переключение на неинтерактивный бэкенд возможно всегда.

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

Если значение True (по умолчанию), вызвать исключение ImportError, если не удаётся настроить бэкенд (из-за ошибки импорта или уже работающей несовместимой интерактивной среды графического интерфейса); если значение False, ошибку не учитывать.

См. также

Бэкенды
matplotlib.get_backend
matplotlib.pyplot.switch_backend

matplotlib.get_backend(*, auto_select=True)[исходный код]

Вернуть имя текущего бэкенда.

Параметры:

auto_selectbool, по умолчанию: True: Следует ли запускать определение бэкенда, если он ещё не выбран. Если значение True, гарантируется возврат допустимого бэкенда. Если значение False, функция вернёт None, если бэкенд ещё не выбран.

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

Предварительная версия

Флаг auto_select является предварительным и может быть изменён или удалён без предварительного уведомления.

См. также

matplotlib.use

matplotlib.interactive(b)[исходный код]: Задать, следует ли перерисовывать график после каждой команды построения (например, pyplot.xlabel).

matplotlib.is_interactive()[исходный код]: Вернуть, следует ли перерисовывать график после каждой команды построения.

Примечание

Эта функция предназначена только для использования в бэкендах. Конечным пользователям следует вместо неё использовать pyplot.isinteractive.

Значения по умолчанию и стилизация

matplotlib.rcParams[исходный код]: Экземпляр RcParams для управления значениями Matplotlib по умолчанию.

classmatplotlib.RcParams(*args, **kwargs)[исходный код]

Хранилище параметров конфигурации в формате «ключ-значение», подобное словарю и включающее проверку значений.

Функции проверки определены и связаны с параметрами rc в matplotlib.rcsetup.

Список rcParams:

_internal.classic_mode
agg.path.chunksize
animation.bitrate
animation.codec
animation.convert_args
animation.convert_path
animation.embed_limit
animation.ffmpeg_args
animation.ffmpeg_path
animation.frame_format
animation.html
animation.writer
axes.autolimit_mode
axes.axisbelow
axes.edgecolor
axes.facecolor
axes.formatter.limits
axes.formatter.min_exponent
axes.formatter.offset_threshold
axes.formatter.use_locale
axes.formatter.use_mathtext
axes.formatter.useoffset
axes.grid
axes.grid.axis
axes.grid.which
axes.labelcolor
axes.labelpad
axes.labelsize
axes.labelweight
axes.linewidth
axes.prop_cycle
axes.spines.bottom
axes.spines.left
axes.spines.right
axes.spines.top
axes.titlecolor
axes.titlelocation
axes.titlepad
axes.titlesize
axes.titleweight
axes.titley
axes.unicode_minus
axes.xmargin
axes.ymargin
axes.zmargin
axes3d.automargin
axes3d.grid
axes3d.mouserotationstyle
axes3d.trackballborder
axes3d.trackballsize
axes3d.xaxis.panecolor
axes3d.yaxis.panecolor
axes3d.zaxis.panecolor
backend
backend_fallback
boxplot.bootstrap
boxplot.boxprops.color
boxplot.boxprops.linestyle
boxplot.boxprops.linewidth
boxplot.capprops.color
boxplot.capprops.linestyle
boxplot.capprops.linewidth
boxplot.flierprops.color
boxplot.flierprops.linestyle
boxplot.flierprops.linewidth
boxplot.flierprops.marker
boxplot.flierprops.markeredgecolor
boxplot.flierprops.markeredgewidth
boxplot.flierprops.markerfacecolor
boxplot.flierprops.markersize
boxplot.meanline
boxplot.meanprops.color
boxplot.meanprops.linestyle
boxplot.meanprops.linewidth
boxplot.meanprops.marker
boxplot.meanprops.markeredgecolor
boxplot.meanprops.markerfacecolor
boxplot.meanprops.markersize
boxplot.medianprops.color
boxplot.medianprops.linestyle
boxplot.medianprops.linewidth
boxplot.notch
boxplot.patchartist
boxplot.showbox
boxplot.showcaps
boxplot.showfliers
boxplot.showmeans
boxplot.vertical
boxplot.whiskerprops.color
boxplot.whiskerprops.linestyle
boxplot.whiskerprops.linewidth
boxplot.whiskers
contour.algorithm
contour.corner_mask
contour.linewidth
contour.negative_linestyle
date.autoformatter.day
date.autoformatter.hour
date.autoformatter.microsecond
date.autoformatter.minute
date.autoformatter.month
date.autoformatter.second
date.autoformatter.year
date.converter
date.epoch
date.interval_multiples
docstring.hardcopy
errorbar.capsize
figure.autolayout
figure.constrained_layout.h_pad
figure.constrained_layout.hspace
figure.constrained_layout.use
figure.constrained_layout.w_pad
figure.constrained_layout.wspace
figure.dpi
figure.edgecolor
figure.facecolor
figure.figsize
figure.frameon
figure.hooks
figure.labelsize
figure.labelweight
figure.max_open_warning
figure.raise_window
figure.subplot.bottom
figure.subplot.hspace
figure.subplot.left
figure.subplot.right
figure.subplot.top
figure.subplot.wspace
figure.titlesize
figure.titleweight
font.cursive
font.family
font.fantasy
font.monospace
font.sans-serif
font.serif
font.size
font.stretch
font.style
font.variant
font.weight
grid.alpha
grid.color
grid.linestyle
grid.linewidth
hatch.color
hatch.linewidth
hist.bins
image.aspect
image.cmap
image.composite_image
image.interpolation
image.interpolation_stage
image.lut
image.origin
image.resample
interactive
keymap.back
keymap.copy
keymap.forward
keymap.fullscreen
keymap.grid
keymap.grid_minor
keymap.help
keymap.home
keymap.pan
keymap.quit
keymap.quit_all
keymap.save
keymap.xscale
keymap.yscale
keymap.zoom
legend.borderaxespad
legend.borderpad
legend.columnspacing
legend.edgecolor
legend.facecolor
legend.fancybox
legend.fontsize
legend.framealpha
legend.frameon
legend.handleheight
legend.handlelength
legend.handletextpad
legend.labelcolor
legend.labelspacing
legend.loc
legend.markerscale
legend.numpoints
legend.scatterpoints
legend.shadow
legend.title_fontsize
lines.antialiased
lines.color
lines.dash_capstyle
lines.dash_joinstyle
lines.dashdot_pattern
lines.dashed_pattern
lines.dotted_pattern
lines.linestyle
lines.linewidth
lines.marker
lines.markeredgecolor
lines.markeredgewidth
lines.markerfacecolor
lines.markersize
lines.scale_dashes
lines.solid_capstyle
lines.solid_joinstyle
macosx.window_mode
markers.fillstyle
mathtext.bf
mathtext.bfit
mathtext.cal
mathtext.default
mathtext.fallback
mathtext.fontset
mathtext.it
mathtext.rm
mathtext.sf
mathtext.tt
patch.antialiased
patch.edgecolor
patch.facecolor
patch.force_edgecolor
patch.linewidth
path.effects
path.simplify
path.simplify_threshold
path.sketch
path.snap
pcolor.shading
pcolormesh.snap
pdf.compression
pdf.fonttype
pdf.inheritcolor
pdf.use14corefonts
pgf.preamble
pgf.rcfonts
pgf.texsystem
polaraxes.grid
ps.distiller.res
ps.fonttype
ps.papersize
ps.useafm
ps.usedistiller
savefig.bbox
savefig.directory
savefig.dpi
savefig.edgecolor
savefig.facecolor
savefig.format
savefig.orientation
savefig.pad_inches
savefig.transparent
scatter.edgecolors
scatter.marker
svg.fonttype
svg.hashsalt
svg.id
svg.image_inline
text.antialiased
text.color
text.hinting
text.hinting_factor
text.kerning_factor
text.latex.preamble
text.parse_math
text.usetex
timezone
tk.window_focus
toolbar
webagg.address
webagg.open_in_browser
webagg.port
webagg.port_retries
xaxis.labellocation
xtick.alignment
xtick.bottom
xtick.color
xtick.direction
xtick.labelbottom
xtick.labelcolor
xtick.labelsize
xtick.labeltop
xtick.major.bottom
xtick.major.pad
xtick.major.size
xtick.major.top
xtick.major.width
xtick.minor.bottom
xtick.minor.ndivs
xtick.minor.pad
xtick.minor.size
xtick.minor.top
xtick.minor.visible
xtick.minor.width
xtick.top
yaxis.labellocation
ytick.alignment
ytick.color
ytick.direction
ytick.labelcolor
ytick.labelleft
ytick.labelright
ytick.labelsize
ytick.left
ytick.major.left
ytick.major.pad
ytick.major.right
ytick.major.size
ytick.major.width
ytick.minor.left
ytick.minor.ndivs
ytick.minor.pad
ytick.minor.right
ytick.minor.size
ytick.minor.visible
ytick.minor.width
ytick.right

См. также

Файл matplotlibrc

find_all(pattern)[исходный код]: Возвращает подмножество этого словаря RcParams, ключи которого соответствуют заданному pattern, используя re.search().

Примечание

Изменения возвращённого словаря не передаются родительскому словарю RcParams.

copy()[исходный код]: Создаёт копию этого экземпляра RcParams.

matplotlib.rc_context(rc=None, fname=None)[исходный код]

Возвращает менеджер контекста для временного изменения rcParams.

Менеджер контекста не сбрасывает rcParams["backend"].

Изменения rcParams, внесённые как при вызове менеджера контекста, так и в теле контекста, будут отменены при выходе из контекста.

Параметры:

rcdict: Параметры rcParams, которые нужно временно задать.
fnameстрока или объект, подобный пути: Файл с настройками rc для Matplotlib. Если указаны и fname, и rc, настройки из rc имеют приоритет.

См. также

Файл matplotlibrc

Примеры

Передача явных значений через словарь:

with mpl.rc_context({'interactive': False}):
    fig, ax = plt.subplots()
    ax.plot(range(3), range(3))
    fig.savefig('example.png')
    plt.close(fig)

Загрузка настроек из файла:

with mpl.rc_context(fname='print.rc'):
    plt.plot(x, y)  # uses 'print.rc'

Задание настроек в теле контекста:

with mpl.rc_context():
    # will be reset
    mpl.rcParams['lines.linewidth'] = 5
    plt.plot(x, y)

matplotlib.rc(group, **kwargs)[исходный код]

Задаёт текущие rcParams. group — это группа параметров rc; например, для lines.linewidth группа — lines, для axes.facecolor группа — axes и так далее. В качестве группы также можно указать список или кортеж имён групп, например (xtick, ytick). kwargs — это словарь пар «имя атрибута/значение», например:

rc('lines', linewidth=2, color='r')

задаёт текущие rcParams и эквивалентно следующему:

rcParams['lines.linewidth'] = 2
rcParams['lines.color'] = 'r'

Для сокращения ввода интерактивными пользователями доступны следующие псевдонимы:

Псевдоним	Свойство
'lw'	'linewidth'
'ls'	'linestyle'
'c'	'color'
'fc'	'facecolor'
'ec'	'edgecolor'
'mew'	'markeredgewidth'
'aa'	'antialiased'

Таким образом, предыдущий вызов можно сократить до:

rc('lines', lw=2, c='r')

Обратите внимание: для хранения словарей параметров по умолчанию можно использовать возможность kwargs в словарях Python. Например, можно настроить параметры rc шрифта следующим образом:

font = {'family' : 'monospace',
        'weight' : 'bold',
        'size'   : 'larger'}
rc('font', **font)  # pass in the font dict as kwargs

Это позволяет легко переключаться между несколькими конфигурациями. Используйте matplotlib.style.use('default') или rcdefaults(), чтобы восстановить значения rcParams по умолчанию после внесения изменений.

Примечания

Аналогичные возможности доступны через обычный интерфейс словаря, то есть rcParams.update({"lines.linewidth": 2, ...}) (однако rcParams.update не поддерживает сокращения и группировку).

matplotlib.rcdefaults()[исходный код]

Восстанавливает rcParams из встроенного стиля Matplotlib по умолчанию.

Параметры rcParams, занесённые в чёрный список стилей (определены в matplotlib.style.core.STYLE_BLACKLIST), не обновляются.

См. также

matplotlib.rc_file_defaults: Восстанавливает rcParams из файла rc, изначально загруженного Matplotlib.
matplotlib.style.use: Использует определённый файл стиля. Вызовите style.use('default'), чтобы восстановить стиль по умолчанию.

matplotlib.rc_file_defaults()[исходный код]

Восстанавливает rcParams из исходного файла rc, загруженного Matplotlib.

Параметры rcParams, занесённые в чёрный список стилей (определены в matplotlib.style.core.STYLE_BLACKLIST), не обновляются.

matplotlib.rc_file(fname, *, use_default_template=True)[исходный код]

Обновляет rcParams из файла.

Параметры rcParams, занесённые в чёрный список стилей (определены в matplotlib.style.core.STYLE_BLACKLIST), не обновляются.

Параметры:

fnameстрока или объект, подобный пути: Файл с настройками rc для Matplotlib.
use_default_templatebool: Если True, перед обновлением значениями из указанного файла инициализировать параметры значениями по умолчанию. Если False, текущая конфигурация сохраняется, и обновляются только параметры, заданные в файле.

matplotlib.rc_params(fail_on_error=False)[исходный код]: Создаёт экземпляр RcParams из файла rc Matplotlib по умолчанию.

matplotlib.rc_params_from_file(fname, fail_on_error=False, use_default_template=True)[исходный код]

Создаёт экземпляр RcParams из файла fname.

Параметры:

fnameстрока или объект, подобный пути: Файл с настройками rc для Matplotlib.
fail_on_errorbool: Если True, при сбое анализатора во время преобразования параметра возникает ошибка.
use_default_templatebool: Если True, перед обновлением значениями из указанного файла инициализировать параметры значениями по умолчанию. Если False, класс конфигурации будет содержать только параметры, указанные в файле. (Полезно для обновления словарей.)

matplotlib.get_configdir()[исходный код]

Возвращает путь к каталогу конфигурации в виде строки.

Каталог выбирается следующим образом:

Если задана переменная окружения MPLCONFIGDIR, выбирается указанный в ней каталог.
В Linux используется спецификация XDG: сначала проверяется $XDG_CONFIG_HOME, если она задана, или $HOME/.config. На других платформах выбирается $HOME/.matplotlib.
Если выбранный каталог существует и доступен для записи, он используется в качестве каталога конфигурации.
В противном случае создаётся временный каталог, который используется в качестве каталога конфигурации.

matplotlib.matplotlib_fname()[исходный код]

Возвращает расположение файла конфигурации.

Расположение файла определяется в следующем порядке

$PWD/matplotlibrc
$MATPLOTLIBRC, если это не каталог
$MATPLOTLIBRC/matplotlibrc
$MPLCONFIGDIR/matplotlibrc
В Linux:
- $XDG_CONFIG_HOME/matplotlib/matplotlibrc (если определена $XDG_CONFIG_HOME)
- или $HOME/.config/matplotlib/matplotlibrc (если $XDG_CONFIG_HOME не определена)
На других платформах — $HOME/.matplotlib/matplotlibrc, если определена $HOME
В последнюю очередь проверяется $MATPLOTLIBDATA/matplotlibrc, который всегда должен существовать.

matplotlib.get_data_path()[исходный код]: Возвращает путь к данным Matplotlib.

Ведение журнала

matplotlib.set_loglevel(level)[исходный код]

Настраивает уровни ведения журнала Matplotlib.

Matplotlib использует стандартный модуль библиотеки Python logging в рамках корневого регистратора 'matplotlib'. Эта вспомогательная функция позволяет:

задать уровень корневого регистратора Matplotlib
задать уровень обработчика корневого регистратора, создав обработчик, если он ещё не существует

Обычно для получения дополнительных отладочных сведений следует вызвать set_loglevel("info") или set_loglevel("debug").

Пользователям или приложениям, устанавливающим собственные обработчики журналирования, может быть удобнее напрямую управлять logging.getLogger('matplotlib'), а не использовать эту функцию.

Параметры:

level{"notset", "debug", "info", "warning", "error", "critical"}: Уровень журнала обработчика.

Примечания

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

Цветовые карты и последовательности цветов

matplotlib.colormaps[исходный код]

Контейнер для цветовых карт, известных Matplotlib по именам.

Универсальный экземпляр реестра — matplotlib.colormaps. Пользователям не требуется создавать собственные экземпляры ColormapRegistry.

Для чтения используется интерфейс, подобный словарю, сопоставляющий имена с объектами Colormap:

import matplotlib as mpl
cmap = mpl.colormaps['viridis']

Возвращаемые объекты Colormap являются копиями, поэтому их изменение не влияет на глобальное определение цветовой карты.

Дополнительные цветовые карты можно добавлять с помощью ColormapRegistry.register:

mpl.colormaps.register(my_colormap)

Чтобы получить список всех зарегистрированных цветовых карт, выполните:

from matplotlib import colormaps
list(colormaps)

matplotlib.color_sequences[исходный код]

Контейнер для последовательностей цветов, известных Matplotlib по именам.

Универсальный экземпляр реестра — matplotlib.color_sequences. Пользователям не требуется создавать собственные экземпляры ColorSequenceRegistry.

Для чтения используется интерфейс, подобный словарю, сопоставляющий имена со списками цветов:

import matplotlib as mpl
colors = mpl.color_sequences['tab10']

Список встроенных последовательностей цветов см. в разделе Именованные последовательности цветов. Возвращаемые списки являются копиями, поэтому их изменение не влияет на глобальное определение последовательности цветов.

Дополнительные последовательности цветов можно добавлять с помощью ColorSequenceRegistry.register:

mpl.color_sequences.register('rgb', ['r', 'g', 'b'])

Разное

classmatplotlib.MatplotlibDeprecationWarning[исходный код]: Класс для выдачи предупреждений об устаревании для пользователей Matplotlib.

matplotlib.get_cachedir()[исходный код]

Возвращает строковый путь к каталогу кэша.

Процедура поиска каталога такая же, как для get_configdir, за исключением того, что вместо этого используются $XDG_CACHE_HOME/$HOME/.cache.