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

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

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

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

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

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

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

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

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

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

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

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

Пример

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

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

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

Пример

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

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

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

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 относится либо к строкам байтов с нулевым завершением, либо к строкам Unicode в зависимости от версии 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_ для удобства. Код должен учитывать, что такие типы могут отображаться в будущем на конкретный (новый) тип данных.

Types with .dtype

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

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

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

Каждый встроенный тип данных имеет код символа (обновленные типы кодов 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

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

Первый символ указывает тип данных, а оставшиеся символы – количество байтов на элемент, за исключением 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('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, то объект типа данных должен быть эквивалентен фиксированному типу dtype. Это поведение устарело начиная с NumPy 1.17 и в будущем будет вызывать ошибку. Если shape является кортежем, то новый dtype определяет подмассив заданной формы.

Пример

>>> 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#' ). Имя поля также может быть 2-кортежем строк, где первая строка — либо «заголовок» (который может быть любой строкой или строкой Юникода), либо метаданные для поля, которые могут быть любым объектом, а вторая строка — «имя», которое должно быть допустимым идентификатором 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 позволяет установить общий размер dtype и должен быть целым числом, достаточно большим, чтобы все поля находились внутри dtype. Если создаваемый dtype выровнен, itemsize также должен быть кратным выравниванию структуры. Общий размер dtype 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:

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

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

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

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

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

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

Методы

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

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