Структурированные массивы

Введение

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

>>> x = np.array([('Rex', 9, 81.0), ('Fido', 3, 27.0)],
...              dtype=[('name', 'U10'), ('age', 'i4'), ('weight', 'f4')])
>>> x
array([('Rex', 9, 81.), ('Fido', 3, 27.)],
      dtype=[('name', 'U10'), ('age', '<i4'), ('weight', '<f4')])

Здесь x — одномерный массив длиной два, тип данных которого представляет собой структуру с тремя полями: 1. строка длиной 10 символов или меньше, имя «имя», 2. 32-битное целое число, имя «возраст», и 3. 32-битное число с плавающей точкой, имя «вес».

Если вы индексируете x в позиции 1, вы получите структуру:

>>> x[1]
('Fido', 3, 27.0)

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

>>> x['age']
array([9, 3], dtype=int32)
>>> x['age'] = 5
>>> x
array([('Rex', 5, 81.), ('Fido', 5, 27.)],
      dtype=[('name', 'U10'), ('age', '<i4'), ('weight', '<f4')])

Структурированные типы данных предназначены для имитации «структур» языка C и имеют аналогичную структуру памяти. Они предназначены для взаимодействия с кодом C и для низкоуровневой обработки структурированных буферов, например, для интерпретации двоичных блоков. Для этих целей они поддерживают специализированные функции, такие как подмассивы, вложенные типы данных и объединения, и позволяют контролировать структуру памяти структуры.

Пользователи, желающие обрабатывать табличные данные, такие как данные в файлах csv, могут найти более подходящие проекты pydata, такие как xarray, pandas или DataArray. Они предоставляют высокоуровневый интерфейс для анализа табличных данных и лучше оптимизированы для этого использования. Например, структура памяти, похожая на C-структуру, структурированных массивов в numpy, может привести к плохой работе кэша по сравнению с другими.

Структурированные типы данных

Структурированный тип данных можно рассматривать как последовательность байтов определенной длины (размер элемента структуры itemsize), которая интерпретируется как набор полей. Каждое поле имеет имя, тип данных и смещение в байтах внутри структуры. Тип данных поля может быть любым типом данных numpy, включая другие структурированные типы данных, а также может быть типом данных подмассива, который ведет себя как ndarray заданной формы. Смещения полей произвольны, и поля могут даже перекрываться. Эти смещения обычно определяются автоматически numpy, но также могут быть заданы.

Создание структурированных типов данных

Структурированные типы данных можно создавать с помощью функции numpy.dtype. Существует 4 альтернативных формы спецификации, которые различаются по гибкости и лаконичности. Более подробная информация приведена в справочной странице по Объектам типа данных, и в кратком виде они следующие:

1. Список кортежей, по одному кортежу на поле

   Каждый кортеж имеет вид (fieldname, datatype, shape) , где форма необязательна. fieldname — это строка (или кортеж, если используются заголовки, см. Заголовки полей ниже), datatype может быть любым объектом, преобразуемым в тип данных, и shape — это кортеж целых чисел, определяющий форму подмассива.

   >>> np.dtype([('x', 'f4'), ('y', np.float32), ('z', 'f4', (2, 2))])
   dtype([('x', '<f4'), ('y', '<f4'), ('z', '<f4', (2, 2))])
   

   Если fieldname — это пустая строка '', полю будет присвоено имя по умолчанию вида f#, где # — целочисленный индекс поля, считая с 0 слева:

   >>> np.dtype([('x', 'f4'), ('', 'i4'), ('z', 'i8')])
   dtype([('x', '<f4'), ('f1', '<i4'), ('z', '<i8')])
   

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

2. Строка со спецификациями типов данных, разделенных запятыми

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

   >>> np.dtype('i8, f4, S3')
   dtype([('f0', '<i8'), ('f1', '<f4'), ('f2', 'S3')])
   >>> np.dtype('3int8, float32, (2, 3)float64')
   dtype([('f0', 'i1', (3,)), ('f1', '<f4'), ('f2', '<f8', (2, 3))])
   

3. Словарь массивов параметров поля

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

   Словарь содержит два обязательных ключа, «имена» и «форматы», и четыре необязательных ключа, «смещения», «размер_элемента», «выровненные» и «заголовки». Значения для «имен» и «форматов» должны соответственно быть списком имён полей и списком спецификаций типов данных, имеющих одинаковую длину. Необязательное значение «смещения» должно быть списком целочисленных смещений в байтах, по одному для каждого поля в структуре. Если «смещения» не указаны, смещения определяются автоматически. Необязательное значение «размер_элемента» должно быть целым числом, описывающим общий размер в байтах типа данных, который должен быть достаточно большим, чтобы содержать все поля.

   >>> np.dtype({'names': ['col1', 'col2'], 'formats': ['i4', 'f4']})
   dtype([('col1', '<i4'), ('col2', '<f4')])
   >>> np.dtype({'names': ['col1', 'col2'],
   ...           'formats': ['i4', 'f4'],
   ...           'offsets': [0, 4],
   ...           'itemsize': 12})
   dtype({'names':['col1','col2'], 'formats':['<i4','<f4'], 'offsets':[0,4], 'itemsize':12})
   

   Смещения могут быть выбраны таким образом, чтобы поля перекрывались, хотя это означает, что присваивание одному полю может перезаписать данные любого перекрывающегося поля. В качестве исключения, поля типа numpy.object_ не могут перекрываться с другими полями из-за риска перезаписи указателя внутреннего объекта, а затем его обращение к нему.

   Необязательное значение «выровненные» может быть установлено в True , чтобы автоматическое вычисление смещений использовало выровненные смещения (см. Автоматические байтовые смещения и выравнивание), как будто параметр «выравнивание» в numpy.dtype был установлен в True.

   Необязательное значение «заголовки» должно быть списком заголовков той же длины, что и «имена», см. Заголовки полей ниже.

4. Словарь имён полей

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

   >>> np.dtype({'col1': ('i1', 0), 'col2': ('f4', 1)})
   dtype([('col1', 'i1'), ('col2', '<f4')])
   

   Эта форма не рекомендуется, так как словари Python не сохраняют порядок в версиях Python до Python 3.6, а порядок полей в структурированном типе данных имеет значение. Заголовки полей могут быть указаны, используя 3-кортеж, см. ниже.

Обработка и отображение структурированных типов данных

Список имён полей структурированного типа данных можно найти в атрибуте names объекта типа данных:

>>> d = np.dtype([('x', 'i8'), ('y', 'f4')])
>>> d.names
('x', 'y')

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

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

>>> d.fields
mappingproxy({'x': (dtype('int64'), 0), 'y': (dtype('float32'), 8)})

И атрибут names, и атрибут fields будут равны None для неструктурированных массивов. Рекомендуемый способ проверить, является ли тип данных структурированным, — это использовать if dt.names is not None вместо if dt.names, чтобы учесть типы данных с 0 полями.

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

Автоматические байтовые смещения и выравнивание

Numpy использует один из двух методов для автоматического определения смещений байтов поля и общего размера элемента структурированного типа данных, в зависимости от того, был ли задан параметр align=True в качестве ключевого аргумента к numpy.dtype.

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

>>> def print_offsets(d):
...     print("offsets:", [d.fields[name][1] for name in d.names])
...     print("itemsize:", d.itemsize)
>>> print_offsets(np.dtype('u1, u1, i4, u1, i8, u2'))
offsets: [0, 1, 2, 6, 7, 15]
itemsize: 17

Если align=True задано, numpy будет дополнять структуру так же, как многие компиляторы C дополняют C-структуру. Выровненные структуры могут улучшить производительность в некоторых случаях за счёт увеличения размера типа данных. Дополнительные байты вставляются между полями так, чтобы смещение байтов каждого поля было кратно выравниванию этого поля, которое обычно равно размеру поля в байтах для простых типов данных, см. PyArray_Descr.alignment. К структуре также будет добавлен дополнительный байт-заполнитель, таким образом, чтобы её размер элемента был кратен наибольшему выравниванию поля.

>>> print_offsets(np.dtype('u1, u1, i4, u1, i8, u2', align=True))
offsets: [0, 1, 4, 8, 16, 24]
itemsize: 32

Обратите внимание, что хотя почти все современные компиляторы C дополняют таким образом по умолчанию, дополнение в C-структурах зависит от реализации компилятора C, поэтому такая структура памяти не гарантируется, что будет точно соответствовать структуре соответствующей программы на языке C. Необходимо выполнить определённую работу, либо со стороны numpy, либо со стороны C, чтобы получить точное соответствие.

Если смещения полей и размер элемента структурированного массива удовлетворяют условиям выравнивания, массив будет иметь атрибут ALIGNED flag установленным.

Удобная функция numpy.lib.recfunctions.repack_fields преобразует выровненный тип данных или массив в упакованный и наоборот. Она принимает в качестве аргумента либо тип данных, либо структурированный ndarray, и возвращает копию с переупакованными полями, с или без дополнительных байтов.

Заголовки полей

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

Чтобы добавить заголовки при использовании формы спецификации типа данных «список кортежей», имя поля может быть указано как кортеж из двух строк вместо одной строки, которая будет заголовком поля и именем поля соответственно. Например:

>>> np.dtype([(('my title', 'name'), 'f4')])
dtype([(('my title', 'name'), '<f4')])

При использовании первого варианта спецификации на основе словаря, заголовки могут быть предоставлены как дополнительный 'titles' ключ, как описано выше. При использовании второго (не рекомендуемого) варианта спецификации на основе словаря заголовок можно указать, предоставив кортеж из 3 элементов (datatype, offset, title) вместо обычного кортежа из 2 элементов:

>>> np.dtype({'name': ('i4', 0, 'my title')})
dtype([(('my title', 'name'), '<i4')])

Словарь dtype.fields будет содержать заголовки в качестве ключей, если такие заголовки используются. Это означает, что поле с заголовком будет представлено дважды в словаре полей. Значения кортежа для этих полей также будут иметь третий элемент — заголовок поля. Из-за этого, и потому что атрибут names сохраняет порядок полей, в то время как атрибут fields может этого не делать, рекомендуется итерировать по полям dtype с помощью атрибута names dtype, который не будет перечислять заголовки, как в примере:

>>> for name in d.names:
...     print(d.fields[name][:2])
(dtype('int64'), 0)
(dtype('float32'), 8)

Типы объединения

Структурированные типы данных реализованы в numpy с базовым типом numpy.void по умолчанию, но возможно интерпретировать другие типы numpy как структурированные типы, используя форму спецификации dtype (base_dtype, dtype) описанную в Объекты типов данных. Здесь base_dtype — желаемый базовый тип данных, а поля и флаги будут скопированы из dtype. Этот тип данных аналогичен типу ‘union’ в C.

Индексирование и присваивание структурированным массивам

Присваивание данных структурированному массиву

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

Присваивание из типов Python (кортежи)

Простейший способ присваивания значений структурированному массиву — использование кортежей Python. Каждое присваиваемое значение должно быть кортежем длиной, равной количеству полей в массиве, а не списком или массивом, так как это может привести к применению правил векторизации numpy. Элементы кортежа присваиваются последовательным полям массива слева направо:

>>> x = np.array([(1, 2, 3), (4, 5, 6)], dtype='i8, f4, f8')
>>> x[1] = (7, 8, 9)
>>> x
array([(1, 2., 3.), (7, 8., 9.)],
     dtype=[('f0', '<i8'), ('f1', '<f4'), ('f2', '<f8')])

Присваивание из скаляров

Скаляр, присвоенный структурированному элементу, будет присвоен всем полям. Это происходит, когда скаляр присваивается структурированному массиву или когда неструктурированный массив присваивается структурированному массиву:

>>> x = np.zeros(2, dtype='i8, f4, ?, S1')
>>> x[:] = 3
>>> x
array([(3, 3., True, b'3'), (3, 3., True, b'3')],
      dtype=[('f0', '<i8'), ('f1', '<f4'), ('f2', '?'), ('f3', 'S1')])
>>> x[:] = np.arange(2)
>>> x
array([(0, 0., False, b'0'), (1, 1., True, b'1')],
      dtype=[('f0', '<i8'), ('f1', '<f4'), ('f2', '?'), ('f3', 'S1')])

Структурированные массивы также могут быть присвоены неструктурированным массивам, но только если структурированный тип данных имеет только одно поле:

>>> twofield = np.zeros(2, dtype=[('A', 'i4'), ('B', 'i4')])
>>> onefield = np.zeros(2, dtype=[('A', 'i4')])
>>> nostruct = np.zeros(2, dtype='i4')
>>> nostruct[:] = twofield
Traceback (most recent call last):
...
TypeError: Cannot cast array data from dtype([('A', '<i4'), ('B', '<i4')]) to dtype('int32') according to the rule 'unsafe'

Присваивание из других структурированных массивов

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

>>> a = np.zeros(3, dtype=[('a', 'i8'), ('b', 'f4'), ('c', 'S3')])
>>> b = np.ones(3, dtype=[('x', 'f4'), ('y', 'S3'), ('z', 'O')])
>>> b[:] = a
>>> b
array([(0., b'0.0', b''), (0., b'0.0', b''), (0., b'0.0', b'')],
      dtype=[('x', '<f4'), ('y', 'S3'), ('z', 'O')])

Присваивание, включающее подмассивы

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

Индексирование структурированных массивов

Доступ к отдельным полям

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

>>> x = np.array([(1, 2), (3, 4)], dtype=[('foo', 'i8'), ('bar', 'f4')])
>>> x['foo']
array([1, 3])
>>> x['foo'] = 10
>>> x
array([(10, 2.), (10, 4.)],
      dtype=[('foo', '<i8'), ('bar', '<f4')])

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

>>> y = x['bar']
>>> y[:] = 11
>>> x
array([(10, 11.), (10, 11.)],
      dtype=[('foo', '<i8'), ('bar', '<f4')])

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

>>> y.dtype, y.shape, y.strides
(dtype('float32'), (2,), (12,))

Если доступное поле является подмассивом, размерности подмассива добавляются к форме результата:

>>> x = np.zeros((2, 2), dtype=[('a', np.int32), ('b', np.float64, (3, 3))])
>>> x['a'].shape
(2, 2)
>>> x['b'].shape
(2, 2, 3, 3)

Доступ к нескольким полям

Можно индексировать и присваивать структурированному массиву с индексом из нескольких полей, где индекс — список имён полей.

Результат индексирования с помощью многопольного индекса — представление исходного массива, как следует:

>>> a = np.zeros(3, dtype=[('a', 'i4'), ('b', 'i4'), ('c', 'f4')])
>>> a[['a', 'c']]
array([(0, 0.), (0, 0.), (0, 0.)],
     dtype={'names':['a','c'], 'formats':['<i4','<f4'], 'offsets':[0,8], 'itemsize':12})

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

>>> a[['a', 'c']].view('i8')  # Fails in Numpy 1.16
Traceback (most recent call last):
   File "<stdin>", line 1, in <module>
ValueError: When changing to a smaller dtype, its size must be a divisor of the size of original dtype

>>> from numpy.lib.recfunctions import repack_fields
>>> repack_fields(a[['a', 'c']]).view('i8')  # supported in 1.16
array([0, 0, 0])

>>> b = np.zeros(3, dtype=[('x', 'f4'), ('y', 'f4'), ('z', 'f4')])
>>> b[['x', 'z']].view('f4')
array([0., 0., 0., 0., 0., 0., 0., 0., 0.], dtype=float32)

>>> from numpy.lib.recfunctions import structured_to_unstructured
>>> structured_to_unstructured(b[['x', 'z']])
array([0, 0, 0])

Присваивание массиву с многопольным индексом изменяет исходный массив:

>>> a[['a', 'c']] = (2, 3)
>>> a
array([(2, 0, 3.), (2, 0, 3.), (2, 0, 3.)],
      dtype=[('a', '<i4'), ('b', '<i4'), ('c', '<f4')])

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

>>> a[['a', 'c']] = a[['c', 'a']]

Индексирование целым числом для получения структурированного скаляра

Индексирование одного элемента структурированного массива (с целочисленным индексом) возвращает структурированный скаляр:

>>> x = np.array([(1, 2., 3.)], dtype='i, f, f')
>>> scalar = x[0]
>>> scalar
(1, 2., 3.)
>>> type(scalar)
<class 'numpy.void'>

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

>>> x = np.array([(1, 2), (3, 4)], dtype=[('foo', 'i8'), ('bar', 'f4')])
>>> s = x[0]
>>> s['bar'] = 100
>>> x
array([(1, 100.), (3, 4.)],
      dtype=[('foo', '<i8'), ('bar', '<f4')])

Аналогично кортежам, структурированные скаляры также можно индексировать целым числом:

>>> scalar = np.array([(1, 2., 3.)], dtype='i, f, f')[0]
>>> scalar[0]
1
>>> scalar[1] = 4

Таким образом, кортежи можно рассматривать как родственный Python эквивалент структурированных типов numpy, так же как родственные Python целые числа являются эквивалентом целых типов numpy. Структурированные скаляры можно преобразовать в кортеж, вызвав numpy.ndarray.item:

>>> scalar.item(), type(scalar.item())
((1, 4.0, 3.0), <class 'tuple'>)

Представление структурированных массивов, содержащих объекты

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

Сравнение структур

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

>>> a = np.zeros(2, dtype=[('a', 'i4'), ('b', 'i4')])
>>> b = np.ones(2, dtype=[('a', 'i4'), ('b', 'i4')])
>>> a == b
array([False, False])

В настоящее время, если dtypes двух структурированных массивов void не эквивалентны, сравнение терпит неудачу, возвращая скалярное значение False. Это поведение устарело начиная с numpy 1.10 и в будущем будет приводить к ошибке или выполнению поэлементного сравнения.

Операторы < и > всегда возвращают False при сравнении структурированных массивов void, и арифметические и побитовые операции не поддерживаются.

Записи массивов

В качестве дополнительного удобства numpy предоставляет подкласс ndarray, numpy.recarray, который позволяет получить доступ к полям структурированных массивов по атрибуту вместо только по индексу. Массивы записей используют специальный тип данных, numpy.record, который позволяет получить доступ к полям по атрибуту для структурированных скаляров, полученных из массива. Модуль numpy.rec предоставляет функции для создания recarrays из различных объектов. Дополнительные вспомогательные функции для создания и обработки структурированных массивов можно найти в numpy.lib.recfunctions.

Самый простой способ создать массив записей — это с помощью numpy.rec.array:

>>> recordarr = np.rec.array([(1, 2., 'Hello'), (2, 3., "World")],
...                    dtype=[('foo', 'i4'),('bar', 'f4'), ('baz', 'S10')])
>>> recordarr.bar
array([ 2.,  3.], dtype=float32)
>>> recordarr[1:2]
rec.array([(2, 3., b'World')],
      dtype=[('foo', '<i4'), ('bar', '<f4'), ('baz', 'S10')])
>>> recordarr[1:2].foo
array([2], dtype=int32)
>>> recordarr.foo[1:2]
array([2], dtype=int32)
>>> recordarr[1].baz
b'World'

numpy.rec.array может преобразовать широкий спектр аргументов в массивы записей, включая структурированные массивы:

>>> arr = np.array([(1, 2., 'Hello'), (2, 3., "World")],
...             dtype=[('foo', 'i4'), ('bar', 'f4'), ('baz', 'S10')])
>>> recordarr = np.rec.array(arr)

Модуль numpy.rec предоставляет ряд других удобных функций для создания массивов записей, см. процедуры создания массивов записей.

Представление структурированного массива в виде массива записей можно получить, используя соответствующий вид:

>>> arr = np.array([(1, 2., 'Hello'), (2, 3., "World")],
...                dtype=[('foo', 'i4'),('bar', 'f4'), ('baz', 'a10')])
>>> recordarr = arr.view(dtype=np.dtype((np.record, arr.dtype)),
...                      type=np.recarray)

Для удобства, представление ndarray как типа numpy.recarray автоматически преобразуется в тип numpy.record, поэтому тип данных можно опустить из представления:

>>> recordarr = arr.view(np.recarray)
>>> recordarr.dtype
dtype((numpy.record, [('foo', '<i4'), ('bar', '<f4'), ('baz', 'S10')]))

Чтобы вернуться к обычному ndarray, необходимо сбросить и тип данных, и тип. Следующее представление это делает, учитывая необычный случай, когда recordarr не был структурированным типом:

>>> arr2 = recordarr.view(recordarr.dtype.fields or recordarr.dtype, np.ndarray)

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

>>> recordarr = np.rec.array([('Hello', (1, 2)), ("World", (3, 4))],
...                 dtype=[('foo', 'S6'),('bar', [('A', int), ('B', int)])])
>>> type(recordarr.foo)
<class 'numpy.ndarray'>
>>> type(recordarr.bar)
<class 'numpy.recarray'>

Обратите внимание, что если поле имеет такое же имя, как атрибут ndarray, атрибут ndarray имеет приоритет. Такие поля недоступны по атрибуту, но по-прежнему доступны по индексу.

Вспомогательные функции Recarray

Коллекция утилит для работы со структурированными массивами.

Большинство из этих функций были первоначально реализованы Джоном Хантером для matplotlib. Они были переписаны и расширены для удобства.

numpy.lib.recfunctions.append_fields(base, names, data, dtypes=None, fill_value=-1, usemask=True, asrecarray=False) [source]

Добавление новых полей к существующему массиву.

Имена полей задаются с помощью аргументов names, соответствующие значения с помощью аргументов data. Если добавляется одно поле, names, data и dtypes не должны быть списками, а только значениями.

Параметры

basearray

Входной массив для расширения.

namesstring, sequence

Строка или последовательность строк, соответствующие именам новых полей.

dataarray or sequence of arrays

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

dtypessequence of datatypes, optional

Тип данных или последовательность типов данных. Если None, типы данных оцениваются из data.

fill_value{float}, optional

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

usemask{False, True}, optional

Определяет, возвращать ли массив с маской.

asrecarray{False, True}, optional

Определяет, возвращать ли recarray (MaskedRecords) или нет.

numpy.lib.recfunctions.apply_along_fields(func, arr) [source]

Применение функции ‘func’ как редукции по полям структурированного массива.

Это аналогично apply_along_axis, но обрабатывает поля структурированного массива как дополнительную ось. Поля сначала преобразуются в общий тип, следуя правилам повышения типа из numpy.result_type, применяемым к типам данных полей.

Параметры

funcfunction

Функция для применения к размерности «поле». Эта функция должна поддерживать аргумент axis, например, np.mean, np.sum и т.д.

arrndarray

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

Возвращает

outndarray

Результат операции редукции

Примеры

>>> from numpy.lib import recfunctions as rfn
>>> b = np.array([(1, 2, 5), (4, 5, 7), (7, 8 ,11), (10, 11, 12)],
...              dtype=[('x', 'i4'), ('y', 'f4'), ('z', 'f8')])
>>> rfn.apply_along_fields(np.mean, b)
array([ 2.66666667,  5.33333333,  8.66666667, 11.        ])
>>> rfn.apply_along_fields(np.mean, b[['x', 'z']])
array([ 3. ,  5.5,  9. , 11. ])

numpy.lib.recfunctions.assign_fields_by_name(dst, src, zero_unassigned=True) [source]

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

Обычно в numpy >= 1.14 присвоение одного структурированного массива другому копирует поля «по позиции», что означает, что первое поле из src копируется в первое поле dst, и так далее, независимо от имени поля.

Эта функция вместо этого копирует «по имени поля», таким образом, поля в dst присваиваются из поля с таким же именем в src. Это то, как работало присвоение структуры в numpy >= 1.6 и <= 1.13.

Параметры

dstndarray

srcndarray

Исходный и целевой массивы во время присвоения.

zero_unassignedbool, optional

Если True, поля в dst, для которых не было соответствующего поля в src, заполняются значением 0 (ноль). Это было поведение numpy <= 1.13. Если False, эти поля не изменяются.

numpy.lib.recfunctions.drop_fields(base, drop_names, usemask=True, asrecarray=False) [source]

Возвращает новый массив с удаленными полями из drop_names.

Поддерживаются вложенные поля.

Изменено в версии 1.18.0: drop_fields возвращает массив с 0 полями, если все поля удалены, а не None как это было раньше.

Параметры

basearray

Входной массив

drop_namesstring or sequence

Строка или последовательность строк, соответствующие именам полей для удаления.

usemask{False, True}, optional

Определяет, возвращать ли массив с маской.

asrecarraystring or sequence, optional

Определяет, возвращать ли recarray или mrecarray (asrecarray=True) или обычный ndarray или массив с маской и гибким типом данных. По умолчанию False.

Примеры

>>> from numpy.lib import recfunctions as rfn
>>> a = np.array([(1, (2, 3.0)), (4, (5, 6.0))],
...   dtype=[('a', np.int64), ('b', [('ba', np.double), ('bb', np.int64)])])
>>> rfn.drop_fields(a, 'a')
array([((2., 3),), ((5., 6),)],
      dtype=[('b', [('ba', '<f8'), ('bb', '<i8')])])
>>> rfn.drop_fields(a, 'ba')
array([(1, (3,)), (4, (6,))], dtype=[('a', '<i8'), ('b', [('bb', '<i8')])])
>>> rfn.drop_fields(a, ['ba', 'bb'])
array([(1,), (4,)], dtype=[('a', '<i8')])

numpy.lib.recfunctions.find_duplicates(a, key=None, ignoremask=True, return_index=False) [source]

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

Параметры

aarray-like

Входной массив

key{string, None}, optional

Имя полей, по которым проверять дубликаты. Если None, поиск выполняется по записям

ignoremask{True, False}, optional

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

return_index{False, True}, optional

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

Примеры

>>> from numpy.lib import recfunctions as rfn
>>> ndtype = [('a', int)]
>>> a = np.ma.array([1, 1, 1, 2, 2, 3, 3],
...         mask=[0, 0, 1, 0, 0, 0, 1]).view(ndtype)
>>> rfn.find_duplicates(a, ignoremask=True, return_index=True)
(masked_array(data=[(1,), (1,), (2,), (2,)],
             mask=[(False,), (False,), (False,), (False,)],
       fill_value=(999999,),
            dtype=[('a', '<i8')]), array([0, 1, 3, 4]))

numpy.lib.recfunctions.flatten_descr(ndtype) [source]

Разворачивание описания структурированного типа данных.

Примеры

>>> from numpy.lib import recfunctions as rfn
>>> ndtype = np.dtype([('a', '<i4'), ('b', [('ba', '<f8'), ('bb', '<i4')])])
>>> rfn.flatten_descr(ndtype)
(('a', dtype('int32')), ('ba', dtype('float64')), ('bb', dtype('int32')))

numpy.lib.recfunctions.get_fieldstructure(adtype, lastname=None, parents=None) [source]

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

Эта функция используется для упрощения доступа к вложенным полям в других полях.

Параметры

adtypenp.dtype

Входной тип данных

lastnameoptional

Имя последнего обработанного поля (используется во время рекурсии).

parentsdictionary

Словарь родительских полей (используется во время рекурсии).

Примеры

>>> from numpy.lib import recfunctions as rfn
>>> ndtype =  np.dtype([('A', int),
...                     ('B', [('BA', int),
...                            ('BB', [('BBA', int), ('BBB', int)])])])
>>> rfn.get_fieldstructure(ndtype)
... # XXX: possible regression, order of BBA and BBB is swapped
{'A': [], 'B': [], 'BA': ['B'], 'BB': ['B'], 'BBA': ['B', 'BB'], 'BBB': ['B', 'BB']}

numpy.lib.recfunctions.get_names(adtype) [source]

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

Параметры

adtypedtype

Входной тип данных

Примеры

>>> from numpy.lib import recfunctions as rfn
>>> rfn.get_names(np.empty((1,), dtype=int))
Traceback (most recent call last):
    ...
AttributeError: 'numpy.ndarray' object has no attribute 'names'

>>> rfn.get_names(np.empty((1,), dtype=[('A',int), ('B', float)]))
Traceback (most recent call last):
    ...
AttributeError: 'numpy.ndarray' object has no attribute 'names'
>>> adtype = np.dtype([('a', int), ('b', [('ba', int), ('bb', int)])])
>>> rfn.get_names(adtype)
('a', ('b', ('ba', 'bb')))

numpy.lib.recfunctions.get_names_flat(adtype) [source]

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

Параметры

adtypedtype

Входной тип данных

Примеры

>>> from numpy.lib import recfunctions as rfn
>>> rfn.get_names_flat(np.empty((1,), dtype=int)) is None
Traceback (most recent call last):
    ...
AttributeError: 'numpy.ndarray' object has no attribute 'names'
>>> rfn.get_names_flat(np.empty((1,), dtype=[('A',int), ('B', float)]))
Traceback (most recent call last):
    ...
AttributeError: 'numpy.ndarray' object has no attribute 'names'
>>> adtype = np.dtype([('a', int), ('b', [('ba', int), ('bb', int)])])
>>> rfn.get_names_flat(adtype)
('a', 'b', 'ba', 'bb')

numpy.lib.recfunctions.join_by(key, r1, r2, jointype='inner', r1postfix='1', r2postfix='2', defaults=None, usemask=True, asrecarray=False) [source]

Объединяет массивы r1 и r2 по ключу key.

Ключ должен быть либо строкой, либо последовательностью строк, соответствующих полям, используемым для объединения массива. Если поле key не найдено в двух входных массивах, возникает исключение. Ни r1, ни r2 не должны содержать дубликатов по key: наличие дубликатов сделает вывод довольно ненадежным. Обратите внимание, что дубликаты алгоритмом не проверяются.

Параметры

key{string, sequence}

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

r1, r2arrays

Структурированные массивы.

jointype{‘inner’, ‘outer’, ‘leftouter’}, optional

Если ‘inner’, возвращает элементы, общие для обоих r1 и r2. Если ‘outer’, возвращает общие элементы, а также элементы r1, отсутствующие в r2, и элементы r2, отсутствующие в r1. Если ‘leftouter’, возвращает общие элементы и элементы r1, отсутствующие в r2.

r1postfixstring, optional

Строка, добавляемая к именам полей r1, которые присутствуют в r2, но отсутствуют в ключе.

r2postfixstring, optional

Строка, добавляемая к именам полей r2, которые присутствуют в r1, но отсутствуют в ключе.

defaults{dictionary}, optional

Словарь, сопоставляющий имена полей соответствующим значениям по умолчанию.

usemask{True, False}, optional

Возвращать ли массив MaskedArray (или MaskedRecords, если asrecarray==True) или ndarray.

asrecarray{False, True}, optional

Возвращать ли recarray (или MaskedRecords, если usemask==True) или просто массив гибкого типа.

Примечания

• Вывод сортируется по ключу.
• Образуется временный массив, из которого отброшены поля, не входящие в ключ для двух массивов, а результат конкатенируется. Затем этот массив сортируется, и выбираются общие элементы. Вывод создается путем заполнения полей выбранными элементами. Соответствие не сохраняется, если есть дубликаты…

numpy.lib.recfunctions.merge_arrays(seqarrays, fill_value=-1, flatten=False, usemask=False, asrecarray=False) [source]

Объединение массивов поле за полем.

Параметры

seqarrayssequence of ndarrays

Последовательность массивов

fill_value{float}, optional

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

flatten{False, True}, optional

Сжать вложенные поля.

usemask{False, True}, optional

Возвращать ли массив masked или нет.

asrecarray{False, True}, optional

Возвращать ли recarray (MaskedRecords) или нет.

Примечания

• Без маски пропущенное значение будет заполнено чем-то, в зависимости от его типа:

  • -1 для целых чисел
  • -1.0 для чисел с плавающей точкой
  • '-' для символов
  • '-1' для строк
  • True для логических значений
• XXX: Эти значения были получены эмпирически

Примеры

>>> from numpy.lib import recfunctions as rfn
>>> rfn.merge_arrays((np.array([1, 2]), np.array([10., 20., 30.])))
array([( 1, 10.), ( 2, 20.), (-1, 30.)],
      dtype=[('f0', '<i8'), ('f1', '<f8')])

>>> rfn.merge_arrays((np.array([1, 2], dtype=np.int64),
...         np.array([10., 20., 30.])), usemask=False)
 array([(1, 10.0), (2, 20.0), (-1, 30.0)],
         dtype=[('f0', '<i8'), ('f1', '<f8')])
>>> rfn.merge_arrays((np.array([1, 2]).view([('a', np.int64)]),
...               np.array([10., 20., 30.])),
...              usemask=False, asrecarray=True)
rec.array([( 1, 10.), ( 2, 20.), (-1, 30.)],
          dtype=[('a', '<i8'), ('f1', '<f8')])

numpy.lib.recfunctions.rec_append_fields(base, names, data, dtypes=None) [source]

Добавление новых полей в существующий массив.

Имена полей задаются с помощью аргументов names, соответствующие значения - с помощью аргументов data. Если добавляется одно поле, names, data и dtypes не должны быть списками, а просто значениями.

Параметры

basearray

Входной массив для расширения.

namesstring, sequence

Строка или последовательность строк, соответствующие именам новых полей.

dataarray or sequence of arrays

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

dtypessequence of datatypes, optional

Тип данных или последовательность типов данных. Если None, типы данных оцениваются по data.

Возвращает

appended_arraynp.recarray

См. также

append_fields

numpy.lib.recfunctions.rec_drop_fields(base, drop_names) [source]

Возвращает новый numpy.recarray с полями из drop_names удалены.

numpy.lib.recfunctions.rec_join(key, r1, r2, jointype='inner', r1postfix='1', r2postfix='2', defaults=None) [source]

Объединяет массивы r1 и r2 по ключам. Альтернатива join_by, которая всегда возвращает np.recarray.

См. также

join_by

эквивалентная функция

numpy.lib.recfunctions.recursive_fill_fields(input, output) [source]

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

Параметры

inputndarray

Входной массив.

outputndarray

Массив вывода.

Примечания

• output должен быть по крайней мере того же размера, что и input

Примеры

>>> from numpy.lib import recfunctions as rfn
>>> a = np.array([(1, 10.), (2, 20.)], dtype=[('A', np.int64), ('B', np.float64)])
>>> b = np.zeros((3,), dtype=a.dtype)
>>> rfn.recursive_fill_fields(a, b)
array([(1, 10.), (2, 20.), (0,  0.)], dtype=[('A', '<i8'), ('B', '<f8')])

numpy.lib.recfunctions.rename_fields(base, namemapper) [source]

Переименование полей из массива гибкого типа ndarray или recarray.

Поддерживаются вложенные поля.

Параметры

basendarray

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

namemapperdictionary

Словарь, сопоставляющий старые имена полей новым.

Примеры

>>> from numpy.lib import recfunctions as rfn
>>> a = np.array([(1, (2, [3.0, 30.])), (4, (5, [6.0, 60.]))],
...   dtype=[('a', int),('b', [('ba', float), ('bb', (float, 2))])])
>>> rfn.rename_fields(a, {'a':'A', 'bb':'BB'})
array([(1, (2., [ 3., 30.])), (4, (5., [ 6., 60.]))],
      dtype=[('A', '<i8'), ('b', [('ba', '<f8'), ('BB', '<f8', (2,))])])

numpy.lib.recfunctions.repack_fields(a, align=False, recurse=False) [source]

Переупаковка полей структурированного массива или типа данных в памяти.

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

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

Если align=False, этот метод создает «упакованный» макет памяти, в котором каждое поле начинается с байта, на котором закончилось предыдущее поле, и все байты заполнения удаляются.

Если align=True, этот метод создаёт «выровненную» структуру памяти, в которой смещение каждого поля является кратным его выравниванию, а общий размер элемента — кратен максимальному выравниванию, добавляя по мере необходимости байты заполнения.

Параметры

andarray or dtype

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

alignboolean

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

recurseboolean

Если True, также переупаковываются вложенные структуры.

Возвращает

repackedndarray or dtype

Копия a с переупакованными полями или сам a, если переупаковка не была необходима.

Примеры

>>> from numpy.lib import recfunctions as rfn
>>> def print_offsets(d):
...     print("offsets:", [d.fields[name][1] for name in d.names])
...     print("itemsize:", d.itemsize)
...
>>> dt = np.dtype('u1, <i8, <f8', align=True)
>>> dt
dtype({'names':['f0','f1','f2'], 'formats':['u1','<i8','<f8'], 'offsets':[0,8,16], 'itemsize':24}, align=True)
>>> print_offsets(dt)
offsets: [0, 8, 16]
itemsize: 24
>>> packed_dt = rfn.repack_fields(dt)
>>> packed_dt
dtype([('f0', 'u1'), ('f1', '<i8'), ('f2', '<f8')])
>>> print_offsets(packed_dt)
offsets: [0, 1, 9]
itemsize: 17

numpy.lib.recfunctions.require_fields(array, required_dtype) [source]

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

Эта функция выполняет присваивание из старого массива в новый по имени, поэтому значение поля в выходном массиве равно значению поля с тем же именем во входном массиве. Это приводит к созданию нового массива ndarray, содержащего только поля, «требуемые» параметром required_dtype.

Если имя поля в required_dtype отсутствует во входном массиве, это поле создается и устанавливается в 0 в выходном массиве.

Параметры

andarray

массив для преобразования

required_dtypedtype

тип данных для выходного массива

Возвращает

outndarray

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

Примеры

>>> from numpy.lib import recfunctions as rfn
>>> a = np.ones(4, dtype=[('a', 'i4'), ('b', 'f8'), ('c', 'u1')])
>>> rfn.require_fields(a, [('b', 'f4'), ('c', 'u1')])
array([(1., 1), (1., 1), (1., 1), (1., 1)],
  dtype=[('b', '<f4'), ('c', 'u1')])
>>> rfn.require_fields(a, [('b', 'f4'), ('newf', 'u1')])
array([(1., 0), (1., 0), (1., 0), (1., 0)],
  dtype=[('b', '<f4'), ('newf', 'u1')])

numpy.lib.recfunctions.stack_arrays(arrays, defaults=None, usemask=True, asrecarray=False, autoconvert=False) [source]

Наложение массивов поле за полем

Параметры

arraysarray or sequence

Последовательность входных массивов.

defaultsdictionary, optional

Словарь, сопоставляющий имена полей с соответствующими значениями по умолчанию.

usemask{True, False}, optional

Возвращать ли MaskedArray (или MaskedRecords, если asrecarray==True) или ndarray.

asrecarray{False, True}, optional

Возвращать ли recarray (или MaskedRecords, если usemask==True) или просто массив гибкого типа.

autoconvert{False, True}, optional

Автоматически ли приводить тип поля к максимальному.

Примеры

>>> from numpy.lib import recfunctions as rfn
>>> x = np.array([1, 2,])
>>> rfn.stack_arrays(x) is x
True
>>> z = np.array([('A', 1), ('B', 2)], dtype=[('A', '|S3'), ('B', float)])
>>> zz = np.array([('a', 10., 100.), ('b', 20., 200.), ('c', 30., 300.)],
...   dtype=[('A', '|S3'), ('B', np.double), ('C', np.double)])
>>> test = rfn.stack_arrays((z,zz))
>>> test
masked_array(data=[(b'A', 1.0, --), (b'B', 2.0, --), (b'a', 10.0, 100.0),
                   (b'b', 20.0, 200.0), (b'c', 30.0, 300.0)],
             mask=[(False, False,  True), (False, False,  True),
                   (False, False, False), (False, False, False),
                   (False, False, False)],
       fill_value=(b'N/A', 1.e+20, 1.e+20),
            dtype=[('A', 'S3'), ('B', '<f8'), ('C', '<f8')])

numpy.lib.recfunctions.structured_to_unstructured(arr, dtype=None, copy=False, casting='unsafe') [source]

Преобразование n-мерного структурированного массива в (n+1)-мерный неструктурированный массив.

Новый массив будет иметь новую последнюю размерность, равную числу элементов поля входного массива. Если не указано, тип данных результата определяется правилами повышения типа NumPy, применяемыми ко всем типам данных полей.

Вложенные поля, а также каждый элемент любых полей подмассивов считаются отдельными элементами поля.

Параметры

arrndarray

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

dtypedtype, optional

Тип данных выходного неструктурированного массива.

copybool, optional

См. аргумент copy в ndarray.astype. Если True, всегда возвращается копия. Если False, и dtype требования выполнены, возвращается представление.

casting{‘no’, ‘equiv’, ‘safe’, ‘same_kind’, ‘unsafe’}, optional

См. аргумент casting в ndarray.astype. Управляет видом преобразования данных.

Возвращает

unstructuredndarray

Неструктурированный массив с одной дополнительной размерностью.

Примеры

>>> from numpy.lib import recfunctions as rfn
>>> a = np.zeros(4, dtype=[('a', 'i4'), ('b', 'f4,u2'), ('c', 'f4', 2)])
>>> a
array([(0, (0., 0), [0., 0.]), (0, (0., 0), [0., 0.]),
       (0, (0., 0), [0., 0.]), (0, (0., 0), [0., 0.])],
      dtype=[('a', '<i4'), ('b', [('f0', '<f4'), ('f1', '<u2')]), ('c', '<f4', (2,))])
>>> rfn.structured_to_unstructured(a)
array([[0., 0., 0., 0., 0.],
       [0., 0., 0., 0., 0.],
       [0., 0., 0., 0., 0.],
       [0., 0., 0., 0., 0.]])

>>> b = np.array([(1, 2, 5), (4, 5, 7), (7, 8 ,11), (10, 11, 12)],
...              dtype=[('x', 'i4'), ('y', 'f4'), ('z', 'f8')])
>>> np.mean(rfn.structured_to_unstructured(b[['x', 'z']]), axis=-1)
array([ 3. ,  5.5,  9. , 11. ])

numpy.lib.recfunctions.unstructured_to_structured(arr, dtype=None, names=None, align=False, copy=False, casting='unsafe') [source]

Преобразование n-мерного неструктурированного массива в (n-1)-мерный структурированный массив.

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

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

Параметры

arrndarray

Неструктурированный массив или тип данных для преобразования.

dtypedtype, optional

Структурированный тип данных выходного массива

nameslist of strings, optional

Если dtype не указан, это определяет имена полей для выходного типа данных в порядке. Типы данных полей будут такими же, как у входного массива.

alignboolean, optional

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

copybool, optional

См. аргумент copy в ndarray.astype. Если True, всегда возвращается копия. Если False, и dtype требования выполнены, возвращается представление.

casting{‘no’, ‘equiv’, ‘safe’, ‘same_kind’, ‘unsafe’}, optional

См. аргумент casting в ndarray.astype. Управляет видом преобразования данных.

Возвращает

structuredndarray

Структурированный массив с меньшим числом измерений.

Примеры

>>> from numpy.lib import recfunctions as rfn
>>> dt = np.dtype([('a', 'i4'), ('b', 'f4,u2'), ('c', 'f4', 2)])
>>> a = np.arange(20).reshape((4,5))
>>> a
array([[ 0,  1,  2,  3,  4],
       [ 5,  6,  7,  8,  9],
       [10, 11, 12, 13, 14],
       [15, 16, 17, 18, 19]])
>>> rfn.unstructured_to_structured(a, dt)
array([( 0, ( 1.,  2), [ 3.,  4.]), ( 5, ( 6.,  7), [ 8.,  9.]),
       (10, (11., 12), [13., 14.]), (15, (16., 17), [18., 19.])],
      dtype=[('a', '<i4'), ('b', [('f0', '<f4'), ('f1', '<u2')]), ('c', '<f4', (2,))])