Типы данных массивов (dtype)

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

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

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

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

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

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

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

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

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

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

Подмассивы всегда имеют расположение памяти с непрерывной структурой (C-contiguous).

Пример

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

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

Общие типы

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

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

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

Примечание: 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

Типы с .dtype

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

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

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

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

Пример

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

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

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

Основной формат в данном контексте — это необязательный спецификатор формы, за которым следует строка типа из протокола массивов. Скобки требуются для формы, если она имеет более одной размерности. 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 является кортежем, то новый тип данных определяет подмассив с заданной формой.

Пример

>>> 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#'). Имя поля также может быть кортежем из двух строк, где первая строка — это либо «заголовок» (который может быть любой строкой или строкой Unicode), либо метаданные для поля, которые могут быть любым объектом, а вторая строка — «имя», которое должно быть допустимым идентификатором Python.

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

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

Этот стиль не принимает align в конструкторе 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': ...}

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

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

Ключ 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 должен содержать строковые или строковые 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')]))

dtype

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

Атрибуты

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

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

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

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

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

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

Методы

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

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