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

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

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

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

dtype объект

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

None

Тип данных по умолчанию: float64.

Типы массивно-скалярных данных

Все 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	float64
complexfloating	complex128
integer, signedinteger	int_
unsignedinteger	uint
generic, flexible	void

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

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

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

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

Обратите внимание, что str_ соответствует строкам Unicode с кодировкой UCS4.

Пример

>>> 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) или '=' (родной для оборудования, по умолчанию), чтобы указать порядок байтов.

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

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

Пример

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

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

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

'?'	логический
'b'	(знаковое) байтовое
'B'	беззнаковое байтовое
'i'	(знаковое) целое
'u'	беззнаковое целое
'f'	с плавающей точкой
'c'	комплексное число с плавающей точкой
'm'	timedelta
'M'	datetime
'O'	(объекты Python)
'S', 'a'	байты с нулевым завершением (не рекомендуется)
'U'	строка Unicode
'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('S25')  # 25-length zero-terminated bytes
>>> dt = np.dtype('U25')  # 25-character string

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

Для обратной совместимости со старым кодом, написанным для поддержки Python 2, типы строк S и a представляют собой байты с нулевым завершением. Для строк Unicode используйте 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("S3, 3u8, (3,4)S10")

Строки типов

Любое имя строки типа NumPy, например:

Пример

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

Пример

>>> 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__.)

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

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

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

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

Пример

Тип данных с полями big (целое 32-битное большого порядка) и little (целое 32-битное малого порядка):

>>> 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': ...}

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

При предоставлении необязательных ключей смещения и заголовки их значения должны быть списками той же длины, что и списки имена и форматы. Значение смещения — список байтовых смещений (ограниченных ctypes.c_int) для каждого поля, а значение заголовки — список заголовков для каждого поля (None используется, если заголовок для поля не требуется). Заголовки могут быть любыми объектами, но при использовании объекта 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': ..., ...}

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

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

obj должен содержать строковые или строковые ключи Unicode, которые ссылаются на (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. Это полезно для создания пользовательских структурированных типов данных, как в массивах записей.

Эта форма также позволяет указать структурированные типы данных с перекрывающимися полями, действуя как тип «объединение» в 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')]))

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

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

Пример

>>> a = np.array([1, 2], dtype=np.float32)
>>> a.dtype == np.float32
True

В отличие от типов Python, сравнение с использованием is не следует использовать.

Во-первых, NumPy обрабатывает спецификации типов данных (все, что можно передать конструктору dtype) как эквивалентные самому объекту типа данных. Это эквивалентность можно обработать только через ==, а не через is.

Пример

Объект dtype равен всем спецификациям типа данных, которые эквивалентны ему.

>>> a = np.array([1, 2], dtype=float)
>>> a.dtype == np.dtype(np.float64)
True
>>> a.dtype == np.float64
True
>>> a.dtype == float
True
>>> a.dtype == "float64"
True
>>> a.dtype == "d"
True

Во-вторых, нет гарантии, что объекты типов данных являются синглтонами.

Пример

Не используйте is, так как объекты типов данных могут или не могут быть синглтонами.

>>> np.dtype(float) is np.dtype(float)
True
>>> np.dtype([('a', float)]) is np.dtype([('a', float)])
False

dtype

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