标准数组子类#

注意

对 numpy.ndarray 进行子类化是可能的，但如果您的目标是创建具有*修改*行为的数组，例如 Dask 数组用于分布式计算和 CuPy 数组用于基于 GPU 的计算，则不建议进行子类化。相反，建议使用 NumPy 的调度机制。

如果需要，可以从ndarray 继承（在 Python 或 C 中）。因此，它可以成为许多有用类的基础。通常，是子类化数组对象还是简单地将核心数组组件用作新类的内部部分，这是一个艰难的决定，可能仅仅是个人选择的问题。NumPy 提供了几种工具来简化新对象与其他数组对象的交互方式，因此最终选择可能并不重要。一种简化问题的方法是问问自己，您感兴趣的对象是否可以替换为单个数组，或者它是否真正需要两个或多个数组作为其核心。

请注意，asarray 始终返回基类 ndarray。如果您确信您的数组对象使用可以处理 ndarray 的任何子类，那么可以使用asanyarray 允许子类更清晰地传播到您的子例程中。原则上，子类可以重新定义数组的任何方面，因此在严格的指导下，asanyarray 很少有用。但是，大多数数组对象的子类不会重新定义数组对象的某些方面，例如缓冲区接口或数组的属性。但是，一个重要的例子说明了为什么您的子例程可能无法处理数组的任意子类，即矩阵重新定义了“*”运算符，使其成为矩阵乘法，而不是逐元素乘法。

特殊属性和方法#

参见

ndarray 的子类化

NumPy 提供了几个可以自定义的钩子

class.__array_ufunc__(ufunc, method, *inputs, **kwargs)#

版本 1.13 中的新功能。

任何类，无论是否为 ndarray 子类，都可以定义此方法或将其设置为 None 以覆盖 NumPy 的 ufunc 的行为。这与 Python 的 __mul__ 和其他二元运算例程非常相似。

  • ufunc 是调用的 ufunc 对象。

  • method 是一个字符串，指示调用了哪个 Ufunc 方法（"__call__"、"reduce"、"reduceat"、"accumulate"、"outer"、"inner" 之一）。

  • inputs 是 ufunc 的输入参数元组。

  • kwargs 是一个字典，包含 ufunc 的可选输入参数。如果给定，任何 out 参数（位置参数和关键字参数）都作为tuple 传递到 kwargs 中。有关详细信息，请参见通用函数 (ufunc) 中的讨论。

此方法应返回操作的结果，或 NotImplemented（如果请求的操作未实现）。

如果输入、输出或 where 参数之一具有__array_ufunc__ 方法，则执行该方法而不是 ufunc。如果多个参数实现了__array_ufunc__，则按以下顺序尝试它们：子类优先于超类，输入优先于输出，输出优先于 where，否则从左到右。第一个返回非NotImplemented 的例程决定结果。如果所有 __array_ufunc__ 操作都返回 NotImplemented，则会引发 TypeError。

注意

我们打算将 NumPy 函数重新实现为（泛化的）Ufunc，在这种情况下，它们将可以通过 __array_ufunc__ 方法覆盖。一个主要候选者是matmul，它目前不是 Ufunc，但可以相对容易地重写为（一组）泛化 Ufunc。对于 median、amin 和 argsort 等函数，也可能发生这种情况。

与 Python 中的其他一些特殊方法（例如 __hash__ 和 __iter__）一样，可以通过设置 __array_ufunc__ = None 来表明您的类不支持 ufunc。当对设置 __array_ufunc__ = None 的对象调用 ufunc 时，ufunc 始终会引发 TypeError。

存在__array_ufunc__ 还会影响 ndarray 如何处理 arr + obj 和 arr < obj 等二元运算（当 arr 为 ndarray 且 obj 为自定义类的实例时）。有两种可能性。如果 obj.__array_ufunc__ 存在且不为 None，则 ndarray.__add__ 及其朋友将委托给 ufunc 机制，这意味着 arr + obj 变为 np.add(arr, obj)，然后 add 调用 obj.__array_ufunc__。如果您想定义一个像数组一样的对象，这将非常有用。

或者，如果obj.__array_ufunc__被设置为 None，则作为特殊情况，诸如ndarray.__add__之类的特殊方法会注意到这一点，并*无条件地*引发TypeError。如果您想创建通过二元运算与数组交互但本身不是数组的对象，这很有用。例如，一个单位处理系统可能有一个表示“米”单位的对象m，并希望支持语法arr * m来表示该数组具有“米”的单位，但不希望通过 ufunc 或其他方式与数组进行交互。这可以通过设置__array_ufunc__ = None并定义__mul__和__rmul__方法来完成。（请注意，这意味着编写一个始终返回NotImplemented的__array_ufunc__与设置__array_ufunc__ = None并不完全相同：在前一种情况下，arr + obj将引发TypeError，而在后一种情况下，可以定义一个__radd__方法来防止这种情况。）

以上情况不适用于就地运算符，对于就地运算符，ndarray从不返回NotImplemented。因此，arr += obj将始终导致TypeError。这是因为对于数组来说，就地操作不能泛化地用简单的逆向操作来代替。（例如，默认情况下，arr += obj将被转换为arr = arr + obj，即arr将被替换，这与就地数组操作的预期结果相反。）

注意

如果您定义了__array_ufunc__

  • 如果您不是ndarray的子类，我们建议您的类定义诸如__add__和__lt__之类的特殊方法，这些方法像 ndarray 一样委托给 ufunc。实现这一点的一个简单方法是从NDArrayOperatorsMixin继承。

  • 如果您是ndarray的子类，我们建议您将所有覆盖逻辑放在__array_ufunc__中，而不要同时覆盖特殊方法。这确保类层次结构只在一个地方确定，而不是分别由 ufunc 机制和二元运算规则确定（这优先考虑子类的特殊方法；另一种强制只在一个地方实现层次结构的方法是将__array_ufunc__设置为 None，这将显得非常意外，因此令人困惑，因为这样一来，子类将无法与 ufunc 进行任何交互）。

  • ndarray定义了自己的__array_ufunc__，它在没有参数具有覆盖的情况下评估 ufunc，并在其他情况下返回NotImplemented。这对那些__array_ufunc__将自身类的任何实例转换为ndarray的子类来说可能很有用：它可以使用super().__array_ufunc__(*inputs, **kwargs)将这些实例传递给其超类，并在可能的反向转换之后返回结果。这种做法的优势在于它确保可以拥有扩展行为的子类层次结构。有关详细信息，请参见子类化 ndarray。

class.__array_function__(func, types, args, kwargs)#

版本 1.16 中的新增功能。

  • func 是 NumPy 公开 API 公开的任意可调用对象，它以 func(*args, **kwargs) 的形式被调用。

  • types 是从原始 NumPy 函数调用中收集的collections.abc.Collection，它包含实现 __array_function__ 的唯一参数类型。

  • 元组 args 和字典 kwargs 直接从原始调用中传递过来。

为了方便 __array_function__ 的实现者，types 提供了所有具有 '__array_function__' 属性的参数类型。这允许实现者快速识别他们应该推迟到其他参数上的 __array_function__ 实现的情况。实现不应该依赖于 types 的迭代顺序。

大多数 __array_function__ 的实现将从两个检查开始

  1. 给定的函数是我们知道如何重载的吗？

  2. 所有参数都是我们知道如何处理的类型吗？

如果这些条件成立，__array_function__ 应该返回从调用其对 func(*args, **kwargs) 的实现中获得的结果。否则，它应该返回哨兵值 NotImplemented，表明这些类型没有实现该函数。

对 __array_function__ 的返回值没有一般要求，尽管大多数合理的实现可能应该返回与函数参数之一类型相同的数组。

为 __array_function__ 实现定义自定义装饰器（下面的 implements）可能也很方便。

HANDLED_FUNCTIONS = {}

class MyArray:
    def __array_function__(self, func, types, args, kwargs):
        if func not in HANDLED_FUNCTIONS:
            return NotImplemented
        # Note: this allows subclasses that don't override
        # __array_function__ to handle MyArray objects
        if not all(issubclass(t, MyArray) for t in types):
            return NotImplemented
        return HANDLED_FUNCTIONS[func](*args, **kwargs)

def implements(numpy_function):
    """Register an __array_function__ implementation for MyArray objects."""
    def decorator(func):
        HANDLED_FUNCTIONS[numpy_function] = func
        return func
    return decorator

@implements(np.concatenate)
def concatenate(arrays, axis=0, out=None):
    ...  # implementation of concatenate for MyArray objects

@implements(np.broadcast_to)
def broadcast_to(array, shape):
    ...  # implementation of broadcast_to for MyArray objects

请注意，__array_function__ 实现不需要包含对应 NumPy 函数的所有可选参数（例如，上面的 broadcast_to 省略了无关的 subok 参数）。只有在 NumPy 函数调用中显式使用可选参数时，才会将其传递给 __array_function__。

就像内置特殊方法（例如 __add__）一样，正确编写的 __array_function__ 方法在遇到未知类型时应该始终返回 NotImplemented。否则，如果操作还包含您的对象之一，则将无法从另一个对象正确覆盖 NumPy 函数。

在大多数情况下，使用 __array_function__ 进行分派的规则与使用 __array_ufunc__ 的规则相匹配。特别是

  • NumPy 将从所有指定输入中收集 __array_function__ 的实现，并按顺序调用它们：子类先于超类，否则从左到右。请注意，在涉及子类的某些边缘情况下，这与Python 的当前行为略有不同。

  • __array_function__ 的实现通过返回除 NotImplemented 之外的任何值来表明它们可以处理该操作。

  • 如果所有 __array_function__ 方法都返回 NotImplemented，NumPy 将引发 TypeError。

如果没有 __array_function__ 方法，NumPy 将默认调用其自己的实现，该实现旨在用于 NumPy 数组。例如，当所有类数组参数都是 Python 数字或列表时，会出现这种情况。（NumPy 数组确实有一个 __array_function__ 方法，如下所示，但如果除 NumPy 数组子类之外的任何参数实现 __array_function__，它将始终返回 NotImplemented。）

与当前__array_ufunc__行为的一个偏差是，NumPy 仅会在每个唯一类型的第一个参数上调用 __array_function__。这与 Python 的调用反射方法的规则相匹配，并且这可以确保即使存在大量重载参数，检查重载也能有可接受的性能。

class.__array_finalize__(obj)#

每当系统从obj内部分配一个新的数组时，都会调用此方法，其中obj是ndarray的子类（子类型）。它可以用于在构造后更改self的属性（例如，确保一个 2 维矩阵），或者从“父”更新元信息。子类继承此方法的默认实现，该实现不执行任何操作。

class.__array_wrap__(array, context=None, return_scalar=False)#

在每个ufunc结束时，将使用最高数组优先级的输入对象或指定输出对象（如果存在）调用此方法。将传递 ufunc 计算的数组，并且返回的值将传递给用户。子类继承此方法的默认实现，该实现将数组转换为对象类的新实例。子类可以选择使用此方法将输出数组转换为子类的实例，并在将数组返回给用户之前更新元数据。

NumPy 还可以从非 ufunc 调用此函数，而无需上下文，以允许保留子类信息。

在版本 2.0 中更改: return_scalar现在被传递为 False（通常）或 True，表示 NumPy 将返回一个标量。子类可以忽略该值，或者返回 array[()] 以更像 NumPy 那样运行。

注意

希望最终弃用此方法，转而使用 func:__array_ufunc__ 来处理 ufunc（以及 __array_function__ 来处理一些其他函数，如 numpy.squeeze）。

class.__array_priority__#

此属性的值用于确定在存在多个可能的返回对象 Python 类型的情况下返回哪种类型的对象。子类继承此属性的默认值为 0.0。

注意

对于 ufunc，希望最终弃用此方法，转而使用 __array_ufunc__。

class.__array__(dtype=None, copy=None)#

如果在对象上定义，则应返回一个 ndarray。如果将实现此接口的对象传递给这些函数，则此方法会被像 np.array() 这样的数组强制转换函数调用。__array__ 的第三方实现必须接受 dtype 和 copy 关键字参数，因为忽略它们可能会破坏第三方代码或 NumPy 本身。

  • dtype 是返回数组的数据类型。

  • copy 是一个可选布尔值，指示是否应返回副本。对于 True，始终应创建副本，对于 None，仅在需要时创建副本（例如，由于传递了 dtype 值），对于 False，永远不应该创建副本（如果仍然需要创建副本，则应引发适当的异常）。

请参阅与 NumPy 的互操作性，了解协议层次结构，其中__array__ 是最古老且最不理想的。

注意

如果具有 __array__ 方法的类（ndarray 子类或非子类）用作 ufunc 的输出对象，则结果不会写入由 __array__ 返回的对象。此做法将返回 TypeError。

矩阵对象#

注意

强烈建议不要使用矩阵子类。如下所述，它使得编写一致处理矩阵和普通数组的函数变得非常困难。目前，它们主要用于与 scipy.sparse 交互。我们希望为此提供替代方案，并最终删除 matrix 子类。

matrix 对象继承自 ndarray，因此它们具有与 ndarray 相同的属性和方法。但是，矩阵对象有六个重要的区别，这可能会导致你在使用矩阵时却期望它们像数组那样运行时出现意外结果。

  1. 矩阵对象可以使用字符串表示法创建，以允许使用 Matlab 风格的语法，其中空格分隔列，分号（';'）分隔行。

  2. 矩阵对象始终是二维的。这具有深远的影响，因为 m.ravel() 仍然是二维的（第一维为 1），并且项选择返回二维对象，因此序列行为与数组 fundamentally different。

  3. 矩阵对象覆盖乘法，使其成为矩阵乘法。确保你理解这一点，因为你可能希望接收矩阵的函数。特别是考虑到 asanyarray(m) 在 m 是矩阵时会返回一个矩阵。

  4. 矩阵对象覆盖幂运算，使其成为矩阵的幂运算。使用 asanyarray(…) 获取数组对象的函数内部使用幂运算的相同警告适用于这种情况。

  5. 矩阵对象的默认 __array_priority__ 为 10.0，因此与 ndarray 的混合操作始终会产生矩阵。

  6. 矩阵具有使计算更容易的特殊属性。这些是

    matrix.T

    返回矩阵的转置。

    matrix.H

    返回self 的（复数）共轭转置。

    matrix.I

    返回可逆self 的（乘法）逆。

    matrix.A

    将self 作为 ndarray 对象返回。

警告

矩阵对象分别覆盖乘法“*”和幂运算“**”，使其成为矩阵乘法和矩阵幂运算。如果你的子例程可以接受子类，并且你没有转换为基类数组，那么你必须使用 ufunc multiply 和 power 来确保你对所有输入执行了正确的操作。

矩阵类是 ndarray 的 Python 子类，可以作为构建自己的 ndarray 子类的方式参考。矩阵可以从其他矩阵、字符串以及任何可以转换为 ndarray 的内容创建。名称“mat”是 NumPy 中“matrix”的别名。

matrix(data[, dtype, copy])

从类数组对象或数据字符串返回矩阵。

asmatrix(data[, dtype])

将输入解释为矩阵。

bmat(obj[, ldict, gdict])

从字符串、嵌套序列或数组构建矩阵对象。

示例 1：从字符串创建矩阵

>>> import numpy as np
>>> a = np.asmatrix('1 2 3; 4 5 3')
>>> print((a*a.T).I)
  [[ 0.29239766 -0.13450292]
   [-0.13450292  0.08187135]]

示例 2：从嵌套序列创建矩阵

>>> import numpy as np
>>> np.asmatrix([[1,5,10],[1.0,3,4j]])
matrix([[  1.+0.j,   5.+0.j,  10.+0.j],
        [  1.+0.j,   3.+0.j,   0.+4.j]])

示例 3：从数组创建矩阵

>>> import numpy as np
>>> np.asmatrix(np.random.rand(3,3)).T
matrix([[4.17022005e-01, 3.02332573e-01, 1.86260211e-01],
        [7.20324493e-01, 1.46755891e-01, 3.45560727e-01],
        [1.14374817e-04, 9.23385948e-02, 3.96767474e-01]])

内存映射文件数组#

内存映射文件用于读取和/或修改具有规则布局的大文件的较小子段，而无需将整个文件读入内存。ndarray 的一个简单子类使用内存映射文件作为数组的数据缓冲区。对于小型文件，将整个文件读入内存的开销通常并不明显，但是对于大型文件，使用内存映射可以节省大量的资源。

内存映射文件数组有一个额外的 方法（除了它们从 ndarray 继承的方法之外）：.flush()，用户必须手动调用此方法以确保对数组的任何更改都实际写入磁盘。

memmap(filename[, dtype, mode, offset, ...])

创建指向磁盘上二进制文件中存储的数组的内存映射。

memmap.flush()

将数组中的任何更改写入磁盘上的文件。

示例

>>> import numpy as np

>>> a = np.memmap('newfile.dat', dtype=float, mode='w+', shape=1000)
>>> a[10] = 10.0
>>> a[30] = 30.0
>>> del a

>>> b = np.fromfile('newfile.dat', dtype=float)
>>> print(b[10], b[30])
10.0 30.0

>>> a = np.memmap('newfile.dat', dtype=float)
>>> print(a[10], a[30])
10.0 30.0

字符数组（numpy.char)#

参见

创建字符数组 (numpy.char)

注意

chararray 类是为了向后兼容 Numarray 而存在的，不建议用于新开发。从 numpy 1.4 开始，如果需要字符串数组，建议使用 dtype object_、bytes_ 或 str_ 的数组，并使用 numpy.char 模块中的免费函数进行快速矢量化字符串操作。

这些是 str_ 类型或 bytes_ 类型的增强数组。这些数组继承自 ndarray，但专门定义了在（广播）逐元素基础上的 +、* 和 % 操作。这些操作在标准的字符类型 ndarray 上不可用。此外，chararray 具有所有标准的 str（以及 bytes）方法，并在逐元素基础上执行它们。创建 chararray 的最简单方法可能是使用 self.view(chararray)，其中 self 是一个 str 或 unicode 数据类型的 ndarray。但是，也可以使用 chararray 构造函数或通过 numpy.char.array 函数来创建 chararray。

char.chararray(shape[, itemsize, unicode, ...])

提供对字符串和 unicode 值数组的便捷视图。

char.array(obj[, itemsize, copy, unicode, order])

创建一个 chararray。

与标准 str 数据类型的 ndarray 的另一个区别是，chararray 继承了 Numarray 引入的功能，即数组中任何元素末尾的空白将在项检索和比较操作中被忽略。

记录数组#

参见

创建记录数组、数据类型例程、数据类型对象 (dtype)。

NumPy 提供了 recarray 类，它允许使用属性访问结构化数组的字段，以及相应的标量数据类型对象 record。

recarray(shape[, dtype, buf, offset, ...])

构造一个 ndarray，允许使用属性访问字段。

记录

一个数据类型标量，允许将字段访问作为属性查找。

注意

pandas DataFrame 比记录数组更强大。如果可能，请使用 pandas DataFrame 代替。

掩码数组 (numpy.ma)#

参见

掩码数组

标准容器类#

为了向后兼容，并且作为标准“容器”类，Numeric 中的 UserArray 被移植到 NumPy 并命名为 numpy.lib.user_array.container。容器类是一个 Python 类，其 self.array 属性是一个 ndarray。与 ndarray 本身相比，使用 numpy.lib.user_array.container 进行多重继承可能更容易，因此它默认包含在内。除了提到它的存在之外，这里没有对其进行记录，因为如果您能够直接使用 ndarray 类，我们建议您这样做。

numpy.lib.user_array.container(data[, ...])

用于轻松多重继承的标准容器类。

数组迭代器#

迭代器是数组处理中一个强大的概念。本质上，迭代器实现了一个通用的 for 循环。如果 myiter 是一个迭代器对象，则 Python 代码

for val in myiter:
    ...
    some code involving val
    ...

重复调用 val = next(myiter)，直到迭代器引发 StopIteration。有几种方法可以迭代数组，这些方法可能很有用：默认迭代、扁平迭代和 \(N\) 维枚举。

默认迭代#

ndarray 对象的默认迭代器是序列类型的默认 Python 迭代器。因此，当数组对象本身用作迭代器时。默认行为等效于

for i in range(arr.shape[0]):
    val = arr[i]

此默认迭代器从数组中选择一个维数为 \(N-1\) 的子数组。这对于定义递归算法来说可能是一个有用的结构。要遍历整个数组，需要 \(N\) 个 for 循环。

>>> import numpy as np
>>> a = np.arange(24).reshape(3,2,4) + 10
>>> for val in a:
...     print('item:', val)
item: [[10 11 12 13]
[14 15 16 17]]
item: [[18 19 20 21]
[22 23 24 25]]
item: [[26 27 28 29]
[30 31 32 33]]

扁平迭代#

ndarray.flat

数组上的一个一维迭代器。

如前所述，ndarray 对象的 flat 属性返回一个迭代器，该迭代器将以 C 样式连续顺序遍历整个数组。

>>> import numpy as np
>>> a = np.arange(24).reshape(3,2,4) + 10
>>> for i, val in enumerate(a.flat):
...     if i%5 == 0: print(i, val)
0 10
5 15
10 20
15 25
20 30

在这里，我使用了内置的 enumerate 迭代器来返回迭代器索引以及值。

N 维枚举#

ndenumerate(arr)

多维索引迭代器。

有时在迭代时获取 N 维索引可能很有用。ndenumerate 迭代器可以实现这一点。

>>> import numpy as np
>>> for i, val in np.ndenumerate(a):
...     if sum(i)%5 == 0: print(i, val)
(0, 0, 0) 10
(1, 1, 3) 25
(2, 0, 3) 29
(2, 1, 2) 32

广播的迭代器#

广播

生成一个模仿广播的对象。

广播的一般概念也可以通过使用 broadcast 迭代器从 Python 获得。此对象接受 \(N\) 个对象作为输入，并返回一个迭代器，该迭代器返回元组，在广播结果中提供每个输入序列元素。

>>> import numpy as np
>>> for val in np.broadcast([[1, 0], [2, 3]], [0, 1]):
...     print(val)
(np.int64(1), np.int64(0))
(np.int64(0), np.int64(1))
(np.int64(2), np.int64(0))
(np.int64(3), np.int64(1))
在此页面上