matplotlib.cbook

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

classmatplotlib.cbook.CallbackRegistry(exception_handler=<function _exception_printer>, *, signals=None)[исходный код]

Базовые классы: 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)[исходный код]

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

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

Параметры:

signalstr, необязательный

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

connect(signal, func)[исходный код]

Регистрирует func для вызова при возникновении сигнала signal.

disconnect(cid)[исходный код]

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

Если такого обратного вызова не существует, ошибка не возникает.

process(s, *args, **kwargs)[исходный код]

Обрабатывает сигнал s.

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

classmatplotlib.cbook.Grouper(init=())[исходный код]

Базовые классы: 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

get_siblings(a)[исходный код]

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

join(a, *args)[исходный код]

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

joined(a, b)[исходный код]

Возвращает, принадлежат ли a и b одному множеству.

remove(a)[исходный код]

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

classmatplotlib.cbook.GrouperView(grouper)[исходный код]

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

Неизменяемое представление Grouper.

get_siblings(a)[исходный код]

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

joined(a, b)[исходный код]

Возвращает, принадлежат ли a и b одному множеству.

matplotlib.cbook.boxplot_stats(X, whis=1.5, bootstrap=None, labels=None, autorange=False)[исходный код]

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

Параметры:

Xмассив или объект, подобный массиву

Данные, которые будут представлены на диаграммах размаха. Размерность должна быть не более 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, необязательный

Количество повторных выборок для вычисления доверительных интервалов вокруг медианы (процентильный метод).

labelsсписок строк, необязательный

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

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

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

Возвращает:

список словарей

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

Ключ	Описание значения
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. и Larsen, W.A. (1978) «Variations of Boxplots», The American Statistician, 32:12-16.

matplotlib.cbook.contiguous_regions(mask)[исходный код]

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

matplotlib.cbook.delete_masked_points(*args)[исходный код]

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

Аргументы могут относиться к одной из 5 категорий:

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

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

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

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

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

matplotlib.cbook.file_requires_unicode(x)[исходный код]

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

matplotlib.cbook.flatten(seq, scalarp=<function is_scalar_or_string>)[исходный код]

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

Например:

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

Авторы: объединённая работа Holger Krekel и Luther Blissett Источники: https://code.activestate.com/recipes/121294-simple-generator-for-flattening-nested-containers/ и рецепт 1.12 из cookbook

matplotlib.cbook.get_sample_data(fname, asfileobj=True)[исходный код]

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

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

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

matplotlib.cbook.index_of(y)[исходный код]

Вспомогательная функция для создания подходящих значений x для заданного y.

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

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

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

Параметры:

yfloat или объект, подобный массиву

Возвращает:

x, yndarray

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

matplotlib.cbook.is_math_text(s)[исходный код]

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

Для этого проверяется, содержит ли s чётное количество неэкранированных знаков доллара.

matplotlib.cbook.is_scalar_or_string(val)[исходный код]

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

matplotlib.cbook.is_writable_file_like(obj)[исходный код]

Возвращает, похож ли 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)[исходный код]

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

Параметры:

kwdict или None

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

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

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

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

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

Вызывает исключения:

TypeError

Чтобы соответствовать исключению, которое вызывает Python при передаче вызываемому объекту недопустимых аргументов или аргументов-ключевых слов.

matplotlib.cbook.open_file_cm(path_or_file, mode='r', encoding=None)[исходный код]

Передаёт файловые объекты без изменений и управляет путями-подобными объектами как контекстными менеджерами.

matplotlib.cbook.print_cycles(objects, outstream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, show_progress=False)[исходный код]

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

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

Параметры:

objects

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

outstream

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

show_progressbool

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

matplotlib.cbook.pts_to_midstep(x, *args)[исходный код]

Преобразует непрерывную линию в ступени со сменой значений в середине интервалов.

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

Параметры:

xarray

Положение ступеней по оси x. Может быть пустым.

y1, ..., yparray

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

Возвращает:

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)[исходный код]

Преобразует непрерывную линию в ступени со сменой значений в конце интервалов.

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

Параметры:

xarray

Положение ступеней по оси x. Может быть пустым.

y1, ..., yparray

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

Возвращает:

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)[исходный код]

Преобразует непрерывную линию в ступени со сменой значений в начале интервалов.

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

Параметры:

xarray

Положение ступеней по оси x. Может быть пустым.

y1, ..., yparray

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

Возвращает:

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.safe_first_element(obj)[исходный код]

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

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

matplotlib.cbook.safe_masked_invalid(x, copy=False)[исходный код]

matplotlib.cbook.sanitize_sequence(data)[исходный код]

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

classmatplotlib.cbook.silent_list(type, seq=None)[исходный код]

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

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

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

Вместо

[<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)[исходный код]

Изменяет частоту дискретизации массива, добавляя steps - 1 точек между исходными парами точек.

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

Параметры:

aarray, shape (n, ...)

stepsint

Возвращает:

array

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

matplotlib.cbook.strip_math(s)[исходный код]

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

Обрабатывает только полностью математические или полностью нематематические строки.

matplotlib.cbook.to_filehandle(fname, flag='r', return_opened=False, encoding=None)[исходный код]

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

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

Параметры:

fnamestr or path-like or file-like

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

flagstr, default: 'r'

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

return_openedbool, default: False

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

encodingstr or None, default: None

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

Возвращает:

fhfile-like

openedbool

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

matplotlib.cbook.violin_stats(X, method, points=100, quantiles=None)[исходный код]

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

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

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

Параметры:

Xarray-like

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

methodcallable

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

pointsint, default: 100

Задаёт количество точек, в которых вычисляется каждая оценка плотности ядра Гаусса.

quantilesarray-like, default: None

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

Возвращает:

list of dict

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

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