Типы данных массивов (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 символов (в поле «name») и подмассив из двух 64-битовых вещественных чисел (в поле «grades»):

>>> dt = np.dtype([('name', np.unicode_, 16), ('grades', np.float64, (2,))])
>>> dt['name']
dtype('|U16')
>>> 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:

Обратите внимание, что 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: этот атрибут будет доступен и использован непосредственно. Атрибут должен возвращать что-то, что можно преобразовать в объект dtype.

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

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

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

Пример

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

Пример

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

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

Пример

Тип данных с полями 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 должен содержать строковые или Юникод-ключи, которые ссылаются на (data-type, offset) или (data-type, offset, title) кортежи.

Пример

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

>>> dt = np.dtype({'col1': ('U10', 0), 'col2': (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: