Объекты типов данных (dtype)

Объект типа данных (экземпляр класса numpy.dtype) описывает, как интерпретировать байты в фиксированном блоке памяти, соответствующем элементу массива. Он описывает следующие аспекты данных:

1. Тип данных (целое число, вещественное число, объект Python и т. д.)
2. Размер данных (сколько байтов, например, в целом числе)
3. Порядок байтов данных (маленький порядок или большой порядок)

4. Если тип данных — структурированный тип данных, агрегат других типов данных (например, описывающий элемент массива, состоящий из целого числа и вещественного числа),

   1. как называются «поля» структуры, с помощью которых к ним можно обратиться,
   2. какой тип данных имеет каждое поле, и
   3. какую часть блока памяти занимает каждое поле.
5. Если тип данных — подмассив, каковы его форма и тип данных.

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

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

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

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

Если массив создается с использованием типа данных, описывающего подмассив, размеры подмассива добавляются к форме массива при создании массива. Подмассивы в поле структурированного типа ведут себя по-другому, см. Доступ к полям.

Подмассивы всегда имеют упорядоченную в памяти компоновку C.

Пример

Простой тип данных, содержащий 32-битное целое число в формате big-endian: (подробнее о создании см. Указание и создание типов данных)

>>> dt = np.dtype('>i4')
>>> dt.byteorder
'>'
>>> dt.itemsize
4
>>> dt.name
'int32'
>>> dt.type is np.int32
True

Соответствующий скалярный тип массива — int32.

Пример

Структурированный тип данных, содержащий 16-символьную строку (в поле «имя») и подмассив из двух 64-битных чисел с плавающей точкой (в поле «оценки»):

>>> dt = np.dtype([('name', np.unicode_, 16), ('grades', np.float64, (2,))])
>>> dt['name']
dtype('<U16')
>>> dt['grades']
dtype(('<f8', (2,)))

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

>>> x = np.array([('Sarah', (8.0, 7.0)), ('John', (6.0, 7.0))], dtype=dt)
>>> x[1]
('John', [6., 7.])
>>> x[1]['grades']
array([6.,  7.])
>>> type(x[1])
<class 'numpy.void'>
>>> type(x[1]['grades'])
<class 'numpy.ndarray'>

Указание и создание типов данных

В любой функции или методе NumPy, где требуется тип данных, можно предоставить либо объект dtype, либо то, что может быть преобразовано в него. Такие преобразования выполняются конструктором dtype:

Ниже описывается, что может быть преобразовано в объект типа данных:

dtype объект

Используется как есть.

None

По умолчанию тип данных: float_.

Массивно-скалярные типы

Все 24 встроенных объекты массивно-скалярного типа преобразуются в соответствующий объект типа данных. Это верно и для их подклассов.

Обратите внимание, что не вся информация о типе данных может быть предоставлена с помощью объекта типа: например, типы данных flexible имеют значение по умолчанию itemsize 0 и требуют явного указания размера, чтобы быть полезными.

Пример

>>> dt = np.dtype(np.int32)      # 32-bit integer
>>> dt = np.dtype(np.complex128) # 128-bit complex floating-point number

Общетиповые типы

Объекты общетиповых иерархических типов преобразуются в соответствующие объекты типов в соответствии с ассоциациями:

number, inexact, floating	float
complexfloating	cfloat
integer, signedinteger	int_
unsignedinteger	uint
character	string
generic, flexible	void

Устарело начиная с версии 1.19: Это преобразование общетиповых скалярных типов устарело. Это связано с тем, что оно может быть неожиданным в контексте, таком как arr.astype(dtype=np.floating), который преобразует массив float32 в массив float64, хотя float32 является подтипом np.floating.

Встроенные типы Python

Несколько типов Python эквивалентны соответствующему массивно-скалярному типу при использовании для генерации объекта dtype:

int	int_
bool	bool_
float	float_
complex	cfloat
bytes	bytes_
str	str_
buffer	void
(все остальные)	object_

Обратите внимание, что str относится к нуль-терминированным байтам или строкам Юникода в зависимости от версии Python. В коде, ориентированном на Python 2 и 3, следует использовать np.unicode_ в качестве типа данных для строк. См. Примечание о строчных типах.

Пример

>>> dt = np.dtype(float)   # Python-compatible floating-point number
>>> dt = np.dtype(int)     # Python-compatible integer
>>> dt = np.dtype(object)  # Python object

Примечание

Все остальные типы отображаются на object_ для удобства. Код должен ожидать, что такие типы могут отображаться на определенный (новый) тип данных в будущем.

Типы с атрибутом .dtype

Любой объект типа с атрибутом dtype: Атрибут будет доступен и использован напрямую. Атрибут должен возвращать что-то, что может быть преобразовано в объект типа данных.

Можно преобразовать несколько типов строк. Распознаваемые строки могут быть снабжены префиксом '>' (big-endian), '<' (little-endian) или '=' (родной для аппаратной платформы, по умолчанию), чтобы указать порядок байтов.

Строки из одного символа

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

Пример

>>> dt = np.dtype('b')  # byte, native byte order
>>> dt = np.dtype('>H') # big-endian unsigned short
>>> dt = np.dtype('<f') # little-endian single-precision float
>>> dt = np.dtype('d')  # double-precision floating-point number

Строки типа протокола массивов (см. Интерфейс массивов)

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

'?'	булево
'b'	(знаковый) байт
'B'	(беззнаковый) байт
'i'	(знаковый) целое число
'u'	(беззнаковый) целое число
'f'	вещественное число с плавающей запятой
'c'	комплексное вещественное число с плавающей запятой
'm'	timedelta
'M'	datetime
'O'	(объекты Python)
'S', 'a'	строка байтов с нулевым завершением (не рекомендуется)
'U'	строка Юникода
'V'	сырые данные (void)

Пример

>>> dt = np.dtype('i4')   # 32-bit signed integer
>>> dt = np.dtype('f8')   # 64-bit floating-point number
>>> dt = np.dtype('c16')  # 128-bit complex floating-point number
>>> dt = np.dtype('a25')  # 25-length zero-terminated bytes
>>> dt = np.dtype('U25')  # 25-character string

Примечание о строчных типах

Для обратной совместимости с Python 2 типы S и a остаются строками байтов с нулевым завершением, а numpy.string_ по-прежнему является псевдонимом numpy.bytes_. Для использования реальных строк в Python 3 используйте U или numpy.str_. Для знакомых байтов, не требующих нулевого завершения, можно использовать b или i1.

Строка с полями, разделенными запятыми

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

Базовый формат в данном контексте — это необязательный указатель формы, за которым следует строка типа протокола массива. Скобки обязательны для формы, если она имеет более одной размерности. NumPy допускает модификацию формата, в том смысле, что любой строкой, которая может однозначно идентифицировать тип, можно использовать для задания типа данных в поле. Созданные поля типа данных называются 'f0', 'f1', …, 'f<N-1>' где N (>1) — количество базовых форматов, разделенных запятыми, в строке. Если указатель формы предоставлен, то тип данных для соответствующего поля описывает подмассив.

Пример

• поле с именем f0, содержащее 32-битовое целое число
• поле с именем f1, содержащее подмассив 2x3 64-битных чисел с плавающей запятой
• поле с именем f2, содержащее 32-битное число с плавающей запятой

>>> dt = np.dtype("i4, (2,3)f8, f4")

• поле с именем f0, содержащее строку из 3 символов
• поле с именем f1 содержащее подмассив формы (3,) с 64-битными беззнаковыми целыми числами
• поле с именем f2 содержащее подмассив 3x4, содержащий строки из 10 символов

>>> dt = np.dtype("a3, 3u8, (3,4)a10")

Строки типа

Любая строка в numpy.sctypeDict.keys():

Пример

>>> dt = np.dtype('uint32')   # 32-bit unsigned integer
>>> dt = np.dtype('float64')  # 64-bit floating-point number

(flexible_dtype, itemsize)

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

Пример

>>> dt = np.dtype((np.void, 10))  # 10-byte wide data block
>>> dt = np.dtype(('U', 10))   # 10-character unicode string

(fixed_dtype, shape)

Первый аргумент — любой объект, который может быть преобразован в объект фиксированного типа данных. Второй аргумент — желаемая форма этого типа. Если параметр формы равен 1, то объект типа данных эквивалентен фиксированному типу. Это поведение устарело с NumPy 1.17 и в будущем будет вызывать ошибку. Если shape является кортежем, новый тип данных определяет подмассив заданной формы.

Пример

>>> dt = np.dtype((np.int32, (2,2)))          # 2 x 2 integer sub-array
>>> dt = np.dtype(('i4, (2,3)f8, f4', (2,3))) # 2 x 3 structured sub-array

[(field_name, field_dtype, field_shape), ...]

obj должен быть списком полей, где каждое поле описывается кортежем длиной 2 или 3. (Эквивалентно элементу descr в атрибуте __array_interface__.)

Первый элемент, field_name, — имя поля (если это '' , то присваивается стандартное имя поля, 'f#'). Имя поля также может быть кортежем из двух строк, где первая строка — «заголовок» (который может быть любой строкой или строкой Юникод) или метаданные для поля, которые могут быть любым объектом, а вторая строка — «имя», которое должно быть допустимым идентификатором Python.

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

Необязательный третий элемент field_shape содержит форму, если это поле представляет массив типа данных во втором элементе. Обратите внимание, что кортеж из 3 элементов с третьим аргументом, равным 1, эквивалентен кортежу из 2 элементов.

Этот стиль не принимает align в конструкторе dtype, так как предполагается, что вся память учтена описанием интерфейса массива.

Пример

Тип данных с полями big (целое 32-битное число в формате big-endian) и little (целое 32-битное число в формате little-endian):

>>> dt = np.dtype([('big', '>i4'), ('little', '<i4')])

Тип данных с полями R, G, B, A, каждое из которых — беззнаковое 8-битное целое число:

>>> dt = np.dtype([('R','u1'), ('G','u1'), ('B','u1'), ('A','u1')])

{'names': ..., 'formats': ..., 'offsets': ..., 'titles': ..., 'itemsize': ...}

Этот стиль имеет два обязательных и три необязательных ключа. Ключи names и formats являются обязательными. Их соответствующие значения — списки равной длины с именами полей и форматами полей. Имена полей должны быть строками, а форматы полей — любыми объектами, принимаемыми конструктором dtype.

Когда предоставляются необязательные ключи offsets и titles, их значения должны быть списками той же длины, что и списки names и formats. Значение offsets — список байтовых смещений (ограниченных ctypes.c_int) для каждого поля, а значение titles — список заголовков для каждого поля (None можно использовать, если для этого поля заголовок не требуется). Заголовки titles могут быть любыми объектами, но когда объект str добавит ещё одну запись в словарь полей с ключом, соответствующим заголовку, и со ссылкой на тот же кортеж полей, который будет содержать заголовок в качестве дополнительного члена кортежа.

Ключ itemsize позволяет установить общий размер типа данных и должен быть целым числом, достаточно большим для того, чтобы все поля поместились в типе данных. Если создаваемый тип данных выровнен, itemsize также должен быть кратен выравниванию структуры. Общий размер типа данных itemsize ограничен ctypes.c_int.

Пример

Тип данных с полями r, g, b, a, каждое из которых — беззнаковое 8-битное целое число:

>>> dt = np.dtype({'names': ['r','g','b','a'],
...                'formats': [np.uint8, np.uint8, np.uint8, np.uint8]})

Тип данных с полями r и b (с заданными заголовками), оба являющиеся беззнаковыми 8-битными целыми числами, первое — в байтовой позиции 0 от начала поля, а второе — в позиции 2:

>>> dt = np.dtype({'names': ['r','b'], 'formats': ['u1', 'u1'],
...                'offsets': [0, 2],
...                'titles': ['Red pixel', 'Blue pixel']})

{'field1': ..., 'field2': ..., ...}

Это использование не рекомендуется, так как оно неоднозначно с другим методом построения на основе словаря. Если у вас есть поле с именем «names» и поле с именем «formats», возникнет конфликт.

Этот стиль позволяет передавать атрибут fields объекта типа данных.

obj должен содержать строковые или строковые ключи Юникод, которые ссылаются на (data-type, offset) или (data-type, offset, title) кортежи.

Пример

Тип данных, содержащий поле col1 (строка длиной 10 символов в байтовой позиции 0), col2 (32-битное число с плавающей точкой в байтовой позиции 10) и col3 (целые числа в байтовой позиции 14):

>>> dt = np.dtype({'col1': ('U10', 0), 'col2': (np.float32, 10),
...                'col3': (int, 14)})

(base_dtype, new_dtype)

В NumPy 1.7 и более поздних версиях эта форма позволяет base_dtype интерпретироваться как структурированный тип данных. Массивы, созданные с этим типом данных, будут иметь базовый тип base_dtype, но будут иметь поля и флаги, взятые из new_dtype. Это полезно для создания пользовательских структурированных типов данных, как это делается в массивах записей.

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

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

Пример

32-битное целое число, первые два байта которого интерпретируются как целое число через поле real, а следующие два байта — через поле imag.

>>> dt = np.dtype((np.int32,{'real':(np.int16, 0),'imag':(np.int16, 2)}))

32-битное целое число, которое интерпретируется как состоящее из подмассива формы (4,), содержащего 8-битные целые числа:

>>> dt = np.dtype((np.int32, (np.int8, 4)))

32-битное целое число, содержащее поля r, g, b, a, которые интерпретируют 4 байта в целом числе как четыре беззнаковых целых числа:

>>> dt = np.dtype(('i4', [('r','u1'),('g','u1'),('b','u1'),('a','u1')]))

dtype

Описания типов данных NumPy являются экземплярами класса dtype.

Атрибуты

Тип данных описывается следующими атрибутами dtype:

Размер данных описывается:

Порядок байтов этих данных:

Информация о подтипах в структурированном типе данных:

Для типов данных, описывающих подмассивы:

Атрибуты, предоставляющие дополнительную информацию:

Метаданные, добавленные пользователем:

Методы

Типы данных имеют следующий метод для изменения порядка байтов:

Следующие методы реализуют протокол сериализации: