Типы данных массивов (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(('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 относится либо к нуль-терминированным байтам, либо к строкам Юникода в зависимости от версии 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

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

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

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

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

Первый символ указывает тип данных, а оставшиеся символы — количество байтов на элемент, за исключением Юникода, где он интерпретируется как количество символов. Размер элемента должен соответствовать существующему типу, иначе будет выведено сообщение об ошибке. Поддерживаемые типы —

Пример

>>> 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, содержащее 2 x 3 подмассив 64-битных чисел с плавающей точкой
• поле с именем f2 содержащее 32-битное число с плавающей точкой

>>> dt = np.dtype("i4, (2,3)f8, f4")

• поле с именем f0 содержащее строку из 3 символов
• поле с именем f1 содержащее подмассив формы (3,) содержащий 64-битные беззнаковые целые числа
• поле с именем f2 содержащее 3 x 4 подмассив, содержащий строки из 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-кортежем строк, где первая строка — это «заголовок» (который может быть любой строкой или строкой 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': [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': ('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: