Python numpy nditer用法及代碼示例

本文簡要介紹 python 語言中 numpy.nditer 的用法。

用法:

class  numpy.nditer(op, flags=None, op_flags=None, op_dtypes=None, order='K', casting='safe', op_axes=None, itershape=None, buffersize=0)

高效的多維迭代器對象來迭代數組。要開始使用此對象，請參閱數組迭代介紹指南。

參數：

op： ndarray 或 數組 序列

要迭代的數組。

flags： str 序列，可選

用於控製迭代器行為的標誌。

• buffered 在需要時啟用緩衝。

• c_index 導致跟蹤 C-order 索引。

• f_index 導致跟蹤 Fortran-order 索引。

• multi_index 導致跟蹤多索引或每個迭代維度一個索引的元組。

• common_dtype 將所有操作數轉換為通用數據類型，並根據需要進行複製或緩衝。

• copy_if_overlap 使迭代器確定讀取操作數是否與寫入操作數重疊，並根據需要製作臨時副本以避免重疊。在某些情況下可能會出現誤報(不必要的複製)。

• delay_bufalloc 延遲分配緩衝區，直到調用 reset()。允許在將 allocate 操作數的值複製到緩衝區之前對其進行初始化。

• external_loop 導致給定的 values 是具有多個值的一維數組，而不是零維數組。

• 當同時使用 buffered 和 external_loop 時，grow_inner 允許 value 數組大小大於緩衝區大小。

• ranged 允許將迭代器限製為 iterindex 值的 sub-range。

• refs_ok 啟用引用類型的迭代，例如對象數組。

• reduce_ok 啟用廣播的readwrite 操作數的迭代，也稱為歸約操作數。

• zerosize_ok 允許 itersize 為零。

op_flags： str 列表列表，可選

這是每個操作數的標誌列表。至少，必須指定 readonly 、 readwrite 或 writeonly 之一。

• readonly 表示隻讀取操作數。

• readwrite 表示將讀取和寫入操作數。

• writeonly 表示隻寫入操作數。

• no_broadcast 阻止廣播操作數。

• contig 強製操作數數據是連續的。

• aligned 強製操作數數據對齊。

• nbo 強製操作數數據采用本機字節順序。

• copy 如果需要，允許臨時隻讀副本。

• 如果需要，updateifcopy 允許臨時讀寫副本。

• allocate 如果在 op 參數中為 None，則導致分配數組。

• no_subtype 防止 allocate 操作數使用子類型。

• arraymask 表示此操作數是在寫入設置了‘writemasked’ 標誌的操作數時用於選擇元素的掩碼。迭代器不強製執行此操作，但是當從緩衝區寫回數組時，它僅複製此掩碼指示的那些元素。

• writemasked 表示隻有選擇的 arraymask 操作數為 True 的元素才會被寫入。

• overlap_assume_elementwise 可用於標記僅以迭代器順序訪問的操作數，以便在存在 copy_if_overlap 時允許不那麽保守的複製。

op_dtypes： dtype 或 dtype(s) 的元組，可選

操作數所需的數據類型。如果啟用了複製或緩衝，則數據將轉換為/從其原始類型轉換。

order： {‘C’、‘F’、‘A’、‘K’}，可選

控製迭代順序。 “C”表示 C 順序，“F”表示 Fortran 順序，如果所有數組都是 Fortran 連續的，則“A”表示“F”順序，否則為“C”順序，“K”表示與數組元素出現的順序接近盡可能在內存中。這也會影響 allocate 操作數的元素內存順序，因為它們被分配為與迭代順序兼容。默認為“K”。

casting： {‘no’, ‘equiv’, ‘safe’, ‘same_kind’, ‘unsafe’}，可選

控製在進行複製或緩衝時可能發生的數據類型轉換。不建議將此設置為‘unsafe’，因為它會對累積產生不利影響。

• ‘no’ 表示根本不應該轉換數據類型。

• ‘equiv’ 表示隻允許更改字節順序。

• ‘safe’ 意味著隻允許可以保留值的強製轉換。

• ‘same_kind’ 表示隻允許安全類型轉換或類型中的類型轉換，如 float64 到 float32。

• ‘unsafe’ 表示可以進行任何數據轉換。

op_axes： 整數列表列表，可選

如果提供，則為每個操作數的整數列表或無。操作數的軸列表是從迭代器維度到操作數維度的映射。可以為條目放置值 -1，從而將該維度視為 newaxis 。

itershape： 整數元組，可選

迭代器的所需形狀。這允許具有由op_axes 映射的維度不對應於不同操作數的維度的allocate 操作數獲得該維度的不等於1 的值。

buffersize： 整數，可選

啟用緩衝時，控製臨時緩衝區的大小。設置為 0 作為默認值。

注意：

nditer 取代 flatiter 。 nditer 背後的迭代器實現也由 NumPy C API 公開。

Python 公開提供了兩個迭代接口，一個遵循 Python 迭代器協議，另一個反映 C 風格的 do-while 模式。在大多數情況下，原生 Python 方法更好，但如果您需要迭代器的坐標或索引，請使用 C 樣式模式。

例子：

下麵是我們如何使用 Python 迭代器協議編寫 iter_add 函數：

>>> def iter_add_py(x, y, out=None):
...     addop = np.add
...     it = np.nditer([x, y, out], [],
...                 [['readonly'], ['readonly'], ['writeonly','allocate']])
...     with it:
...         for (a, b, c) in it:
...             addop(a, b, out=c)
...         return it.operands[2]

這是相同的函數，但遵循 C 風格模式：

>>> def iter_add(x, y, out=None):
...    addop = np.add
...    it = np.nditer([x, y, out], [],
...                [['readonly'], ['readonly'], ['writeonly','allocate']])
...    with it:
...        while not it.finished:
...            addop(it[0], it[1], out=it[2])
...            it.iternext()
...        return it.operands[2]

這是一個示例外部產品函數：

>>> def outer_it(x, y, out=None):
...     mulop = np.multiply
...     it = np.nditer([x, y, out], ['external_loop'],
...             [['readonly'], ['readonly'], ['writeonly', 'allocate']],
...             op_axes=[list(range(x.ndim)) + [-1] * y.ndim,
...                      [-1] * x.ndim + list(range(y.ndim)),
...                      None])
...     with it:
...         for (a, b, c) in it:
...             mulop(a, b, out=c)
...         return it.operands[2]

>>> a = np.arange(2)+1
>>> b = np.arange(3)+1
>>> outer_it(a,b)
array([[1, 2, 3],
       [2, 4, 6]])

這是一個像“lambda” ufunc 一樣運行的示例函數：

>>> def luf(lamdaexpr, *args, **kwargs):
...    '''luf(lambdaexpr, op1, ..., opn, out=None, order='K', casting='safe', buffersize=0)'''
...    nargs = len(args)
...    op = (kwargs.get('out',None),) + args
...    it = np.nditer(op, ['buffered','external_loop'],
...            [['writeonly','allocate','no_broadcast']] +
...                            [['readonly','nbo','aligned']]*nargs,
...            order=kwargs.get('order','K'),
...            casting=kwargs.get('casting','safe'),
...            buffersize=kwargs.get('buffersize',0))
...    while not it.finished:
...        it[0] = lamdaexpr(*it[1:])
...        it.iternext()
...    return it.operands[0]

>>> a = np.arange(5)
>>> b = np.ones(5)
>>> luf(lambda i,j:i*i + j/2, a, b)
array([  0.5,   1.5,   4.5,   9.5,  16.5])

如果操作數標誌“writeonly”或者“readwrite”被使用的操作數可能是原始數據的視圖WRITEBACKIFCOPY旗幟。在這種情況下nditer必須用作上下文管理器或nditer.close在使用結果之前必須調用方法。臨時數據將被寫回原始數據，當__exit__函數被調用但不是在之前：

>>> a = np.arange(6, dtype='i4')[::-2]
>>> with np.nditer(a, [],
...        [['writeonly', 'updateifcopy']],
...        casting='unsafe',
...        op_dtypes=[np.dtype('f4')]) as i:
...    x = i.operands[0]
...    x[:] = [-1, -2, -3]
...    # a still unchanged here
>>> a, x
(array([-1, -2, -3], dtype=int32), array([-1., -2., -3.], dtype=float32))

需要注意的是，一旦退出迭代器，懸空引用(如示例中的 x)可能會也可能不會與原始數據 a 共享數據。如果回寫語義處於活動狀態，即如果 x.base.flags.writebackifcopy 為 True，則退出迭代器將切斷 x 和 a 之間的連接，寫入 x 將不再寫入 a。如果回寫語義未激活，則 x.data 仍將指向 a.data 的某些部分，並且寫入其中一個部分將影響另一個部分。

上下文管理和 close 方法出現在 1.15.0 版本中。

屬性：

dtypes： dtype 的元組

value 中提供的值的數據類型。如果啟用了緩衝，這可能與操作數數據類型不同。僅在迭代器關閉之前有效。

finished： bool

操作數上的迭代是否完成。

has_delayed_bufalloc： bool

如果為 True，則使用 delay_bufalloc 標誌創建迭代器，並且尚未對其調用 reset() 函數。

has_index： bool

如果為 True，則使用 c_index 或 f_index 標誌創建迭代器，並且可以使用屬性 index 來檢索它。

has_multi_index： bool

如果為 True，則使用 multi_index 標誌創建迭代器，並且可以使用屬性 multi_index 來檢索它。

index：

當使用c_index 或f_index 標誌時，此屬性提供對索引的訪問。如果訪問並且 has_index 為 False，則引發 ValueError。

iterationneedsapi： bool

迭代是否需要訪問 Python API，例如，如果操作數之一是對象數組。

iterindex： int

與迭代順序匹配的索引。

itersize： int

迭代器的大小。

itviews：

operands 在內存中的結構化視圖，匹配重新排序和優化的迭代器訪問模式。僅在迭代器關閉之前有效。

multi_index：

當使用multi_index 標誌時，此屬性提供對索引的訪問。如果訪問已訪問且 has_multi_index 為 False，則引發 ValueError。

ndim： int

迭代器的維度。

nop： int

迭代器操作數的數量。

operands 操作數的元組

操作數[切片]

shape： 整數元組

shape tuple，迭代器的形狀。

value：

當前迭代中operands 的值。通常，這是一個數組標量的元組，但如果使用標誌external_loop，它是一個一維數組的元組。