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

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

1. Тип данных (целое число, число с плавающей точкой, объект Python и т. д.)
2. Размер данных (сколько байт, например, в целом числе)
3. Порядок байтов данных (little-endian или big-endian)
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 встроенных объекта скалярного типа массива преобразуются в связанный объект типа данных. Это также справедливо для их подклассов.

Обратите внимание, что не вся информация о типе данных может быть предоставлена с помощью объекта типа: например, гибкие типы данных имеют значение 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

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

Пример

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