matplotlib.cbook

Содержит набор служебных функций и классов. Первоначально многие (но не все) были из Python Cookbook, откуда и название cbook.

classmatplotlib.cbook.CallbackRegistry(exception_handler=<function _exception_printer>, *, signals=None)[source]

Базовые классы: object

Обработка регистрации, обработки, блокирования и отключения набора сигналов и обратных вызовов:

>>> def oneat(x):
...     print('eat', x)
>>> def ondrink(x):
...     print('drink', x)

>>> from matplotlib.cbook import CallbackRegistry
>>> callbacks = CallbackRegistry()

>>> id_eat = callbacks.connect('eat', oneat)
>>> id_drink = callbacks.connect('drink', ondrink)

>>> callbacks.process('drink', 123)
drink 123
>>> callbacks.process('eat', 456)
eat 456
>>> callbacks.process('be merry', 456)   # nothing will be called

>>> callbacks.disconnect(id_eat)
>>> callbacks.process('eat', 456)        # nothing will be called

>>> with callbacks.blocked(signal='drink'):
...     callbacks.process('drink', 123)  # nothing will be called
>>> callbacks.process('drink', 123)
drink 123

На практике следует всегда отключать все обратные вызовы, когда они больше не нужны, чтобы избежать висячих ссылок (и, следовательно, утечек памяти). Однако реальный код в Matplotlib редко делает это, и из-за его конструкции довольно сложно разместить такой код. Чтобы обойти эту проблему и предотвратить этот тип утечек памяти, мы вместо этого храним только слабые ссылки на связанные методы, поэтому, когда целевому объекту нужно умереть, CallbackRegistry не будет его поддерживать.

Параметры:

exception_handlerвызываемый объект, необязательно

Если не равно None, exception_handler должен быть функцией, которая принимает исключение Exception в качестве единственного параметра. Он вызывается с любым исключением Exception, возбуждённым обратными вызовами во время CallbackRegistry.process, и может либо повторно возбудить исключение, либо обработать его другим способом.

Обработчик по умолчанию выводит исключение (с помощью traceback.print_exc), если запущен интерактивный цикл событий; он повторно возбуждает исключение, если интерактивный цикл событий не запущен.

signalsсписок, необязательно

Если не равно None, signals — это список сигналов, которые обрабатывает этот регистр: попытка process или connect к сигналу, отсутствующему в списке, возбуждает ValueError. По умолчанию, None, не накладывает ограничений на обрабатываемые сигналы.

blocked(*, signal=None)[source]

Блокировать обработку сигналов обратных вызовов.

Контекстный менеджер для временного блокирования/отключения обработки сигналов обратных вызовов зарегистрированными слушателями.

Параметры:

signalстрока, необязательно

Сигнал обратного вызова, который нужно заблокировать. По умолчанию блокируются все сигналы.

connect(signal, func)[source]

Зарегистрировать func для вызова при генерации сигнала signal.

disconnect(cid)[source]

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

Ошибка не возбуждается, если такой обратный вызов не существует.

process(s, *args, **kwargs)[source]

Обработать сигнал s.

Все функции, зарегистрированные для получения обратных вызовов на s, будут вызваны с *args и **kwargs.

classmatplotlib.cbook.Grouper(init=())[source]

Базовые классы: object

Структура данных непересекающихся множеств.

Объекты могут быть объединены с помощью join(), проверены на подключенность с помощью joined(), а все непересекающиеся множества могут быть получены с помощью объекта в качестве итератора.

Объединяемые объекты должны быть хешируемыми и поддерживать слабые ссылки.

Примеры

>>> from matplotlib.cbook import Grouper
>>> class Foo:
...     def __init__(self, s):
...         self.s = s
...     def __repr__(self):
...         return self.s
...
>>> a, b, c, d, e, f = [Foo(x) for x in 'abcdef']
>>> grp = Grouper()
>>> grp.join(a, b)
>>> grp.join(b, c)
>>> grp.join(d, e)
>>> list(grp)
[[a, b, c], [d, e]]
>>> grp.joined(a, b)
True
>>> grp.joined(a, c)
True
>>> grp.joined(a, d)
False

clean()[source]

[Устаревшее] Очистить мертвые слабые ссылки из словаря.

Примечания

Устарело начиная с версии 3.8: Используйте ничего, вам больше не нужно очищать Grouper.

get_siblings(a)[source]

Возвращает все элементы, объединённые с a, включая его самого.

join(a, *args)[source]

Объединяет указанные аргументы в одно множество. Принимает один или несколько аргументов.

joined(a, b)[source]

Возвращает, являются ли a и b членами одного и того же множества.

remove(a)[source]

Удаляет a из группировщика, не делая ничего, если его там нет.

classmatplotlib.cbook.GrouperView(grouper)[source]

Bases: object

Неизменяемый вид на Grouper.

get_siblings(a)[source]

joined(a, b)[source]

classmatplotlib.cbook.Stack(default=None)[source]

Bases: object

[Устарело] Стек элементов с перемещаемым курсором.

Имитирует навигацию назад/вперед в веб-браузере.

Примечания

Устарело начиная с версии 3.8.

back()[source]

Переместить позицию назад и вернуть текущий элемент.

bubble(o)[source]

Поднять все ссылки на o наверх стека и вернуть его.

Исключения:

ValueError

Если o не находится в стеке.

clear()[source]

Очистить стек.

empty()[source]

Возвращает, пуст ли стек.

forward()[source]

Переместить позицию вперед и вернуть текущий элемент.

home()[source]

Поместить первый элемент в начало стека.

Возвращается первый элемент.

push(o)[source]

Поместить o в стек на текущую позицию. Отбросить все последующие элементы.

Возвращается o.

remove(o)[source]

Удалить o из стека.

Исключения:

ValueError

Если o не находится в стеке.

matplotlib.cbook.boxplot_stats(X, whis=1.5, bootstrap=None, labels=None, autorange=False)[source]

Возвращает список словарей со статистикой, используемой для построения набора диаграмм размаха с использованием bxp.

Параметры:

Xarray-like

Данные, которые будут представлены на диаграммах размаха. Должны иметь 2 или меньше измерений.

whisfloat или (float, float), по умолчанию: 1.5

Позиция усов.

Если число, то нижний ус находится в наименьшем значении выше Q1 - whis*(Q3-Q1), а верхний ус — в наибольшем значении ниже Q3 + whis*(Q3-Q1), где Q1 и Q3 — первый и третий квартили. Значение по умолчанию whis = 1.5 соответствует исходному определению диаграмм размаха по Туки.

Если пара чисел, они указывают на процентили, по которым нужно рисовать усы (например, (5, 95)). В частности, установка значения (0, 100) приводит к усам, охватывающим весь диапазон данных.

В случае, когда Q1 == Q3, whis автоматически устанавливается в (0, 100) (охватывает весь диапазон данных), если autorange равно True.

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

bootstrapint, необязательно

Число раз, когда интервалы достоверности вокруг медианы должны быть получены методом бутстрепа (метод процентилей).

labelsarray-like, необязательно

Метки для каждого набора данных. Длина должна быть совместима с измерениями X.

autorangebool, необязательно (False)

Когда True и данные распределены таким образом, что 25-й и 75-й процентили равны, whis устанавливается в (0, 100), так что концы усов находятся на минимуме и максимуме данных.

Возвращаемое значение:

list of dict

Список словарей, содержащих результаты для каждого столбца данных. Ключи каждого словаря следующие:

Ключ	Описание значения
label	метка для диаграммы размаха
mean	арифметическое среднее значение
med	50-й процентиль
q1	первый квартиль (25-й процентиль)
q3	третий квартиль (75-й процентиль)
iqr	межквартильный размах
cilo	нижняя отметка вокруг медианы
cihi	верхняя отметка вокруг медианы
whislo	конец нижнего уса
whishi	конец верхнего уса
fliers	выбросы

Примечания

Не-бутстреповский подход к интервалу достоверности использует основанное на гауссовском приближении асимптотическое приближение:

\[\mathrm{med} \pm 1.57 \times \frac{\mathrm{iqr}}{\sqrt{N}}\]

Общий подход из: McGill, R., Tukey, J.W., and Larsen, W.A. (1978) "Variations of Boxplots", The American Statistician, 32:12-16.

matplotlib.cbook.contiguous_regions(mask)[source]

Возвращает список (ind0, ind1) такой, что mask[ind0:ind1].all() истинно и мы покрываем все такие области.

matplotlib.cbook.delete_masked_points(*args)[source]

Находит все замаскированные и/или неконечные точки в наборе аргументов и возвращает аргументы, содержащие только незамаскированные точки.

Аргументы могут быть любого из 5 типов:

1. Одномерные массивы с маской
2. Одномерные массивы NumPy
3. Массивы NumPy с более чем одним измерением
4. Другие итерируемые объекты, не являющиеся строками
5. Всё остальное

Первый аргумент должен быть одного из первых четырёх типов; любые аргументы с длиной, отличающейся от длины первого аргумента (и, следовательно, любые аргументы 5-го типа) передаются без изменений.

Маски получаются от всех аргументов правильной длины в категориях 1, 2 и 4; точка считается плохой, если она замаскирована в массиве с маской или если это nan или inf. Не делается попытки извлечь маску из категорий 2, 3 и 4, если numpy.isfinite не возвращает массив bool.

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

Значительно упрощённая версия этой функции изначально была написана как вспомогательная функция для Axes.scatter().

matplotlib.cbook.file_requires_unicode(x)[source]

Возвращает значение, определяющее, требует ли данный объект типа «файл» для записи Unicode.

matplotlib.cbook.flatten(seq, scalarp=<function is_scalar_or_string>)[source]

Возвращает генератор, разворачивающий вложенные контейнеры.

Например:

>>> from matplotlib.cbook import flatten
>>> l = (('John', ['Hunter']), (1, 23), [[([42, (5, 23)], )]])
>>> print(list(flatten(l)))
['John', 'Hunter', 1, 23, 42, 5, 23]

Автор: Композиция Хольгера Крекеля и Лютера Блиссета Источник: https://code.activestate.com/recipes/121294/ и рецепт 1.12 в кулинарной книге

matplotlib.cbook.get_sample_data(fname, asfileobj=True, *, np_load=<deprecated parameter>)[source]

Возвращает файл образца данных. fname — это путь, относительный к каталогу mpl-data/sample_data. Если asfileobj равен True, возвращает объект файла, в противном случае — просто путь к файлу.

Файлы образцов данных хранятся в каталоге 'mpl-data/sample_data' внутри пакета Matplotlib.

Если имя файла заканчивается на .gz, файл неявно распаковывается. Если имя файла заканчивается на .npy или .npz, и asfileobj равен True, файл загружается с помощью numpy.load.

matplotlib.cbook.index_of(y)[source]

Функция-помощник для создания разумных значений x для заданного y.

Используется для построения графиков (x, y), если значения x не заданы явно.

Сначала попробуйте y.index (предполагая, что y — это pandas.Series), если это не сработает, используйте range(len(y)).

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

Параметры:

yfloat или array-like

Возвращает:

x, yndarray

Значения x и y для построения графика.

matplotlib.cbook.is_math_text(s)[source]

Возвращает, содержит ли строка s математические выражения.

Это делается путем проверки, содержит ли s четное число неэкранированных знаков доллара.

matplotlib.cbook.is_scalar_or_string(val)[source]

Возвращает, является ли заданный объект скаляром или похожим на строку.

matplotlib.cbook.is_writable_file_like(obj)[source]

Возвращает, похоже ли obj на объект файла с методом write.

matplotlib.cbook.ls_mapper={'-': 'solid', '--': 'dashed', '-.': 'dashdot', ':': 'dotted'}

Преобразует короткие коды стиля линии в их полные имена, используемые бэкендами.

matplotlib.cbook.ls_mapper_r={'dashdot': '-.', 'dashed': '--', 'dotted': ':', 'solid': '-'}

Преобразует полные имена стилей линий, используемых бэкендами, в их короткие коды.

matplotlib.cbook.normalize_kwargs(kw, alias_mapping=None)[source]

Функция-помощник для нормализации входных данных kwarg.

Параметры:

kwdict или None

Словарь ключевых аргументов. None явно поддерживается и обрабатывается как пустой словарь, чтобы поддерживать функции с необязательным параметром в формате props=None.

alias_mappingdict или подкласс Artist или экземпляр Artist, необязательно

Сопоставление между каноническим именем и списком псевдонимов в порядке приоритета, от низшего к высшему.

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

Если передан подкласс или экземпляр Artist, используется его сопоставление псевдонимов.

Исключения:

TypeError

Для соответствия тому, что Python поднимает, если переданы неверные аргументы/ключевые аргументы вызываемому объекту.

matplotlib.cbook.open_file_cm(path_or_file, mode='r', encoding=None)[source]

Передача объектов файлов и управление контекстом для путей.

matplotlib.cbook.print_cycles(objects, outstream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, show_progress=False)[source]

Вывод циклов циклических ссылок в заданных objects.

Зачастую полезно передавать gc.garbage для поиска циклов, которые препятствуют сборке мусора некоторых объектов.

Параметры:

objects

Список объектов, в которых нужно найти циклы.

outstream

Поток для вывода.

show_progressbool

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

matplotlib.cbook.pts_to_midstep(x, *args)[source]

Преобразование непрерывной линии в средние шаги.

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

Параметры:

xмассив

Расположение x шагов. Может быть пустым.

y1, ..., ypмассив

массивы y, которые должны быть преобразованы в шаги; все должны иметь одинаковую длину, что и x.

Возвращает:

массив

Значения x и y, преобразованные в шаги в том же порядке, что и на входе; может быть распакован как x_out, y1_out, ..., yp_out. Если вход имеет длину N, каждый из этих массивов будет иметь длину 2N.

Примеры

>>> x_s, y1_s, y2_s = pts_to_midstep(x, y1, y2)

matplotlib.cbook.pts_to_poststep(x, *args)[source]

Преобразование непрерывной линии в пост-шаги.

Для заданного набора N точек преобразует в 2N + 1 точки, которые при линейном соединении дают ступенчатую функцию, меняющую значения в конце интервалов.

Параметры:

xмассив

Расположение x шагов. Может быть пустым.

y1, ..., ypмассив

массивы y, которые должны быть преобразованы в шаги; все должны иметь одинаковую длину, что и x.

Возвращает:

массив

Значения x и y, преобразованные в шаги в том же порядке, что и на входе; может быть распакован как x_out, y1_out, ..., yp_out. Если вход имеет длину N, каждый из этих массивов будет иметь длину 2N + 1. Для N=0, длина будет 0.

Примеры

>>> x_s, y1_s, y2_s = pts_to_poststep(x, y1, y2)

matplotlib.cbook.pts_to_prestep(x, *args)[source]

Преобразование непрерывной линии в предварительные шаги.

Учитывая набор N точек, преобразуйте их в 2N - 1 точки, которые, при линейном соединении, дадут ступенчатую функцию, изменяющую значения в начале интервалов.

Параметры:

xмассив

Положение x шагов. Может быть пустым.

y1, ..., ypмассив

Массивы y, которые должны быть преобразованы в шаги; все должны иметь одинаковую длину с x.

Возвращает:

массив

Значения x и y, преобразованные в шаги в том же порядке, что и входные данные; их можно распаковать как x_out, y1_out, ..., yp_out. Если длина входных данных N, каждый из этих массивов будет иметь длину 2N + 1. Для N=0, длина будет 0.

Примеры

>>> x_s, y1_s, y2_s = pts_to_prestep(x, y1, y2)

matplotlib.cbook.safe_first_element(obj)[source]

Возвращает первый элемент в obj.

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

matplotlib.cbook.safe_masked_invalid(x, copy=False)[source]

matplotlib.cbook.sanitize_sequence(data)[source]

Преобразует объекты dictview в список. Другие входные данные возвращаются без изменений.

classmatplotlib.cbook.silent_list(type, seq=None)[source]

Базы: list

Список с коротким repr().

Предназначен для использования с однородным списком объектов-артистов, чтобы они не выводили длинный бессмысленный вывод.

Вместо

[<matplotlib.lines.Line2D object at 0x7f5749fed3c8>,
 <matplotlib.lines.Line2D object at 0x7f5749fed4e0>,
 <matplotlib.lines.Line2D object at 0x7f5758016550>]

получим

<a list of 3 Line2D objects>

Если self.type равно None, имя типа берётся из первого элемента списка (если таковой имеется).

matplotlib.cbook.simple_linear_interpolation(a, steps)[source]

Перевыборка массива с steps - 1 точками между парами исходных точек.

Вдоль каждой колонки массива a вводятся (steps - 1) точек между каждым исходным значением; значения интерполируются линейно.

Параметры:

aмассив, форма (n, ...)

stepsцелое число

Возвращает:

массив

форма ((n - 1) * steps + 1, ...)

matplotlib.cbook.strip_math(s)[source]

Удаление форматирования LaTeX из mathtext.

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

matplotlib.cbook.to_filehandle(fname, flag='r', return_opened=False, encoding=None)[source]

Преобразует путь в открытый дескриптор файла или передает объект, подобный файлу.

Рассмотрите использование open_file_cm, так как оно позволяет проще и правильно закрывать недавно созданные объекты файлов.

Параметры:

fnameстрока или путь или объект, подобный файлу

Если str или os.PathLike, файл открывается с использованием флагов, заданных flag и encoding. Если объект, подобный файлу, он передаётся.

flagстрока, по умолчанию: 'r'

Передаётся в качестве аргумента mode к open, когда fname является str или os.PathLike; игнорируется, если fname является объектом, подобным файлу.

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

Если True, возвращает как объект файла, так и булевое значение, указывающее, был ли это новый файл (который вызывающий код должен закрыть). Если False, возвращает только новый файл.

encodingстрока или None, по умолчанию: None

Передаётся в качестве аргумента mode к open, когда fname является str или os.PathLike; игнорируется, если fname является объектом, подобным файлу.

Возвращает:

fhобъект, подобный файлу

openedbool

opened возвращается только в том случае, если return_opened равно True.

matplotlib.cbook.violin_stats(X, method, points=100, quantiles=None)[source]

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

См. раздел Returns ниже, чтобы увидеть необходимые ключи словаря.

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

Параметры:

Xarray-like

Данные выборки, которые будут использованы для создания оценок плотности гауссова ядра. Должны иметь 2 или меньше измерения.

methodcallable

Метод, используемый для вычисления оценки плотности ядра для каждого столбца данных. При вызове через method(v, coords), он должен возвращать вектор значений KDE, вычисленных в значениях, указанных в coords.

pointsint, по умолчанию: 100

Определяет количество точек для оценки каждой из оценок плотности гауссова ядра.

quantilesarray-like, по умолчанию: None

Определяет (если не None) список чисел с плавающей точкой в интервале [0, 1] для каждого столбца данных, который представляет квантили, которые будут отображаться для этого столбца данных. Должны иметь 2 или меньше измерения. 1D массив будет обрабатываться как одиночный список, содержащий их.

Возвращаемое значение:

list of dict

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

• coords: Список скаляров, содержащих координаты, в которых была вычислена эта оценка плотности ядра.
• vals: Список скаляров, содержащих значения оценки плотности ядра в каждой из координат, указанных в coords.
• mean: Среднее значение для данного столбца данных.
• median: Медианное значение для данного столбца данных.
• min: Минимальное значение для данного столбца данных.
• max: Максимальное значение для данного столбца данных.
• quantiles: Значения квантилей для данного столбца данных.