cbook

matplotlib.cbook

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

Этот модуль безопасно импортировать из любой части matplotlib; он импортирует matplotlib только во время выполнения.

class matplotlib.cbook.Bunch(**kwargs) [source]

Базы: types.SimpleNamespace

Устарело начиная с версии 3.0: Класс Bunch устарел в Matplotlib 3.0 и будет удален в версии 3.2. Используйте types.SimpleNamespace вместо него.

Часто нам нужно просто собрать несколько вещей вместе, присвоив имя каждой части; для этого подойдёт словарь, но даже лучше использовать небольшой класс без действий, он ещё и красивее в использовании. Всякий раз, когда вы хотите сгруппировать несколько переменных:

>>> point = Bunch(datum=2, squared=4, coord=12)
>>> point.datum

class matplotlib.cbook.CallbackRegistry(exception_handler=<function _exception_printer>) [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

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

Параметры:

Параметры:	`exception_handler : callable, optional` Если указано, должно быть с сигнатурой def handler(exc: Exception) -> None: Если не None, эта функция будет вызываться с любым подклассом `Exception`, вызванным обратными вызовами в `CallbackRegistry.process`. Обработчик может либо обработать исключение, либо повторно вызвать его. Вызываемая функция должна быть сериализуемой. По умолчанию используется обработчик def h(exc): traceback.print_exc()

exception_handler : callable, optional

Если указано, должно быть с сигнатурой

def handler(exc: Exception) -> None:

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

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

По умолчанию используется обработчик

def h(exc):
    traceback.print_exc()

connect(s, func) [source]: Зарегистрировать func для вызова при генерации сигнала s.

disconnect(cid) [source]: Отключить зарегистрированный обратный вызов с идентификатором обратного вызова cid.

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

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

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

class matplotlib.cbook.GetRealpathAndStat(**kwargs) [source]: Базы: object

Устарело начиная с версии 3.0: Класс GetRealpathAndStat устарел в Matplotlib 3.0 и будет удален в версии 3.2.

class matplotlib.cbook.Grouper(init=()) [source]

Базы: object

Этот класс предоставляет лёгкий способ группировать произвольные объекты в непересекающиеся наборы, когда полная графовая структура будет излишней.

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

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

Например:

>>> from matplotlib.cbook import Grouper
>>> class Foo(object):
...     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)
>>> sorted(map(tuple, grp))
[(a, b, c), (d, e)]
>>> grp.joined(a, b)
True
>>> grp.joined(a, c)
True
>>> grp.joined(a, d)
False

clean() [source]: Очистка мёртвых слабых ссылок из словаря.

get_siblings(a) [source]: Возвращает все элементы, объединённые с a, включая сам элемент.

join(a, *args) [source]: Объединить заданные аргументы в один набор. Принимает один или несколько аргументов.

joined(a, b) [source]: Возвращает True, если a и b являются членами одного набора.

remove(a) [source]

exception matplotlib.cbook.IgnoredKeywordWarning [source]

Базы: UserWarning

Класс для выдачи предупреждений об аргументах ключевых слов, которые будут проигнорированы matplotlib

class matplotlib.cbook.Locked(**kwargs) [source]

Базы: object

Устарело начиная с версии 3.0: Класс Locked устарел в Matplotlib 3.0 и будет удален в версии 3.2.

Менеджер контекста для обработки блокировок.

Основано на коде из conda.

conda распространяется на условиях лицензии BSD с тремя пунктами. См. LICENSE_CONDA или https://opensource.org/licenses/BSD-3-Clause.

LOCKFN = '.matplotlib_lock'

exception TimeoutError [source]: Базы: RuntimeError

END_OF_DOCUMENT_MARKER

class matplotlib.cbook.Stack(default=None) [source]

Bases: object

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

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

back() [source]: Перемещает позицию назад и возвращает текущий элемент.

bubble(o) [source]

Поднимает o наверх стека. o должен присутствовать в стеке.

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

clear() [source]: Очищает стек.

empty() [source]: Возвращает, пуст ли стек.

forward() [source]: Перемещает позицию вперед и возвращает текущий элемент.

home() [source]

Помещает первый элемент наверх стека.

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

push(o) [source]

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

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

remove(o) [source]: Удаляет o из стека.

matplotlib.cbook.align_iterators(func, *iterables) [source]

Deprecated since version 2.2: Функция align_iterators была помечена как устаревшая в Matplotlib 2.2 и будет удалена в 3.1.

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

(func(row), [rows from all iterators matching func(row)])

Используется функцией matplotlib.mlab.recs_join() для объединения массивов записей.

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

Возвращает список словарей со статистикой, используемой для построения набора диаграмм размаха. Раздел Returns перечисляет необходимые ключи словаря. Пользователи могут пропустить эту функцию и передать собственный набор словарей в новый метод axes.bxp, вместо того, чтобы полагаться на MPL для вычислений.

Параметры:

X : array-like: Данные, которые будут представлены в диаграммах размаха. Должны иметь 2 или менее измерения.
whis : float, string, or sequence (default = 1.5): В качестве числа определяет область усиков за пределами первого и третьего квартилей. Другими словами, если IQR — это межквартильный размах (Q3-Q1), верхний усик будет простираться до последнего значения, меньшего чем Q3 + whis*IQR). Аналогично, нижний усик будет простираться до первого значения, большего чем Q1 - whis*IQR. За пределами усиков данные считаются выбросами и отображаются как отдельные точки. Это можно задать как возрастающую последовательность процентилей (например, [5, 95]), чтобы установить усики на определённых процентилях данных. Наконец, whis может быть строкой 'range', чтобы зафиксировать усики на минимальном и максимальном значениях данных. В крайнем случае, когда 25-й и 75-й процентили совпадают, whis может автоматически устанавливаться в 'range' с помощью опции autorange.
bootstrap : int, optional: Количество раз, когда интервалы доверительной области вокруг медианы должны быть сэмплированы методом бутстрепа (метод процентилей).
labels : array-like, optional: Метки для каждого набора данных. Длина должна быть совместима с измерениями X.
autorange : bool, optional (False): Если True и данные распределены таким образом, что 25-й и 75-й процентили равны, whis устанавливается в 'range', чтобы усики заканчивались на минимальном и максимальном значениях данных.

Возвращает:

bxpstats : list of dict

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

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

Примечания

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

Общий подход взят из: 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.dedent(s) [source]

Удаляет избыточную вложенность из строковой документации s.

Отбрасывает любые ведущие пустые строки, затем удаляет до n пробельных символов из каждой строки, где n — количество ведущих пробельных символов в первой строке. Отличается от textwrap.dedent тем, что удаляет ведущие пустые строки и использует первую непустую строку для определения отступа.

Также быстрее в большинстве случаев.

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

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

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

Одномерные маскированные массивы
Одномерные массивы NumPy
Массивы NumPy с более чем одним измерением
Другие итерируемые объекты, не являющиеся строками
Любой другой тип

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

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

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

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

matplotlib.cbook.file_requires_unicode(x) [source]: Возвращает True, если данному файловому объекту для записи требуется 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_label(y, default_name) [source]

matplotlib.cbook.get_realpath_and_stat [source]

matplotlib.cbook.get_sample_data(fname, asfileobj=True) [source]

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

Установите параметр rc examples.directory в каталог, где следует искать, если файлы sample_data хранятся в местоположении, отличном от стандартного (по умолчанию — 'mpl-data/sample_data` на том же уровне, что и файлы Python-модуля 'matplotlib').

Если имя файла заканчивается на .gz, файл неявно распаковывается.

matplotlib.cbook.index_of(y) [source]

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

Попытка получить y.index (работает, если это pd.Series), если это не удаётся, возвращает np.arange(y.shape[0]).

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

Параметры:	`y : scalar or array-like` Предлагаемое значение y
Возвращает:	`x, y : ndarray` Значения x и y для построения графика.

matplotlib.cbook.is_hashable(obj) [source]: Возвращает True, если obj может быть хеширован

matplotlib.cbook.is_math_text(s) [source]

matplotlib.cbook.is_numlike(obj) [source]: Устарело начиная с версии 3.0: isinstance(..., numbers.Number)

Возвращает True, если obj похож на число

matplotlib.cbook.is_scalar_or_string(val) [source]: Возвращает True, если данный объект является скаляром или строкой.

matplotlib.cbook.is_writable_file_like(obj) [source]: Возвращает True, если obj похож на объект файла с методом write

matplotlib.cbook.iterable(obj) [source]: Возвращает True, если obj является итерируемым

matplotlib.cbook.listFiles(root, patterns='*', recurse=1, return_folders=0) [source]

Устарело начиная с версии 3.0: Функция listFiles устарела в Matplotlib 3.0 и будет удалена в 3.2.

Рекурсивный список файлов

из Parmar и Martelli в Python Cookbook

matplotlib.cbook.local_over_kwdict(local_var, kwargs, *keys) [source]

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

local_var > kwargs[keys[0]] > ... > kwargs[keys[-1]]

Будет возвращено первое из них, значение которого не равно None. Если все они равны None, возвращается None. Каждый ключ в ключах будет удален из словаря kwargs на месте.

Параметры:	local_var: любой объект Локальная переменная (самый высокий приоритет) kwargs: dict Словарь ключевых аргументов; изменяется на месте keys: str(s) Имя(а) ключевых аргументов для обработки в порядке убывания приоритета
Возвращает:	out: любой объект Либо local_var, либо один из kwargs[key] для key в keys
Возбуждает:	IgnoredKeywordWarning Для каждого ключа в ключах, который удаляется из kwargs, но не используется в качестве значения вывода

class matplotlib.cbook.maxdict(maxsize) [source]

Базируется на dict

Словарь с максимальным размером; это не переопределяет все соответствующие методы для ограничения размера, только setitem, поэтому используйте с осторожностью

matplotlib.cbook.mkdirs(newdir, mode=511) [source]

Устарело начиная с версии 3.0: Функция mkdirs устарела в Matplotlib 3.0 и будет удалена в 3.2.

Рекурсивно создаёт каталог newdir и устанавливает mode. Эквивалентно

> mkdir -p NEWDIR
> chmod MODE NEWDIR

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

Вспомогательная функция для нормализации входных данных kwargs

Порядок их разрешения:

алиасирование
обязательные
запрещённые
разрешённые

Этот порядок означает, что только канонические имена должны присутствовать в allowed, forbidden, required

Параметры:

Параметры:	alias_mapping, dict, optional Словарь соответствий между каноническим именем и списком алиасов в порядке убывания приоритета. Если каноническое значение не находится в списке, предполагается, что оно имеет наивысший приоритет. `required : iterable, optional` Кортеж полей, которые должны быть в kwargs. `forbidden : iterable, optional` Список ключей, которые не должны быть в kwargs `allowed : tuple, optional` Кортеж разрешённых полей. Если это не None, то возникает ошибка, если `kw` содержит ключи, отсутствующие в объединении `required` и `allowed`. Чтобы разрешить только необходимые поля, передайте `()` для `allowed`
Возбуждает:	TypeError Для соответствия тому, что Python вызывает, если передаются некорректные args/kwargs вызываемому объекту.

alias_mapping, dict, optional

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

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

required : iterable, optional

Кортеж полей, которые должны быть в kwargs.

forbidden : iterable, optional

Список ключей, которые не должны быть в kwargs

allowed : tuple, optional

Кортеж разрешённых полей. Если это не None, то возникает ошибка, если kw содержит ключи, отсутствующие в объединении required и allowed. Чтобы разрешить только необходимые поля, передайте () для allowed

Возбуждает:

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

matplotlib.cbook.open_file_cm(path_or_file, mode='r', encoding=None) [source]: Передаёт объекты файлов и управляет контекстом PathLike.

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

objects: Список объектов, в которых следует найти циклы. Часто полезно передать gc.garbage, чтобы найти циклы, которые мешают сборке мусора некоторых объектов.
outstream: Поток для вывода.
show_progress: Если True, выводится количество достигнутых объектов по мере обнаружения.

END_OF_DOCUMENT_MARKER

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

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

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

Параметры:	`x : array` Положение x шагов. Может быть пустым. `y1, ..., yp : array` Массивы y, которые должны быть преобразованы в шаги; все они должны иметь такую же длину, как `x`.
Возвращаемое значение:	`out : array` Значения 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 : array: Положение x шагов. Может быть пустым.
y1, ..., yp : array: Массивы y, которые должны быть преобразованы в шаги; все они должны иметь такую же длину, как x.

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

out : array: Значения 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 : array: Положение x шагов. Может быть пустым.
y1, ..., yp : array: Массивы y, которые должны быть преобразованы в шаги; все они должны иметь такую же длину, как x.

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

out : array: Значения 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.report_memory(i=0) [source]: возвращает память, потребляемую процессом

matplotlib.cbook.safe_first_element(obj) [source]

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

matplotlib.cbook.safezip(*args) [source]: убедитесь, что args имеют одинаковую длину перед сжатием

matplotlib.cbook.sanitize_sequence(data) [source]: Преобразует объект dictview в список

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

Наследует от list

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

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

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

Параметры:	`a : array, shape (n, ...)` `steps : int`
Возвращаемое значение:	*массив, форма ``((n - 1) шаги + 1, ...)`` Вдоль каждого столбца a, ``(шаги - 1)`` точек вводятся между каждой пары исходных значений; значения линейно интерполируются.**

matplotlib.cbook.strip_math(s) [source]: удаление форматирования latex из mathtext

matplotlib.cbook.to_filehandle(fname, flag='rU', return_opened=False, encoding=None) [source]: fname может быть os.PathLike или дескриптором файла. Поддержка сжатых файлов gzip автоматическая, если имя файла заканчивается на .gz. flag — это флаг чтения/записи для file()

matplotlib.cbook.unicode_safe(s) [source]: Устарело начиная с версии 3.0: Функция unicode_safe была устарела в Matplotlib 3.0 и будет удалена в 3.2.

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

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

Параметры:

Параметры:	`X : array-like` Данные выборок, которые будут использованы для создания оценок плотности гауссова ядра. Должны иметь 2 или меньше измерений. `method : callable` Метод, используемый для расчета оценки плотности ядра для каждого столбца данных. При вызове через `method(v, coords)`, он должен возвращать вектор значений KDE, вычисленных в значениях, указанных в coords. `points : scalar, default = 100` Определяет количество точек для оценки каждой из оценок плотности гауссова ядра.
Возвращаемое значение:	Список словарей, содержащих результаты для каждого столбца данных. Словари содержат по крайней мере следующие: coords: Список скаляров, содержащих координаты, в которых был вычислен этот конкретный KDE. vals: Список скаляров, содержащих значения оценки плотности ядра в каждой из координат, указанных в `coords`. mean: Среднее значение для этого столбца данных. median: Медианное значение для этого столбца данных. min: Минимальное значение для этого столбца данных. max: Максимальное значение для этого столбца данных.

X : array-like: Данные выборок, которые будут использованы для создания оценок плотности гауссова ядра. Должны иметь 2 или меньше измерений.
method : callable: Метод, используемый для расчета оценки плотности ядра для каждого столбца данных. При вызове через method(v, coords), он должен возвращать вектор значений KDE, вычисленных в значениях, указанных в coords.
points : scalar, default = 100: Определяет количество точек для оценки каждой из оценок плотности гауссова ядра.

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

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

Словари содержат по крайней мере следующие:

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