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，它是一个一维数组的元组。