N 维数组 (ndarray)

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

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

不同的 ndarrays 可以共享相同的数据，因此在一个 ndarray 中进行的更改可能在另一个 ndarray 中可见。也就是说，ndarray 可以是另一个 ndarray 的“视图”，它引用的数据由“基”ndarray 管理。ndarrays 也可以是 Python 字符串 或实现 memoryview 或 array 接口的对象拥有的内存的视图。

示例

一个 2x3 大小的二维数组，由 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 样式的连续的。

要点 1. 意味着 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	数组上的 1-D 迭代器。

数组接口

另请参见

数组接口协议.

__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.tostring([order])	tobytes 的兼容性别名，行为完全相同。
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 in indices，设置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])	查找应在a中插入v的元素以保持顺序的索引。
ndarray.nonzero()	返回非零元素的索引。
ndarray.compress(condition[, axis, out])	沿给定轴返回该数组的选定切片。
ndarray.diagonal([offset, axis1, axis2])	返回指定的对角线。

计算

许多这些方法都采用名为axis的参数。在这种情况下，

• 如果axis为None（默认值），则数组被视为一维数组，并且操作在整个数组上执行。如果self是零维数组或数组标量，则此行为也是默认行为。（数组标量是float32、float64等类型/类的实例，而零维数组是包含精确一个数组标量的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 += 3j 会转换结果以适应 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__()	用于序列化。
ndarray.__setstate__(state, /)	用于反序列化。

基本定制

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

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

ndarray.__len__(/)	返回 len(self)。
ndarray.__getitem__(key, /)	返回 self[key]。
ndarray.__setitem__(key, value, /)	将 self[key] 设置为 value。
ndarray.__contains__(key, /)	返回 key in 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类型的参数化包装器。