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

Введение

Структурированные массивы — это 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 символов или меньше с именем ‘name’, 2. 32-битное целое число с именем ‘age’, и 3. 32-битное число с плавающей запятой с именем ‘weight’.

Если вы индексируете 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. Словарь с параметрами массивов полей

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

   Словарь содержит два обязательных ключа, ‘names’ и ‘formats’, и четыре необязательных ключа, ‘offsets’, ‘itemsize’, ‘aligned’ и ‘titles’. Значения для ‘names’ и ‘formats’ должны соответственно быть списком имён полей и списком спецификаций типов данных такой же длины. Необязательное значение ‘offsets’ должно быть списком целочисленных смещений в байтах, по одному на каждое поле в структуре. Если ‘offsets’ не указано, смещения определяются автоматически. Необязательное значение ‘itemsize’ должно быть целым числом, описывающим общий размер в байтах типа данных, который должен быть достаточно большим, чтобы содержать все поля.

   >>> 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 не могут перекрываться с другими полями, из-за риска перезаписи внутреннего указателя объекта и последующего его обращения.

   Необязательное значение ‘aligned’ может быть установлено в True для того, чтобы вычисление смещений использовало выровненные смещения (см. Автоматическое вычисление смещений в байтах и выравнивание), как будто аргумент ключевого слова ‘align’ функции numpy.dtype был установлен в True.

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

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

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

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

Структурированные типы данных в numpy реализованы с базовым типом numpy.void по умолчанию, но можно интерпретировать другие типы numpy как структурированные типы, используя форму спецификации типа данных (base_dtype, dtype), описанную в Объекты типов данных. Здесь, base_dtype — желаемый базовый тип данных, а поля и флаги будут скопированы из dtype. Этот тип данных похож на 'объединение' в 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 scalar 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')])

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

>>> 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})

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

>>> 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. Структурированные скаляры могут быть преобразованы в кортеж, вызвав ndarray.item:

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

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

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

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

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

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

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

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

Массивы записей

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

Самый простой способ создать массив записей — с помощью 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 как типа np.recarray автоматически преобразуется в тип np.record, поэтому dtype можно опустить из представления:

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

Чтобы вернуться к простому ndarray, необходимо сбросить dtype и тип. Следующее представление делает это, учитывая необычный случай, когда 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

Возвращать ли массив записей (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.

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

..versionchanged: 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 или массив с маской и гибким dtype. По умолчанию 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

Возвращать ли массив с пропусками.

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 не существует в входном массиве, это поле создается и устанавливается в 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 не указан, это определяет имена полей для выходного 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,))])