N 维数组 (ndarray)

一个 ndarray 是一个（通常是固定大小的）多维容器，包含相同类型和大小的项。数组的维度数和项数由其 shape 定义，shape 是一个由 N 个非负整数组成的 tuple，指定每个维度的大小。数组中项的类型由一个单独的 数据类型对象 (dtype) 指定，每个 ndarray 都关联一个这样的对象。

与其他 Python 容器对象一样，ndarray 的内容可以通过 索引或切片（例如，使用 N 个整数）以及 ndarray 的方法和属性进行访问和修改。

不同的 ndarrays 可以共享相同的数据，因此在一个 ndarray 中所做的更改可能会在另一个中可见。也就是说，一个 ndarray 可以是另一个 ndarray 的“视图”，它所引用的数据由“base”ndarray 负责。ndarray 也可以是 Python 字符串 或实现 memoryview 或 数组 接口的内存的视图。

示例

在浏览器中尝试！

一个 2 x 3 的二维数组，由 4 字节整数元素组成

>>> import numpy as np

>>> x = np.array([[1, 2, 3], [4, 5, 6]], np.int32)
>>> type(x)
<class 'numpy.ndarray'>
>>> x.shape
(2, 3)
>>> x.dtype
dtype('int32')

该数组可以使用类似 Python 容器的语法进行索引

>>> # The element of x in the *second* row, *third* column, namely, 6.
>>> x[1, 2]
   6

例如，切片 可以生成数组的视图

>>> y = x[:,1]
>>> y
array([2, 5], dtype=int32)
>>> y[0] = 9 # this also changes the corresponding element in x
>>> y
array([9, 5], dtype=int32)
>>> x
array([[1, 9, 3],
       [4, 5, 6]], dtype=int32)

返回在新标签页中打开

构造数组

可以使用 数组创建例程 中详述的例程以及低级 ndarray 构造函数来构造新数组

ndarray(shape[, dtype, buffer, offset, ...])

一个数组对象表示一个多维的、同构的、固定大小的项数组。

索引数组

可以使用扩展的 Python 切片语法 array[selection] 来索引数组。类似的语法也用于访问结构化数据类型中的字段。

另请参阅

数组索引.

ndarray 的内部内存布局

ndarray 类的一个实例由一段连续的一维计算机内存（由数组或其他对象拥有）组成，并结合一个索引方案，该方案将 N 个整数映射到块中项的位置。索引可以变化的范围由数组的 shape 指定。每个项占用多少字节以及这些字节如何解释由与数组关联的 数据类型对象 定义。

内存段本质上是一维的，并且有许多不同的方案用于在一维块中排列 N 维数组的项。NumPy 是灵活的，ndarray 对象可以适应任何跨步索引方案。在跨步方案中，N 维索引 \((n_0, n_1, ..., n_{N-1})\) 对应于偏移量（以字节为单位）

\[n_{\mathrm{offset}} = \sum_{k=0}^{N-1} s_k n_k\]

从与数组关联的内存块的开头开始。这里，\(s_k\) 是指定数组步幅的整数。列主序（例如，在 Fortran 语言和 Matlab 中使用）和 行主序（在 C 中使用）方案只是特定类型的跨步方案，它们对应于可以通过步幅寻址的内存

\[s_k^{\mathrm{column}} = \mathrm{itemsize} \prod_{j=0}^{k-1} d_j , \quad s_k^{\mathrm{row}} = \mathrm{itemsize} \prod_{j=k+1}^{N-1} d_j .\]

其中 \(d_j\) = self.shape[j]。

C 和 Fortran 两种顺序都是连续的，即单段内存布局，其中内存块的每个部分都可以通过索引的某种组合进行访问。

注意

连续数组和单段数组是同义词，在整个文档中可互换使用。

虽然设置了相应标志的 C 风格和 Fortran 风格的连续数组可以用上述步幅寻址，但实际步幅可能不同。这在两种情况下会发生：

1. 如果 self.shape[k] == 1，则对于任何合法的索引 index[k] == 0。这意味着在偏移量公式中 \(n_k = 0\)，因此 \(s_k n_k = 0\)，并且 \(s_k\) = self.strides[k] 的值是任意的。

2. 如果一个数组没有元素 (self.size == 0)，则没有合法的索引，步幅也从不使用。任何没有元素的数组都可以认为是 C 风格和 Fortran 风格的连续数组。

第一点意味着 self 和 self.squeeze() 总是具有相同的连续性和 aligned 标志值。这也意味着即使是高维数组也可以同时是 C 风格和 Fortran 风格的连续数组。

如果所有元素的内存偏移量以及基本偏移量本身都是 self.itemsize 的倍数，则数组被认为是内存对齐的。理解内存对齐可以在大多数硬件上获得更好的性能。

警告

对于 C 风格的连续数组，self.strides[-1] == self.itemsize 通常不成立；对于 Fortran 风格的连续数组，self.strides[0] == self.itemsize 也通常不成立。

新 ndarrays 中的数据默认是行主序（C 序），除非另有指定，但例如，基本数组切片 通常会产生不同方案的视图。

注意

NumPy 中的几种算法适用于任意跨步数组。然而，某些算法需要单段数组。当不规则跨步数组传递给此类算法时，会自动进行复制。

数组属性

数组属性反映了数组本身的固有信息。通常，通过其属性访问数组可以获取有时设置数组的固有属性，而无需创建新数组。暴露的属性是数组的核心部分，其中只有一部分可以在不创建新数组的情况下有意义地重置。每个属性的信息如下所示。

内存布局

以下属性包含有关数组内存布局的信息

ndarray.flags	有关数组内存布局的信息。
ndarray.shape	数组维度的元组。
ndarray.strides	遍历数组时每个维度要步进的字节数元组。
ndarray.ndim	数组维度数量。
ndarray.data	指向数组数据开头的 Python 缓冲区对象。
ndarray.size	数组中的元素数量。
ndarray.itemsize	一个数组元素的字节长度。
ndarray.nbytes	数组元素消耗的总字节数。
ndarray.base	如果内存来自其他对象，则为基对象。

数据类型

另请参阅

数据类型对象

与数组关联的数据类型对象可以在 dtype 属性中找到

ndarray.dtype

数组元素的数据类型。

其他属性

ndarray.T	转置数组的视图。
ndarray.real	数组的实部。
ndarray.imag	数组的虚部。
ndarray.flat	数组上的一维迭代器。

数组接口

另请参阅

数组接口协议.

__array_interface__	数组接口的 Python 端
__array_struct__	数组接口的 C 端

ctypes 外部函数接口

ndarray.ctypes

一个简化数组与 ctypes 模块交互的对象。

数组方法

一个 ndarray 对象有许多方法，它们以某种方式操作数组或与数组一起操作，通常返回一个数组结果。这些方法在下面简要解释。（每个方法的文档字符串都有更完整的描述。）

对于以下方法，在 numpy 中也有对应的函数：all, any, argmax, argmin, argpartition, argsort, choose, clip, compress, copy, cumprod, cumsum, diagonal, imag, max, mean, min, nonzero, partition, prod, put, ravel, real, repeat, reshape, round, searchsorted, sort, squeeze, std, sum, swapaxes, take, trace, transpose, var。

数组转换

ndarray.item(*args)	将数组元素复制到标准 Python 标量并返回。
ndarray.tolist()	将数组返回为 a.ndim 级深度的嵌套 Python 标量列表。
ndarray.tobytes([order])	构造包含数组原始数据字节的 Python 字节对象。
ndarray.tofile(fid[, sep, format])	将数组作为文本或二进制（默认）写入文件。
ndarray.dump(file)	将数组的 pickle 转储到指定文件。
ndarray.dumps()	将数组的 pickle 返回为字符串。
ndarray.astype(dtype[, order, casting, ...])	数组的副本，转换为指定类型。
ndarray.byteswap([inplace])	交换数组元素的字节。
ndarray.copy([order])	返回数组的副本。
ndarray.view([dtype][, type])	具有相同数据的新数组视图。
ndarray.getfield(dtype[, offset])	将给定数组的字段作为特定类型返回。
ndarray.setflags([write, align, uic])	分别设置数组标志 WRITEABLE、ALIGNED、WRITEBACKIFCOPY。
ndarray.fill(value)	用标量值填充数组。

形状操作

对于 reshape、resize 和 transpose，单个元组参数可以替换为 n 个整数，这些整数将被解释为 n 元组。

ndarray.reshape(shape, /, *[, order, copy])	返回包含相同数据但具有新形状的数组。
ndarray.resize(new_shape[, refcheck])	就地改变数组的形状和大小。
ndarray.transpose(*axes)	返回轴转置后的数组视图。
ndarray.swapaxes(axis1, axis2)	返回一个交换了 axis1 和 axis2 的数组视图。
ndarray.flatten([order])	返回折叠为一维的数组副本。
ndarray.ravel([order])	返回一个扁平化的数组。
ndarray.squeeze([axis])	从 a 中移除长度为一的轴。

项选择和操作

对于接受 axis 关键字的数组方法，它默认为 None。如果 axis 为 None，则将数组视为一维数组并对整个数组执行操作。对于 axis 的任何其他值，表示操作应沿给定维度进行。

ndarray.take(indices[, axis, out, mode])	返回从 a 中给定索引处的元素构成的数组。
ndarray.put(indices, values[, mode])	对于索引中的所有 n，设置 a.flat[n] = values[n]。
ndarray.repeat(repeats[, axis])	重复数组元素。
ndarray.choose(choices[, out, mode])	使用索引数组从一组选择中构造一个新数组。
ndarray.sort([axis, kind, order])	就地排序数组。
ndarray.argsort([axis, kind, order])	返回将排序此数组的索引。
ndarray.partition(kth[, axis, kind, order])	部分排序数组中的元素，使得第 k 个位置的元素值处于排序数组中它应有的位置。
ndarray.argpartition(kth[, axis, kind, order])	返回将分区此数组的索引。
ndarray.searchsorted(v[, side, sorter])	查找 v 的元素应插入 a 中以保持顺序的索引。
ndarray.nonzero()	返回非零元素的索引。
ndarray.compress(condition[, axis, out])	返回沿给定轴的此数组的选定切片。
ndarray.diagonal([offset, axis1, axis2])	返回指定的对角线。

计算

这些方法中有许多接受名为 axis 的参数。在这种情况下，

• 如果 axis 为 None（默认值），则将数组视为一维数组，并对整个数组执行操作。如果 self 是 0 维数组或数组标量（数组标量是 float32、float64 等类型/类的实例，而 0 维数组是恰好包含一个数组标量的 ndarray 实例），此行为也是默认的。

• 如果 axis 是一个整数，则操作在给定轴上执行（对于沿给定轴可以创建的每个一维子数组）。

axis 参数的示例

在浏览器中尝试！

一个 3 x 3 x 3 的三维数组，对其三个轴分别求和

>>> import numpy as np

>>> x = np.arange(27).reshape((3,3,3))
>>> x
array([[[ 0,  1,  2],
      [ 3,  4,  5],
      [ 6,  7,  8]],
      [[ 9, 10, 11],
      [12, 13, 14],
      [15, 16, 17]],
      [[18, 19, 20],
      [21, 22, 23],
      [24, 25, 26]]])
>>> x.sum(axis=0)
array([[27, 30, 33],
      [36, 39, 42],
      [45, 48, 51]])
>>> # for sum, axis is the first keyword, so we may omit it,
>>> # specifying only its value
>>> x.sum(0), x.sum(1), x.sum(2)
(array([[27, 30, 33],
      [36, 39, 42],
      [45, 48, 51]]),
array([[ 9, 12, 15],
      [36, 39, 42],
      [63, 66, 69]]),
array([[ 3, 12, 21],
      [30, 39, 48],
      [57, 66, 75]]))

返回在新标签页中打开

参数 dtype 指定了规约操作（如求和）应在其上进行的数据类型。默认的规约数据类型与 self 的数据类型相同。为避免溢出，使用更大的数据类型执行规约可能很有用。

对于几种方法，还可以提供可选的 out 参数，结果将放置在给定的输出数组中。out 参数必须是 ndarray 并具有相同数量的元素。它可以具有不同的数据类型，在这种情况下将执行类型转换。

ndarray.max([axis, out, keepdims, initial, ...])	返回沿给定轴的最大值。
ndarray.argmax([axis, out, keepdims])	返回沿给定轴的最大值的索引。
ndarray.min([axis, out, keepdims, initial, ...])	返回沿给定轴的最小值。
ndarray.argmin([axis, out, keepdims])	返回沿给定轴的最小值的索引。
ndarray.clip([min, max, out])	返回其值限制在 [min, max] 范围内的数组。
ndarray.conj()	所有元素的复共轭。
ndarray.round([decimals, out])	返回 a，其中每个元素都四舍五入到给定的小数位数。
ndarray.trace([offset, axis1, axis2, dtype, out])	返回数组对角线上的和。
ndarray.sum([axis, dtype, out, keepdims, ...])	返回数组元素沿给定轴的和。
ndarray.cumsum([axis, dtype, out])	返回元素沿给定轴的累积和。
ndarray.mean([axis, dtype, out, keepdims, where])	返回数组元素沿给定轴的平均值。
ndarray.var([axis, dtype, out, ddof, ...])	返回数组元素沿给定轴的方差。
ndarray.std([axis, dtype, out, ddof, ...])	返回数组元素沿给定轴的标准差。
ndarray.prod([axis, dtype, out, keepdims, ...])	返回数组元素沿给定轴的乘积。
ndarray.cumprod([axis, dtype, out])	返回元素沿给定轴的累积乘积。
ndarray.all([axis, out, keepdims, where])	如果所有元素都评估为 True，则返回 True。
ndarray.any([axis, out, keepdims, where])	如果 a 的任何元素评估为 True，则返回 True。

算术、矩阵乘法和比较操作

对 ndarrays 的算术和比较操作定义为逐元素操作，通常会产生 ndarray 对象作为结果。

每个算术运算（+、-、*、/、//、%、divmod()、** 或 pow()、<<、>>、&、^、|、~）和比较运算（==、<、>、<=、>=、!=）都等价于 NumPy 中相应的通用函数（或简称ufunc）。有关更多信息，请参见 通用函数 部分。

比较运算符

ndarray.__lt__(value, /)	返回 self<value。
ndarray.__le__(value, /)	返回 self<=value。
ndarray.__gt__(value, /)	返回 self>value。
ndarray.__ge__(value, /)	返回 self>=value。
ndarray.__eq__(value, /)	返回 self==value。
ndarray.__ne__(value, /)	返回 self!=value。

数组的真值 (bool())

ndarray.__bool__(/)

如果 self 为 True，否则为 False

注意

数组的真值测试会调用 ndarray.__bool__，如果数组中的元素数量不为 1，则会引发错误，因为此类数组的真值是模糊的。在这种情况下，请使用 .any() 和 .all() 以明确含义。（如果您想检查数组是否为空，例如使用 .size > 0。）

一元操作

ndarray.__neg__(/)	-self
ndarray.__pos__(/)	+self
ndarray.__abs__(self)
ndarray.__invert__(/)	~self

算术

ndarray.__add__(value, /)	返回 self+value。
ndarray.__sub__(value, /)	返回 self-value。
ndarray.__mul__(value, /)	返回 self*value。
ndarray.__truediv__(value, /)	返回 self/value。
ndarray.__floordiv__(value, /)	返回 self//value。
ndarray.__mod__(value, /)	返回 self%value。
ndarray.__divmod__(value, /)	返回 divmod(self, value)。
ndarray.__pow__(value[, mod])	返回 pow(self, value, mod)。
ndarray.__lshift__(value, /)	返回 self<<value。
ndarray.__rshift__(value, /)	返回 self>>value。
ndarray.__and__(value, /)	返回 self&value。
ndarray.__or__(value, /)	返回 self|value。
ndarray.__xor__(value, /)	返回 self^value。

注意

• pow 的任何第三个参数都会被静默忽略，因为底层 ufunc 只接受两个参数。

• 由于 ndarray 是一个内置类型（用 C 编写），因此 __r{op}__ 特殊方法没有直接定义。

• 用于实现数组的许多算术特殊方法的函数可以使用 __array_ufunc__ 进行修改。

算术，就地操作

ndarray.__iadd__(value, /)	返回 self+=value。
ndarray.__isub__(value, /)	返回 self-=value。
ndarray.__imul__(value, /)	返回 self*=value。
ndarray.__itruediv__(value, /)	返回 self/=value。
ndarray.__ifloordiv__(value, /)	返回 self//=value。
ndarray.__imod__(value, /)	返回 self%=value。
ndarray.__ipow__(value, /)	返回 self**=value。
ndarray.__ilshift__(value, /)	返回 self<<=value。
ndarray.__irshift__(value, /)	返回 self>>=value。
ndarray.__iand__(value, /)	返回 self&=value。
ndarray.__ior__(value, /)	返回 self|=value。
ndarray.__ixor__(value, /)	返回 self^=value。

警告

就地操作将使用两个操作数的数据类型所决定的精度执行计算，但会静默向下转换结果（如果需要），以便其可以重新适应数组。因此，对于混合精度计算，A {op}= B 可能与 A = A {op} B 不同。例如，假设 a = ones((3,3))。那么，a += 3j 与 a = a + 3j 不同：虽然它们都执行相同的计算，但 a += 3 将结果转换为适合 a 的类型，而 a = a + 3j 则将名称 a 重新绑定到结果。

矩阵乘法

ndarray.__matmul__(value, /)

返回 self@value。

注意

矩阵运算符 @ 和 @= 是在 Python 3.5 中根据 PEP 465 引入的，并且 @ 运算符已在 NumPy 1.10.0 中引入。更多信息可以在 matmul 文档中找到。

特殊方法

对于标准库函数

ndarray.__copy__()	当对数组调用 copy.copy 时使用。
ndarray.__deepcopy__(memo, /)	当对数组调用 copy.deepcopy 时使用。
ndarray.__reduce__()	用于 pickle 序列化。
ndarray.__setstate__(state, /)	用于 unpickling。

基本自定义

ndarray.__new__(*args, **kwargs)
ndarray.__array__([dtype], *[, copy])	对于 dtype 参数，如果未给定 dtype 或其与数组的数据类型匹配，则返回 self 的新引用。
ndarray.__array_wrap__(array[, context], /)	返回 array 的视图，其类型与 self 相同。

容器自定义：（参见 索引）

ndarray.__len__(/)	返回 len(self)。
ndarray.__getitem__(key, /)	返回 self[key]。
ndarray.__setitem__(key, value, /)	将 self[key] 设置为 value。
ndarray.__contains__(key, /)	返回 key 是否在 self 中。

转换；操作 int()、float() 和 complex()。它们只适用于含有一个元素的数组，并返回相应的标量。

ndarray.__int__(self)
ndarray.__float__(self)
ndarray.__complex__

字符串表示

ndarray.__str__(/)	返回 str(self)。
ndarray.__repr__(/)	返回 repr(self)。

类型化实用方法

ndarray.__class_getitem__(item, /)

返回 ndarray 类型的一个参数化包装器。