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

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

1. Тип данных (целое число, число с плавающей запятой, объект Python и т. д.)
2. Размер данных (сколько байт, например, в целом числе)
3. Порядок байтов данных (little-endian или big-endian)
4. Если тип данных является structured, агрегатом других типов данных (например, описывающим элемент массива, состоящий из целого числа и числа с плавающей запятой),
   1. каковы имена «fields» структуры, по которым к ним можно обратиться,
   2. каков тип данных каждого field и
   3. какую часть блока памяти занимает каждый поле.
5. Если тип данных является подмассивом, каковы его форма и тип данных.

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

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

Структурированные типы данных создаются путем создания типа данных, чьи fields содержат другие типы данных. Каждое поле имеет имя, по которому к нему можно обратиться. Тип родительского объекта должен быть достаточно большим, чтобы содержать все его поля; родительский объект почти всегда основан на типе 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.str_, 16), ('grades', np.float64, (2,))])
>>> dt['name']
dtype('|S16')
>>> dt['grades']
dtype(('float64',(2,)))

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

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

Определение и создание типов данных

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

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

dtype объект

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

None

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

Типы скаляров массивов

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

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

Пример

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

Общие типы

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

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

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

Пример

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

Типы со .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

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

Первый символ указывает тип данных, а оставшиеся символы — количество байт на элемент, за исключением 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-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((void, 10))  # 10-byte wide data block
>>> dt = np.dtype((str, 35))   # 35-character string
>>> dt = np.dtype(('U', 10))   # 10-character unicode string

(fixed_dtype, shape)

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

Пример

>>> dt = np.dtype((np.int32, (2,2)))          # 2 x 2 integer sub-array
>>> dt = np.dtype(('S10', 1))                 # 10-character string
>>> 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-битное число в формате 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 — это список байтовых смещений (целых чисел) для каждого поля, а значение titles — это список заголовков для каждого поля (None может быть использовано, если для этого поля не требуется заголовок). Заголовки titles могут быть любыми string или unicode объектами и добавят другую запись в словарь полей, ключом которой будет заголовок, а значением — тот же кортеж полей, который будет содержать заголовок в качестве дополнительного члена кортежа.

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

Пример

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

>>> dt = np.dtype({'names': ['r','g','b','a'],
...                'formats': [uint8, uint8, uint8, 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': ('S10', 0), 'col2': (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:

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

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

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

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

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

Методы

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

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