資料型態物件 (`dtype`)#

資料型態物件（numpy.dtype 類別的實例）描述了應如何解釋對應於陣列項目的固定大小記憶體區塊中的位元組。它描述了資料的以下幾個方面

資料的類型（整數、浮點數、Python 物件等）
資料的大小（例如，整數佔用多少位元組）
資料的位元組順序（小端序或大端序）
如果資料型態是結構化資料型態，即其他資料型態的聚合（例如，描述一個由整數和浮點數組成的陣列項目），
1. 結構的「欄位」名稱是什麼，它們可以透過這些名稱被存取，
2. 每個欄位的資料型態是什麼，以及
3. 每個欄位佔用記憶體區塊的哪一部分。
如果資料型態是子陣列，則其形狀和資料型態為何。

為了描述純量資料的類型，NumPy 中有幾種內建純量類型，用於各種精度的整數、浮點數等等。從陣列中提取的項目，例如，透過索引，將會是一個 Python 物件，其類型是與陣列資料型態相關聯的純量類型。

請注意，純量類型不是 dtype 物件，即使它們可以在 NumPy 中需要資料型態規範時用來代替。

結構化資料型態是透過建立一個資料型態來形成的，其欄位包含其他資料型態。每個欄位都有一個名稱，可以透過該名稱存取。父資料型態應具有足夠的大小以容納其所有欄位；父型態幾乎總是基於 void 類型，該類型允許任意項目大小。結構化資料型態也可能在其欄位中包含巢狀結構化子陣列資料型態。

最後，資料型態可以描述本身是另一種資料型態的項目陣列的項目。但是，這些子陣列必須具有固定的大小。

如果使用描述子陣列的資料型態建立陣列，則在建立陣列時，子陣列的維度會附加到陣列的形狀。結構化類型欄位中的子陣列行為不同，請參閱欄位存取。

子陣列始終具有 C 連續記憶體佈局。

範例

一個簡單的資料型態，包含一個 32 位元大端序整數：（有關建構的詳細資訊，請參閱指定和建構資料型態）

>>> import numpy as np

>>> dt = np.dtype('>i4')
>>> dt.byteorder
'>'
>>> dt.itemsize
4
>>> dt.name
'int32'
>>> dt.type is np.int32
True

對應的陣列純量類型是 int32。

範例

一個結構化資料型態，包含一個 16 字元的字串（在欄位 'name' 中）和一個由兩個 64 位元浮點數組成的子陣列（在欄位 'grades' 中）

>>> import numpy as np

>>> dt = np.dtype([('name', np.str_, 16), ('grades', np.float64, (2,))])
>>> dt['name']
dtype('<U16')
>>> dt['grades']
dtype(('<f8', (2,)))

此資料型態的陣列項目被封裝在一個也具有兩個欄位的陣列純量類型中

>>> import numpy as np

>>> 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(dtype[, align, copy])

建立資料型態物件。

以下描述了可以轉換為資料型態物件的內容

dtype 物件: 按原樣使用。
None: 預設資料型態：float64。

陣列純量類型

24 個內建陣列純量類型物件全部轉換為關聯的資料型態物件。對於它們的子類別也是如此。

請注意，並非所有資料型態資訊都可以透過類型物件提供：例如，flexible 資料型態的預設 itemsize 為 0，並且需要明確給定大小才能有用。

範例

>>> import numpy as np

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

通用類型

通用階層類型物件根據以下關聯轉換為對應的類型物件

`number`, `inexact`, `floating`	`float64`
`complexfloating`	`complex128`
`integer`, `signedinteger`	`int_`
`unsignedinteger`	`uint`
`generic`, `flexible`	`void`

版本 1.19 中已棄用：通用純量類型的這種轉換已被棄用。這是因為在諸如 arr.astype(dtype=np.floating) 之類的上下文中，它可能是意外的，它會將 float32 的陣列轉換為 float64 的陣列，即使 float32 是 np.floating 的子型別。

內建 Python 類型

當用於產生 dtype 物件時，幾種 python 類型等效於對應的陣列純量

`int`	`int_`
`bool`	`bool_`
`float`	`float64`
`complex`	`complex128`
`bytes`	`bytes_`
`str`	`str_`
`memoryview`	`void`
（所有其他類型）	`object_`

請注意，str_ 對應於 UCS4 編碼的 unicode 字串。

範例

>>> import numpy as np

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

注意

為了方便起見，所有其他類型都對應到 object_。程式碼應預期此類類型將來可能會對應到特定的（新的）dtype。

具有 .dtype 的類型

任何具有 dtype 屬性的類型物件：將直接存取和使用該屬性。該屬性必須傳回可轉換為 dtype 物件的內容。

幾種類型的字串可以轉換。可辨識的字串可以加上 '>'（大端序）、'<'（小端序）或 '='（硬體原生，預設值）作為前綴，以指定位元組順序。

單字元字串

每個內建資料型態都有一個字元代碼（更新的 Numeric 類型代碼），可以唯一識別它。

範例

>>> import numpy as np

>>> 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 除外，在 Unicode 中，它被解釋為字元數。項目大小必須對應於現有類型，否則將引發錯誤。支援的種類有

`'?'`	布林值
`'b'`	（有號）位元組
`'B'`	無號位元組
`'i'`	（有號）整數
`'u'`	無號整數
`'f'`	浮點數
`'c'`	複數浮點數
`'m'`	時間差
`'M'`	日期時間
`'O'`	（Python）物件
`'S'`, `'a'`	以零結尾的位元組（不建議使用）
`'U'`	Unicode 字串
`'V'`	原始資料 (`void`)

範例

>>> import numpy as np

>>> 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('S25')  # 25-length zero-terminated bytes
>>> dt = np.dtype('U25')  # 25-character string

關於字串類型的注意事項

為了向後相容最初編寫以支援 Python 2 的現有程式碼，S 和 a 類型字串是以零結尾的位元組。對於 unicode 字串，請使用 U、numpy.str_。對於不需要以零結尾的有號位元組，可以使用 b 或 i1。

以逗號分隔欄位的字串

用於指定結構化資料型態格式的一種簡寫符號是以逗號分隔的基本格式字串。

在此上下文中，基本格式是可選的形狀指定符，後跟陣列協定類型字串。如果形狀具有多個維度，則形狀上需要括號。NumPy 允許修改格式，即任何可以唯一識別類型的字串都可以用來指定欄位中的資料型態。產生的資料型態欄位被命名為 'f0'、'f1'、…、'f<N-1>'，其中 N (>1) 是字串中以逗號分隔的基本格式的數量。如果提供了可選的形狀指定符，則對應欄位的資料型態描述子陣列。

範例

名為 f0 的欄位，包含一個 32 位元整數
名為 f1 的欄位，包含一個 2 x 3 的 64 位元浮點數子陣列

名為 f2 的欄位，包含一個 32 位元浮點數

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

名為 f0 的欄位，包含一個 3 字元字串
名為 f1 的欄位，包含一個形狀為 (3,) 的子陣列，其中包含 64 位元無號整數
名為 f2 的欄位，包含一個 3 x 4 的子陣列，其中包含 10 字元字串
```
>>> import numpy as np
>>> dt = np.dtype("S3, 3u8, (3,4)S10")
```

類型字串

NumPy dtype 的任何字串名稱，例如

範例

>>> import numpy as np

>>> dt = np.dtype('uint32')   # 32-bit unsigned integer
>>> dt = np.dtype('float64')  # 64-bit floating-point number

(flexible_dtype, itemsize)

第一個引數必須是可以轉換為零大小彈性資料型態物件的物件，第二個引數是提供所需項目大小的整數。

範例

>>> import numpy as np

>>> dt = np.dtype((np.void, 10))  # 10-byte wide data block
>>> dt = np.dtype(('U', 10))   # 10-character unicode string

(fixed_dtype, shape)

第一個引數是可以轉換為固定大小資料型態物件的任何物件。第二個引數是此類型所需的形狀。如果 shape 參數為 1，則資料型態物件過去等效於固定 dtype。此行為自 NumPy 1.17 起已棄用，將來會引發錯誤。如果 shape 是元組，則新的 dtype 定義給定形狀的子陣列。

範例

>>> import numpy as np

>>> 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 的元組描述。（等效於 __array_interface__ 屬性中的 descr 項目。）

第一個元素 field_name 是欄位名稱（如果這是 ''，則會指派標準欄位名稱 'f#'）。欄位名稱也可能是一個字串 2 元組，其中第一個字串是欄位的「標題」（可以是任何字串或 unicode 字串）或中繼資料（可以是任何物件），第二個字串是「名稱」（必須是有效的 Python 識別符）。

第二個元素 field_dtype 可以是任何可以解釋為資料型態的內容。

可選的第三個元素 field_shape 包含形狀（如果此欄位表示第二個元素中資料型態的陣列）。請注意，第三個引數等於 1 的 3 元組等效於 2 元組。

此樣式不接受 dtype 建構函式中的 align，因為假定陣列介面描述已說明所有記憶體。

範例

具有欄位 big（大端序 32 位元整數）和 little（小端序 32 位元整數）的資料型態

>>> import numpy as np

>>> 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 可以是任何物件，但是當 str 物件將另一個條目新增至以標題為鍵的欄位字典，並引用將包含標題作為額外元組成員的相同欄位元組時。

itemsize 鍵允許設定 dtype 的總大小，並且必須是一個足夠大的整數，以便所有欄位都在 dtype 內。如果正在建構的 dtype 已對齊，則 itemsize 也必須可被結構對齊整除。總 dtype itemsize 限制為 ctypes.c_int。

範例

資料型態具有欄位 r、g、b、a，每個欄位都是一個 8 位元無號整數

>>> import numpy as np

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

範例

資料型態包含欄位 col1（位元組位置 0 的 10 字元字串）、col2（位元組位置 10 的 32 位元浮點數）和 col3（位元組位置 14 的整數）

>>> import numpy as np

>>> dt = np.dtype({'col1': ('U10', 0), 'col2': (np.float32, 10),
...                'col3': (int, 14)})

(base_dtype, new_dtype)

在 NumPy 1.7 及更高版本中，此形式允許將 base_dtype 解釋為結構化 dtype。使用此 dtype 建立的陣列將具有基礎 dtype base_dtype，但將具有從 new_dtype 取得的欄位和旗標。這對於建立自訂結構化 dtype 非常有用，如記錄陣列中所做的那樣。

此形式也使得可以指定具有重疊欄位的結構 dtype，其功能類似於 C 中的 'union' 類型。但是，不建議使用此用法，並且首選 union 機制。

兩個引數都必須可轉換為總大小相同的資料型態物件。

範例

32 位元整數，其前兩個位元組透過欄位 real 解釋為整數，後兩個位元組透過欄位 imag 解釋為整數。

>>> import numpy as np

>>> 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')]))

檢查資料型態#

在檢查特定資料型態時，請使用 == 比較。

範例

>>> import numpy as np

>>> a = np.array([1, 2], dtype=np.float32)
>>> a.dtype == np.float32
True

與 Python 類型相反，不應使用使用 is 的比較。

首先，NumPy 將資料型態規範（可以傳遞給 dtype 建構函式的所有內容）視為等效於資料型態物件本身。這種等效性只能透過 == 而不是透過 is 來處理。

範例

dtype 物件等於所有與其等效的資料型態規範。

>>> import numpy as np

>>> a = np.array([1, 2], dtype=float)
>>> a.dtype == np.dtype(np.float64)
True
>>> a.dtype == np.float64
True
>>> a.dtype == float
True
>>> a.dtype == "float64"
True
>>> a.dtype == "d"
True

其次，不能保證資料型態物件是單例模式。

範例

請勿使用 is，因為資料型態物件可能是也可能不是單例模式。

>>> import numpy as np

>>> np.dtype(float) is np.dtype(float)
True
>>> np.dtype([('a', float)]) is np.dtype([('a', float)])
False

`dtype`#

NumPy 資料型態描述是 dtype 類別的實例。

屬性#

資料的類型由以下 dtype 屬性描述

`dtype.type`
`dtype.kind`	一個字元代碼（'biufcmMOSUV' 之一），用於識別資料的一般種類。
`dtype.char`	21 種不同內建類型中每種类型的唯一字元代碼。
`dtype.num`	21 種不同內建類型中每種類型的唯一數字。
`dtype.str`	此資料型態物件的陣列協定類型字串。

資料的大小反過來由以下描述

`dtype.name`	此資料型態的位元寬度名稱。
`dtype.itemsize`	此資料型態物件的元素大小。

此資料的位元組序

dtype.byteorder

一個字元，指示此資料型態物件的位元組序。

關於結構化資料型態中子資料型態的資訊

`dtype.fields`	為此資料型態定義的具名欄位字典，或 `None`。
`dtype.names`	欄位名稱的排序列表，如果沒有欄位，則為 `None`。

對於描述子陣列的資料型態

`dtype.subdtype`	如果此 `dtype` 描述子陣列，則為元組 `(item_dtype, shape)`，否則為 None。
`dtype.shape`	如果此資料型態描述子陣列，則為子陣列的形狀元組，否則為 `()`。

提供其他資訊的屬性

`dtype.hasobject`	布林值，指示此 dtype 是否在任何欄位或子 dtype 中包含任何參考計數物件。
`dtype.flags`	描述如何解釋此資料型態的位元旗標。
`dtype.isbuiltin`	整數，指示此 dtype 與內建 dtype 的關係。
`dtype.isnative`	布林值，指示此 dtype 的位元組序是否為平台的原生位元組序。
`dtype.descr`	資料型態的 __array_interface__ 描述。
`dtype.alignment`	根據編譯器，此資料型態所需的對齊方式（位元組）。
`dtype.base`	傳回子陣列基本元素的 dtype，無論其維度或形狀如何。

使用者附加的中繼資料

dtype.metadata

None 或中繼資料的唯讀字典 (mappingproxy)。

方法#

資料型態具有以下用於更改位元組序的方法

dtype.newbyteorder([new_order])

傳回具有不同位元組序的新 dtype。

以下方法實作 pickle 協定

`dtype.__reduce__`	pickle 的輔助方法。
`dtype.__setstate__`

用於類型標註的實用方法

dtype.__class_getitem__(item, /)

傳回 dtype 類型的參數化包裝器。

比較運算

`dtype.__ge__`(value, /)	傳回 self>=value。
`dtype.__gt__`(value, /)	傳回 self>value。
`dtype.__le__`(value, /)	傳回 self<=value。
`dtype.__lt__`(value, /)	傳回 self<value。

資料型態物件 (dtype)#

指定和建構資料型態#

檢查資料型態#

dtype#

屬性#

方法#

資料型態物件 (`dtype`)#

`dtype`#