NumPy-1-26-中文文档-十八-

NumPy 1.26 中文文档（十八）

原文：numpy.org/doc/

统计学

原文：numpy.org/doc/1.26/reference/routines.statistics.html

顺序统计

ptp(a[, axis, out, keepdims])	沿轴的值范围（最大值 - 最小值）。
percentile(a, q[, axis, out, ...])	计算沿指定轴的数据的第 q 个百分位数。
nanpercentile(a, q[, axis, out, ...])	计算沿指定轴的数据的第 q 个百分位数，同时忽略 nan 值。
quantile(a, q[, axis, out, overwrite_input, ...])	计算沿指定轴的数据的第 q 个分位数。
nanquantile(a, q[, axis, out, ...])	计算沿指定轴的数据的第 q 个分位数，同时忽略 nan 值。

平均值和方差

median(a[, axis, out, overwrite_input, keepdims])	计算沿指定轴的中位数。
average(a[, axis, weights, returned, keepdims])	计算沿指定轴的加权平均值。
mean(a[, axis, dtype, out, keepdims, where])	计算沿指定轴的算术平均值。
std(a[, axis, dtype, out, ddof, keepdims, where])	计算沿指定轴的标准差。
var(a[, axis, dtype, out, ddof, keepdims, where])	计算沿指定轴的方差。
nanmedian(a[, axis, out, overwrite_input, ...])	计算沿指定轴的中位数，同时忽略 NaN 值。
nanmean(a[, axis, dtype, out, keepdims, where])	计算沿指定轴的算术平均值，忽略 NaN 值。
nanstd(a[, axis, dtype, out, ddof, ...])	计算沿指定轴的标准差，同时忽略 NaN 值。
nanvar(a[, axis, dtype, out, ddof, ...])	计算沿指定轴的方差，同时忽略 NaN 值。

相关性

corrcoef(x[, y, rowvar, bias, ddof, dtype])	返回 Pearson 积矩相关系数。
correlate(a, v[, mode])	计算两个一维序列的交叉相关性。
cov(m[, y, rowvar, bias, ddof, fweights, ...])	给定数据和权重，估计协方差矩阵。

直方图

histogram(a[, bins, range, density, weights])	计算数据集的直方图。
histogram2d(x, y[, bins, range, density, ...])	计算两个数据样本的二维直方图。
histogramdd(sample[, bins, range, density, ...])	计算一些数据的多维直方图。
bincount(x, /[, weights, minlength])	计算非负整数数组中每个值的出现次数。
histogram_bin_edges(a[, bins, range, weights])	仅计算由 histogram 函数使用的箱的边缘的函数。
digitize(x, bins[, right])	返回输入数组中每个值所属的箱的索引。

顺序统计量

ptp(a[, axis, out, keepdims])	沿轴的值范围（最大值 - 最小值）。
percentile(a, q[, axis, out, ...])	计算沿指定轴的数据的第 q 个百分位数。
nanpercentile(a, q[, axis, out, ...])	计算沿指定轴的数据的第 q 个百分位数，同时忽略 nan 值。
quantile(a, q[, axis, out, overwrite_input, ...])	计算沿指定轴的数据的第 q 个分位数。
nanquantile(a, q[, axis, out, ...])	计算沿指定轴的数据的第 q 个分位数，同时忽略 nan 值。

平均值和方差

median(a[, axis, out, overwrite_input, keepdims])	沿指定轴计算中位数。
average(a[, axis, weights, returned, keepdims])	沿指定轴计算加权平均值。
mean(a[, axis, dtype, out, keepdims, where])	沿指定轴计算算术平均值。
std(a[, axis, dtype, out, ddof, keepdims, where])	沿指定轴计算标准差。
var(a[, axis, dtype, out, ddof, keepdims, where])	沿指定轴计算方差。
nanmedian(a[, axis, out, overwrite_input, ...])	计算沿指定轴的中位数，忽略 NaN 值。
nanmean(a[, axis, dtype, out, keepdims, where])	计算沿指定轴的算术平均值，忽略 NaN 值。
nanstd(a[, axis, dtype, out, ddof, ...])	计算沿指定轴的标准差，忽略 NaN 值。
nanvar(a[, axis, dtype, out, ddof, ...])	计算沿指定轴的方差，忽略 NaN 值。

Correlating

corrcoef(x[, y, rowvar, bias, ddof, dtype])	返回皮尔逊积矩相关系数。
correlate(a, v[, mode])	两个一维序列的交叉相关。
cov(m[, y, rowvar, bias, ddof, fweights, ...])	给定数据和权重，估计协方差矩阵。

直方图

histogram(a[, bins, range, density, weights])	计算数据集的直方图。
histogram2d(x, y[, bins, range, density, ...])	计算两个数据样本的二维直方图。
histogramdd(sample[, bins, range, density, ...])	计算一些数据的多维直方图。
bincount(x, /[, weights, minlength])	计算非负整数数组中每个值的出现次数。
histogram_bin_edges(a[, bins, range, weights])	用于计算histogram函数使用的箱子边缘的函数。
digitize(x, bins[, right])	返回输入数组中每个值所属的箱子的索引。

numpy.ptp

原文：numpy.org/doc/1.26/reference/generated/numpy.ptp.html

numpy.ptp(a, axis=None, out=None, keepdims=<no value>)

沿轴的值的范围（最大值 - 最小值）。

函数的名称来自于“peak to peak”的缩写。

警告

ptp保留了数组的数据类型。这意味着对于具有 n 位有符号整数的输入（如np.int8、np.int16等），返回值也是具有 n 位有符号整数。在这种情况下，大于2**(n-1)-1的峰值-峰值值将作为负值返回。下面是一个带解决方法的示例。

参数：

a（类似于数组）

输入值。

axis（None、int 或 int 型的元组，可选）

寻找峰值的轴。默认情况下，将数组展平。axis可以是负数，此时它从最后一个轴向第一个轴计数。

版本 1.15.0 中新增。

如果这是一组 int 型的元组，则将对多个轴进行归约，而不是像以前那样对单个轴或所有轴进行归约。

out（类似于数组）

用于放置结果的替代输出数组。它必须具有与预期输出相同的形状和缓冲区长度，但如果需要，输出值的类型将被强制转换。

keepdims（布尔型，可选）

如果设置为 True，则被减少的轴会在结果中保留为大小为一的维度。通过此选项，结果将与输入数组正确地进行广播。

如果传递了默认值，则keepdims不会传递到ptp方法的ndarray子类中，但任何非默认值都会传递。如果子类的方法没有实现keepdims，则会引发任何异常。

返回值：

ptp（类似于 ndarray 或标量）

给定数组的范围 - 如果数组为一维，则为标量；如果数组为多维，则为沿给定轴的结果的新数组。

示例：

>>> x = np.array([[4, 9, 2, 10],
...               [6, 9, 7, 12]]) 

>>> np.ptp(x, axis=1)
array([8, 6]) 

>>> np.ptp(x, axis=0)
array([2, 0, 5, 2]) 

>>> np.ptp(x)
10 

该示例表明，当输入是一组有符号整数时，可能会返回负值。

>>> y = np.array([[1, 127],
...               [0, 127],
...               [-1, 127],
...               [-2, 127]], dtype=np.int8)
>>> np.ptp(y, axis=1)
array([ 126,  127, -128, -127], dtype=int8) 

一种解决方法是使用view()方法将结果视为具有相同位宽的无符号整数：

>>> np.ptp(y, axis=1).view(np.uint8)
array([126, 127, 128, 129], dtype=uint8) 

numpy.percentile

原文：numpy.org/doc/1.26/reference/generated/numpy.percentile.html

numpy.percentile(a, q, axis=None, out=None, overwrite_input=False, method='linear', keepdims=False, *, interpolation=None)

沿指定轴计算数据的第 q 个百分位数。

返回数组元素的第 q 个百分位数。

参数：

a 实数的 array_like。

输入数组或可转换为数组的对象。

q 浮点数的 array_like。

计算要计算的百分位数的百分比或百分比序列。值必须介于 0 和 100 之间（包括边界）。

axis {int, int 的元组, None}，可选。

计算百分位数的轴或轴。默认是在数组的扁平版本上计算百分位数。

1.9.0 版中的更改：支持轴的元组

out ndarray，可选。

替代输出数组，必须具有与预期输出相同的形状和缓冲区长度，但如有必要，则输出的类型将被强制转换。

overwrite_input bool，可选。

如果为 True，则允许中间计算修改输入数组 a，以节省内存。在这种情况下，此函数完成后输入 a 的内容是未定义的。

methodstr，可选。

此参数指定用于估计百分位数的方法。有许多不同的方法，其中一些是 NumPy 特有的。有关说明，请参阅注释。按照其在 H&F 论文 [1]中总结的 R 类型排序的选项为：

1. ‘inverted_cdf’

2. ‘averaged_inverted_cdf’

3. ‘closest_observation’

4. ‘interpolated_inverted_cdf’

5. ‘hazen’

6. ‘weibull’

7. ‘linear’（默认）

8. ‘median_unbiased’

9. ‘normal_unbiased’

前三种方法是不连续的。NumPy 还定义了默认 ‘linear’（7.）选项的以下不连续变体：

• ‘lower’

• ‘higher’

• ‘midpoint’

• ‘nearest’

1.22.0 版中的更改：此参数以前称为“interpolation”，并且只提供了“linear”默认值和其余的四个选项。

keepdimsbool，可选。

如果设置为 True，则缩减的轴将作为大小为 1 的维度保留在结果中。使用此选项，结果将正确地广播到原始数组 a。

新版 1.9.0 中新增。

interpolation str，可选。

方法关键字参数的不推荐名称。

从 1.22.0 版开始不推荐使用。

返回：

percentile 标量或 ndarray。

如果 q 是单个百分位数并且 axis=None，则结果是标量。如果给出多个百分位数，结果的第一个轴对应于百分位数。其他轴是在 a 缩减后剩下的轴。如果输入包含小于 float64 的整数或浮点数，则输出数据类型为 float64。否则，输出的数据类型与输入的相同。如果指定了 out，则返回该数组。

另请参阅

mean

median

等效于 percentile(..., 50)

nanpercentile

分位数

与分位数相同，只是范围为 [0, 1] 的 q。

注

给定长度为 n 的向量 V，V 的第 q 个百分位数是在排序后的 V 的最小值和最大值之间，从最小值到最大值的q/100 处的值。如果标准化排名与位置 q 不完全匹配，则两个最近邻居的值和距离以及 method 参数将确定百分位数。如果 q=50，这个函数与中位数相同，如果 q=0，则与最小值相同，如果 q=100，则与最大值相同。

可选的 method 参数指定了当所需的百分位数位于两个索引 i 和 j = i + 1 之间时要使用的方法。在这种情况下，我们首先确定一个位于 i 和 j 之间的虚拟索引 i + g，其中 i 是 floor，g 是索引的小数部分。最终结果是基于 g 的 a[i] 和 a[j] 的插值。在计算 g 期间，i 和 j 被修正使用校正常数 alpha 和 beta，其选择取决于使用的 method。最后，注意由于 Python 使用基于 0 的索引，代码在内部从索引中再减去 1。

下列公式确定排序样本中百分位的虚拟索引 i + g 的位置：

[i + g = (q / 100) * ( n - alpha - beta + 1 ) + alpha]

不同的方法运作如下

inverted_cdf:

H&F 的第 1 种方法 [1]。这种方法给出不连续的结果：

• 如果 g > 0 ; 则取 j

• 如果 g = 0 ; 则取 i

averaged_inverted_cdf:

H&F 的第 2 种方法 [1]。这种方法给出不连续的结果：

• 如果 g > 0 ; 则取 j

• 如果 g = 0 ; 则在边界之间取平均

closest_observation:

H&F 的第 3 种方法 [1]。这种方法给出不连续的结果：

• 如果 g > 0 ; 则取 j

• 如果 g = 0 且索引为奇数 ; 则取 j

• 如果 g = 0 且索引为偶数 ; 则取 i

interpolated_inverted_cdf:

H&F 的第 4 种方法 [1]。这种方法使用以下方法给出连续的结果：

• alpha = 0

• beta = 1

hazen:

H&F 的第 5 种方法 [1]。这种方法使用以下方法给出连续的结果：

• alpha = 1/2

• beta = 1/2

weibull:

H&F 的第 6 种方法 [1]。这种方法使用以下方法给出连续的结果：

• alpha = 0

• beta = 0

linear:

H&F 的第 7 种方法 [1]。这种方法使用以下方法给出连续的结果：

• alpha = 1

• beta = 1

median_unbiased:

H&F 的第 8 种方法 [1]。这种方法可能是最好的方法，如果样本分布函数是未知的（参见参考）。这种方法使用以下方法给出连续的结果：

• alpha = 1/3

• beta = 1/3

normal_unbiased:

H&F 的第 9 种方法 [1]。这种方法可能是最好的方法，如果样本分布函数已知是正态的。这种方法使用以下方法给出连续的结果：

• alpha = 3/8

• beta = 3/8

lower:

NumPy 方法保留用于向后兼容。以i作为插值点。

更高：

NumPy 方法保留用于向后兼容。以j作为插值点。

最近的：

NumPy 方法保留用于向后兼容。取最近的i或j。

中点：

NumPy 方法保留用于向后兼容。使用(i + j) / 2。

参考文献

[1] (1,2,3,4,5,6,7,8,9,10)

R. J. Hyndman 和 Y. Fan，“统计软件包中的样本分位数”，《美国统计学家》，1996 年，50(4)，361-365 页

例子

>>> a = np.array([[10, 7, 4], [3, 2, 1]])
>>> a
array([[10,  7,  4],
 [ 3,  2,  1]])
>>> np.percentile(a, 50)
3.5
>>> np.percentile(a, 50, axis=0)
array([6.5, 4.5, 2.5])
>>> np.percentile(a, 50, axis=1)
array([7.,  2.])
>>> np.percentile(a, 50, axis=1, keepdims=True)
array([[7.],
 [2.]]) 

>>> m = np.percentile(a, 50, axis=0)
>>> out = np.zeros_like(m)
>>> np.percentile(a, 50, axis=0, out=out)
array([6.5, 4.5, 2.5])
>>> m
array([6.5, 4.5, 2.5]) 

>>> b = a.copy()
>>> np.percentile(b, 50, axis=1, overwrite_input=True)
array([7.,  2.])
>>> assert not np.all(a == b) 

这些不同的方法可以以图形方式进行可视化:

import matplotlib.pyplot as plt

a = np.arange(4)
p = np.linspace(0, 100, 6001)
ax = plt.gca()
lines = [
    ('linear', '-', 'C0'),
    ('inverted_cdf', ':', 'C1'),
    # Almost the same as `inverted_cdf`:
    ('averaged_inverted_cdf', '-.', 'C1'),
    ('closest_observation', ':', 'C2'),
    ('interpolated_inverted_cdf', '--', 'C1'),
    ('hazen', '--', 'C3'),
    ('weibull', '-.', 'C4'),
    ('median_unbiased', '--', 'C5'),
    ('normal_unbiased', '-.', 'C6'),
    ]
for method, style, color in lines:
    ax.plot(
        p, np.percentile(a, p, method=method),
        label=method, linestyle=style, color=color)
ax.set(
    title='Percentiles for different methods and data: ' + str(a),
    xlabel='Percentile',
    ylabel='Estimated percentile value',
    yticks=a)
ax.legend(bbox_to_anchor=(1.03, 1))
plt.tight_layout()
plt.show() 

numpy.nanpercentile

原文：numpy.org/doc/1.26/reference/generated/numpy.nanpercentile.html

numpy.nanpercentile(a, q, axis=None, out=None, overwrite_input=False, method='linear', keepdims=<no value>, *, interpolation=None)

计算指定轴上的数据的第 q 个百分位数，同时忽略 nan 值。

返回数组元素的第 q 个百分位数。

版本 1.9.0 中的新功能。

参数：

aarray_like

输入数组或可以转换为数组的对象，其中包含要忽略的 nan 值。

qarray_like of float

要计算的百分位数或百分位数序列，必须在 0 和 100 之间（包括 0 和 100）。

axis，可选

计算百分位数的轴或轴。默认值是沿数组的平坦版本计算百分位数。

outndarray, 可选

替代的输出数组，用于放置结果。它必须具有与预期输出相同的形状和缓冲区长度，但如果需要，输出的类型将被强制转换。

overwrite_inputbool，可选

如果为 True，则允许对中间计算修改输入数组a，以节省内存。在这种情况下，此函数完成后输入a的内容未定义。

methodstr，可选

此参数指定用于估计百分位数的方法。有许多不同的方法，一些是 NumPy 特有的。请参阅注释以了解解释。按照 H&F 论文[1]中总结的它们的 R 类型排序的选项是：

1. ‘inverted_cdf’

2. ‘averaged_inverted_cdf’

3. ‘closest_observation’

4. ‘interpolated_inverted_cdf’

5. ‘hazen’

6. ‘weibull’

7. ‘linear’（默认）

8. ‘median_unbiased’

9. ‘normal_unbiased’

前三种方法是不连续的。NumPy 进一步对默认的‘linear’(7.)选项定义了以下不连续的变体：

• ‘lower’

• ‘higher’

• ‘midpoint’

• ‘nearest’

从版本 1.22.0 开始更改：此参数以前称为“interpolation”，并且仅提供了“linear”默认值和最后四个选项。

keepdimsbool，可选

如果设置为 True，则减少的轴将作为尺寸为 1 的维度保留在结果中。使用此选项，结果将正确广播到原始数组a。

如果这不是默认值，它将被传递（在特殊情况下是空数组）到底层数组的mean函数中。如果数组是子类，并且mean没有 kwarg keepdims，这将引发 RuntimeError。

interpolationstr，可选

方法关键字参数的不推荐名称。

自版本 1.22.0 起不推荐使用。

返回：

percentilescalar or ndarray

如果q是一个单一的百分位数，axis=None，那么结果是一个标量。如果给定了多个百分位数，结果的第一个轴对应于百分位数。其他轴是* a * 减少后保留的轴。如果输入包含小于float64的整数或浮点数，则输出数据类型是float64。否则，输出数据类型与输入的相同。如果指定了out，则返回该数组。

另请参阅

nanmean

nanmedian

相当于nanpercentile(..., 50)

percentile, median, mean

nanquantile

相当于 nanpercentile，除了 q 的范围是[0, 1]。

注意

更多信息请参见numpy.percentile

参考资料

[1]

R. J. Hyndman 和 Y. Fan，“统计软件包中的样本分位数”，《美国统计学家》，第 50 卷，第 361-365 页，1996 年

示例

>>> a = np.array([[10., 7., 4.], [3., 2., 1.]])
>>> a[0][1] = np.nan
>>> a
array([[10.,  nan,   4.],
 [ 3.,   2.,   1.]])
>>> np.percentile(a, 50)
nan
>>> np.nanpercentile(a, 50)
3.0
>>> np.nanpercentile(a, 50, axis=0)
array([6.5, 2\. , 2.5])
>>> np.nanpercentile(a, 50, axis=1, keepdims=True)
array([[7.],
 [2.]])
>>> m = np.nanpercentile(a, 50, axis=0)
>>> out = np.zeros_like(m)
>>> np.nanpercentile(a, 50, axis=0, out=out)
array([6.5, 2\. , 2.5])
>>> m
array([6.5,  2\. ,  2.5]) 

>>> b = a.copy()
>>> np.nanpercentile(b, 50, axis=1, overwrite_input=True)
array([7., 2.])
>>> assert not np.all(a==b) 

numpy.quantile

原文：numpy.org/doc/1.26/reference/generated/numpy.quantile.html

numpy.quantile(a, q, axis=None, out=None, overwrite_input=False, method='linear', keepdims=False, *, interpolation=None)

计算沿指定轴的数据的 q-th 分位数。

版本 1.15.0 中的新内容。

参数：

a实数 array_like

输入数组或可转换为数组的对象。

qfloat array_like

用于计算分位数的概率或分位数序列。值必须在 0 到 1 之间（包括 0 和 1）。

axis，可选

计算分位数的轴或轴。默认是沿数组的扁平版本计算分位数。

输出ndarray，可选

替代的输出数组，其中放置结果。它必须具有与预期输出相同的形状和缓冲区长度，但如果需要，输出的类型（输出）将被转换。

overwrite_inputbool，可选

如果为 True，则允许对中间计算修改输入数组a，以节省内存。在这种情况下，此函数完成后输入a的内容是不确定的。

methodstr，可选

此参数指定用于估算分位数的方法。有许多不同的方法，其中一些是 NumPy 独有的。请参见注释以了解解释。按照它们在 H&F 论文[1]中总结的 R 类型的排序，选项分为：

1. ‘inverted_cdf’

2. ‘averaged_inverted_cdf’

3. ‘closest_observation’

4. ‘interpolated_inverted_cdf’

5. ‘hazen’

6. ‘weibull’

7. ‘linear’（默认）

8. ‘median_unbiased’

9. ‘normal_unbiased’

前三种方法是不连续的。NumPy 还进一步定义了默认的‘linear’（7）选项的以下不连续变体：

• ‘lower’

• ‘higher’，

• ‘中点’

• ‘nearest’

在版本 1.22.0 中更改：此参数以前称为“interpolation”，并且仅提供了“linear”默认值和最后四个选项。

keepdimsbool，可选

如果设置为 True，则减少的轴将保留在结果中，作为尺寸为一的维度。选择此选项，结果将正确地针对原始数组a进行广播。

插值str，可选

方法关键字参数的不推荐名称。

从版本 1.22.0 开始不推荐使用。

返回：

分位数标量或 ndarray

如果q是单个概率且axis=None，则结果是标量。如果给定了多个概率水平，则结果的第一个轴对应于分位数。其他轴是对a减少后保留的轴。如果输入包含小于float64的整数或浮点数，则输出数据类型为float64。否则，输出数据类型与输入的相同。如果指定了out，则返回该数组。

另请参阅

mean

百分位数

等效于 quantile，但 q 在范围[0,100]内。

中位数

等效于quantile(..., 0.5)

nanquantile

注意事项

给定长度为 n 的向量 V，V 的第 q 个分位数是在 V 的排序副本中从最小值到最大值的 q 处的值。如果归一化排名与 q 的位置不完全匹配，则两个最近邻居的值和距离以及 method 参数将确定分位数。如果 q=0.5，则此函数与中位数相同；如果 q=0.0，则与最小值相同；如果 q=1.0，则与最大值相同。

可选的 method 参数指定当所需分位数位于两个索引 i 和 j = i + 1 之间时要使用的方法。在这种情况下，我们首先确定 i + g，即位于 i 和 j 之间的虚拟索引，其中 i 是地板，g 是索引的小数部分。然后，最终结果是根据 g 对 a[i] 和 a[j] 进行插值。在计算 g 时，使用修正常数 alpha 和 beta 修改 i 和 j，其选择取决于所使用的 method。最后，请注意，由于 Python 使用基于 0 的索引，因此代码在内部从索引中再减去另外 1。

以下公式确定了排序样本中分位数的虚拟索引 i + g 的位置：

[i + g = q * ( n - alpha - beta + 1 ) + alpha]

然后，不同的方法工作如下：

倒数累积分布：

H&F 方法 1 [1]。此方法提供不连续的结果：

• 若 g > 0；则取 j

• 若 g = 0；则取 i

平均倒数累积分布：

H&F 方法 2 [1]。此方法提供不连续的结果：

• 若 g > 0；则取 j

• 若 g = 0；则在边界之间取平均

最近观察值：

H&F 方法 3 [1]。此方法提供不连续的结果：

• 若 g > 0；则取 j

• 若 g = 0 且索引为奇数；则取 j

• 若 g = 0 且索引为偶数；则取 i

插值倒数累积分布：

H&F 方法 4 [1]。此方法使用连续结果：

• alpha = 0

• beta = 1

哈兹恩：

H&F 方法 5 [1]。此方法使用连续结果：

• alpha = 1/2

• beta = 1/2

威布尔：

H&F 方法 6 [1]。此方法使用连续结果：

• alpha = 0

• beta = 0

线性：

H&F 方法 7 [1]。此方法使用连续结果：

• alpha = 1

• beta = 1

中位数无偏：

H&F 方法 8 [1]。如果样本分布函数未知，则此方法可能是最佳方法（参见参考资料）。此方法使用连续结果：

• alpha = 1/3

• beta = 1/3

正态无偏：

H&F 方法 9 [1]。如果已知样本分布函数为正态分布，则此方法可能是最佳方法。此方法使用连续结果：

• alpha = 3/8

• beta = 3/8

低值：

NumPy 方法保留以确保向后兼容性。以 i 为插值点。

更高：

NumPy 方法保留以确保向后兼容性。以 j 为插值点。

最近的：

NumPy 方法保留以供向后兼容。取i或j，以最近的一个为准。

中点:

NumPy 方法保留以供向后兼容。使用(i + j) / 2。

参考

[1] (1,2,3,4,5,6,7,8,9,10)

R. J. Hyndman 和 Y. Fan，“统计软件包中的样本分位数”，美国统计学家, 50(4), 第 361-365 页, 1996

例子

>>> a = np.array([[10, 7, 4], [3, 2, 1]])
>>> a
array([[10,  7,  4],
 [ 3,  2,  1]])
>>> np.quantile(a, 0.5)
3.5
>>> np.quantile(a, 0.5, axis=0)
array([6.5, 4.5, 2.5])
>>> np.quantile(a, 0.5, axis=1)
array([7.,  2.])
>>> np.quantile(a, 0.5, axis=1, keepdims=True)
array([[7.],
 [2.]])
>>> m = np.quantile(a, 0.5, axis=0)
>>> out = np.zeros_like(m)
>>> np.quantile(a, 0.5, axis=0, out=out)
array([6.5, 4.5, 2.5])
>>> m
array([6.5, 4.5, 2.5])
>>> b = a.copy()
>>> np.quantile(b, 0.5, axis=1, overwrite_input=True)
array([7.,  2.])
>>> assert not np.all(a == b) 

另请参阅numpy.percentile以获取大多数方法的可视化。

numpy.nanquantile

原文：numpy.org/doc/1.26/reference/generated/numpy.nanquantile.html

numpy.nanquantile(a, q, axis=None, out=None, overwrite_input=False, method='linear', keepdims=<no value>, *, interpolation=None)

在忽略 nan 值的情况下计算指定轴上的第 q 分位数。返回数组元素的 q 分位数。

1.15.0 版中新增。

参数：

aarray_like

输入数组或可以转换为数组的对象，其中包含要忽略的 nan 值

qfloat 的 array_like

概率或用于计算分位数的概率序列。值必须在 0 和 1 之间（包括 0 和 1）。

轴, 可选参数

计算分位数的轴或轴。默认值是在数组的扁平化版本上计算分位数。

outndarray，可选参数

替代输出数组，用于存放结果。它必须具有与预期输出相同的形状和缓冲区长度，但如果需要，输出的类型将会转换。

overwrite_input布尔值，可选参数

如果为 True，则允许修改中间计算的输入数组a，以节省内存。在这种情况下，此函数完成后输入 a 的内容是未定义的。

method字符串，可选参数

该参数指定用于估计分位数的方法。有许多不同的方法，其中一些是 NumPy 特有的。请参见注释以获取解释。根据它们在 H&F 论文中总结的 R 类型，选项如下[1]：

1. ‘inverted_cdf’

2. ‘averaged_inverted_cdf’

3. ‘closest_observation’

4. ‘interpolated_inverted_cdf’

5. ‘hazen’

6. ‘weibull’

7. ‘linear’（默认值）

8. ‘median_unbiased’

9. ‘normal_unbiased’

前三种方法是不连续的。NumPy 进一步定义了默认的‘linear’(7.)选项的以下不连续变化：

• ‘lower’

• ‘higher’，

• ‘midpoint’

• ‘nearest’

自 1.22.0 版本更改：该参数以前称为“interpolation”，并且只提供“linear”默认值和最后四个选项。

keepdims布尔值，可选参数

如果设置为 True，那么被减少的轴将作为大小为一的维度保留在结果中。使用此选项，结果将正确地对原始数组a进行广播。

如果这不是默认值，那么它将通过（在空数组的特殊情况下）传递给底层数组的mean函数。如果数组是子类，而mean没有 kwarg keepdims，则会引发运行时错误。

interpolation字符串，可选参数

方法关键字参数的已弃用名称。

自 1.22.0 版起已弃用。

返回值：

quantile标量或 ndarray

如果q是单个概率且axis=None，则结果是标量。如果给定多个概率水平，则结果的第一个轴对应于分位数。其他轶轴是在a减少后保留的轴。如果输入包含小于float64的整数或浮点数，则输出数据类型为float64。否则，输出数据类型与输入相同。如果指定了out，则返回该数组。

另请参阅

quantile

nanmean，nanmedian

nanmedian

等同于nanquantile(..., 0.5)

nanpercentile

与 nanquantile 相同，但 q 在范围[0, 100]内。

注意事项

有关更多信息，请参

参考文献

[1]

R. J. Hyndman 和 Y. Fan，“统计软件包中的样本分位数”，《美国统计学家》，50(4)，pp. 361-365，1996

例子

>>> a = np.array([[10., 7., 4.], [3., 2., 1.]])
>>> a[0][1] = np.nan
>>> a
array([[10.,  nan,   4.],
 [ 3.,   2.,   1.]])
>>> np.quantile(a, 0.5)
nan
>>> np.nanquantile(a, 0.5)
3.0
>>> np.nanquantile(a, 0.5, axis=0)
array([6.5, 2\. , 2.5])
>>> np.nanquantile(a, 0.5, axis=1, keepdims=True)
array([[7.],
 [2.]])
>>> m = np.nanquantile(a, 0.5, axis=0)
>>> out = np.zeros_like(m)
>>> np.nanquantile(a, 0.5, axis=0, out=out)
array([6.5, 2\. , 2.5])
>>> m
array([6.5,  2\. ,  2.5])
>>> b = a.copy()
>>> np.nanquantile(b, 0.5, axis=1, overwrite_input=True)
array([7., 2.])
>>> assert not np.all(a==b) 

numpy.median

原文：numpy.org/doc/1.26/reference/generated/numpy.median.html

numpy.median(a, axis=None, out=None, overwrite_input=False, keepdims=False)

计算沿指定轴的中位数。

返回数组元素的中位数。

参数：

a array_like

输入数组或可转换为数组的对象。

axis, 可选

计算中位数的轴或轴。默认值是计算数组的扁平版本沿中位数。自版本 1.9.0 以来支持轴序列。

out ndarray，可选

替代输出数组，其中放置结果。它必须具有与预期输出相同的形状和缓冲区长度，但必要时将转换（输出）的类型。

overwrite_inputbool, 可选

如果为 True，则允许使用输入数组a的内存进行计算。该调用对输入数组进行修改。当不需要保留输入数组的内容时，这将节省内存。将输入视为未定义，但可能完全或部分排序。默认值为 False。如果overwrite_input为True且a还不是ndarray，则会引发错误。

keepdimsbool, 可选

如果设置为 True，则减少的轴将作为具有大小为一的维度留在结果中。使用此选项，结果将针对原始arr进行正确的广播。

新版本 1.9.0。

返回：

median ndarray

存储结果的新数组。如果输入包含小于float64的整数或浮点数，则输出数据类型为np.float64。否则，输出的数据类型与输入的相同。如果指定了out，则返回该数组。

另请参阅

mean，percentile

注意

给定长度为N的向量V，V的中位数是排序副本V_sorted的中间值 - 即 V_sorted[(N-1)/2]，当N为奇数时，以及V_sorted的两个中间值的平均值，当N为偶数时。

示例

>>> a = np.array([[10, 7, 4], [3, 2, 1]])
>>> a
array([[10,  7,  4],
 [ 3,  2,  1]])
>>> np.median(a)
3.5
>>> np.median(a, axis=0)
array([6.5, 4.5, 2.5])
>>> np.median(a, axis=1)
array([7.,  2.])
>>> m = np.median(a, axis=0)
>>> out = np.zeros_like(m)
>>> np.median(a, axis=0, out=m)
array([6.5,  4.5,  2.5])
>>> m
array([6.5,  4.5,  2.5])
>>> b = a.copy()
>>> np.median(b, axis=1, overwrite_input=True)
array([7.,  2.])
>>> assert not np.all(a==b)
>>> b = a.copy()
>>> np.median(b, axis=None, overwrite_input=True)
3.5
>>> assert not np.all(a==b) 

numpy.average

原文：numpy.org/doc/1.26/reference/generated/numpy.average.html

numpy.average(a, axis=None, weights=None, returned=False, *, keepdims=<no value>)

计算沿指定轴的加权平均值。

参数：

aarray_like

包含要平均的数据的数组。如果a不是数组，则会尝试转换。

axisNone 或 int 或 int 元组，可选

沿着其进行平均值计算的轴或轴。默认情况下，axis=None 将对输入数组的所有元素进行平均值计算。如果 axis 为负数，则从最后一个轴到第一个轴计数。

新功能在版本 1.7.0 中。

如果轴是整数元组，则对元组中指定的所有轴执行平均值计算，而不是以前的单个轴或所有轴。

weightsarray_like，可选

与a中的值相关联的权重数组。a中的每个值根据其关联的权重对平均值做出贡献。权重数组可以是 1-D（在这种情况下，其长度必须是给定轴上a的大小）或与a相同形状。如果weights=None，则假定a中的所有数据的权重都等于 1。1-D 计算如下：

avg = sum(a * weights) / sum(weights) 

权重的唯一约束是sum(weights)不能为 0。

returnedbool，可选

默认值为False。如果True，则返回元组（average，sum_of_weights），否则仅返回平均值。如果weights=None，sum_of_weights等于计算平均值的元素数量。

keepdimsbool，可选

如果设置为 True，则被减少的轴将作为尺寸为 1 的维度保留在结果中。使用此选项，结果将正确广播到原始a。注意: keepdims不适用于numpy.matrix或其他不支持keepdims方法的类的实例。

新功能在版本 1.23.0 中。

返回：

retval，[sum_of_weights]array_type 或 double

沿指定轴计算平均值。当returned为True时，返回一个元组，第一个元素是平均值，第二个元素是权重的总和。sum_of_weights与retval的类型相同。结果 dtype 遵循一般模式。如果weights为 None，则结果 dtype 将是a的 dtype，或者如果a是整数，则为float64。否则，如果weights不为 None 且a不是整数，则结果类型将是能够表示a和weights值的最低精度类型。如果a恰好是整数，则仍然适用先前的规则，但结果 dtype 至少为float64。

引发：

零除错误

当沿轴的所有权重都为零时。查看numpy.ma.average以获得对此类型错误鲁棒的版本。

类型错误

当 1D weights的长度与沿轴的a的形状不同时。

另请参阅

mean

ma.average

用于掩码数组的平均值 - 如果您的数据包含“缺失”值，则非常有用

numpy.result_type

返回应用 numpy 类型提升规则到参数后的类型。

示例

>>> data = np.arange(1, 5)
>>> data
array([1, 2, 3, 4])
>>> np.average(data)
2.5
>>> np.average(np.arange(1, 11), weights=np.arange(10, 0, -1))
4.0 

>>> data = np.arange(6).reshape((3, 2))
>>> data
array([[0, 1],
 [2, 3],
 [4, 5]])
>>> np.average(data, axis=1, weights=[1./4, 3./4])
array([0.75, 2.75, 4.75])
>>> np.average(data, weights=[1./4, 3./4])
Traceback (most recent call last):
  ...
TypeError: Axis must be specified when shapes of a and weights differ. 

>>> a = np.ones(5, dtype=np.float128)
>>> w = np.ones(5, dtype=np.complex64)
>>> avg = np.average(a, weights=w)
>>> print(avg.dtype)
complex256 

运用keepdims=True，以下结果的形状为(3, 1)。

>>> np.average(data, axis=1, keepdims=True)
array([[0.5],
 [2.5],
 [4.5]]) 

numpy.mean

原文：numpy.org/doc/1.26/reference/generated/numpy.mean.html

numpy.mean(a, axis=None, dtype=None, out=None, keepdims=<no value>, *, where=<no value>)

沿指定轴计算算术平均值。

返回数组元素的平均值。默认情况下，平均值是在扁平化数组上计算的，否则在指定的轴上计算。对于整数输入，中间和返回值使用float64。

参数:

aarray_like

包含所需平均值的数字的数组。如果a不是数组，则会尝试进行转换。

axisNone 或 int 或 int 元组, 可选

计算平均值的轴。默认情况下，计算扁平数组的平均值。

1.7.0 版本中的新内容。

如果这是一个 int 元组，则将在多个轴上执行平均值，而不是以前的单个轴或所有轴的平均值。

dtype数据类型, 可选

用于计算平均值的类型。对于整数输入，默认值为float64；对于浮点输入，它与输入 dtype 相同。

outndarray, 可选

备选输出数组，用于放置结果。默认值为None；如果提供，则必须具有与预期输出相同的形状，但必要时将进行类型转换。详情请参阅输出类型确定。

keepdimsbool, 可选

如果设置为 True，则被减少的轴将作为大小为 1 的维度保留在结果中。使用此选项，结果将正确地广播到输入数组。

如果传递了默认值，则keepdims将不会传递给mean方法的子类，但任何非默认值都将传递。如果子类方法不实现keepdims，则会引发任何异常。

wherearray_like of bool, 可选

要包括在均值中的元素。详情请参阅reduce。

1.20.0 版本中的新内容。

返回:

mndarray，参见上面的 dtype 参数

如果out=None，返回一个包含平均值的新数组，否则返回对输出数组的引用。

另请参阅

average

加权平均

std, var, nanmean, nanstd, nanvar

注意

算术平均值是沿着轴的元素之和除以元素个数。

请注意，对于浮点输入，均值是使用与输入相同的精度计算的。根据输入数据，这可能导致结果不准确，特别是对于float32（见下面的示例）。使用dtype关键字指定更高精度的累加器可以缓解这个问题。

默认情况下，float16的结果是用float32作为中间值计算，以获得额外的精度。

示例

>>> a = np.array([[1, 2], [3, 4]])
>>> np.mean(a)
2.5
>>> np.mean(a, axis=0)
array([2., 3.])
>>> np.mean(a, axis=1)
array([1.5, 3.5]) 

在单精度下，mean可能不准确：

>>> a = np.zeros((2, 512*512), dtype=np.float32)
>>> a[0, :] = 1.0
>>> a[1, :] = 0.1
>>> np.mean(a)
0.54999924 

用float64计算均值更精确：

>>> np.mean(a, dtype=np.float64)
0.55000000074505806 # may vary 

指定一个where参数：

>>> a = np.array([[5, 9, 13], [14, 10, 12], [11, 15, 19]])
>>> np.mean(a)
12.0
>>> np.mean(a, where=[[True], [False], [False]])
9.0 

numpy.std

numpy.org/doc/1.26/reference/generated/numpy.std.html

numpy.std(a, axis=None, dtype=None, out=None, ddof=0, keepdims=<no value>, *, where=<no value>)

沿指定轴计算标准差。

返回数组元素的标准差，这是对分布的扩展度的一种测量。默认情况下，通过压平的数组计算标准差，或者可以沿指定轴进行计算。

参数：

a类似数组

计算这些值的标准差。

axisNone 或 int 或 int 的元组，可选

计算标准差的轴或轴。默认值是计算压平数组的标准差。

自 1.7.0 版本新增。

如果传入的是 int 的元组，则会在多个轴上执行标准差计算，而不是之前的单个轴或所有轴的计算。

dtypedtype，可选

用于计算标准差的类型。对于整数类型的数组，默认值是 float64，对于浮点类型的数组，它与数组类型相同。

outndarray，可选

替代输出数组，用于放置结果。它必须具有与期望输出相同的形状，但如果需要，将会对计算的值进行类型强制转换。

ddofint，可选

自由度差异。计算中使用的除数是N - ddof，其中N代表元素的数量。默认情况下，ddof为零。

keepdimsbool，可选

如果设置为 True，则被减少的轴会留在结果中作为大小为 1 的维度。使用此选项，结果将正确地广播到输入数组。

如果传入的是默认值，那么keepdims将不会传递给 std 的子类的方法，然而任何非默认值都会。如果子类的方法没有实现keepdims，则会引发任何异常。

wherebool 值的数组或类似数组，可选

包括在标准差中的元素。有关详细信息，请参见 reduce。

自 1.20.0 版本新增。

返回：

standard_deviationndarray，参见上面的 dtype 参数。

如果out为空，则返回一个包含标准差的新数组，否则返回对输出数组的引用。

参见

var, mean, nanmean, nanstd, nanvar

输出类型确定

注释

标准差是平均平方离差的平方根，即std = sqrt(mean(x))，其中x = abs(a - a.mean())**2。

平均平方偏差通常被计算为 x.sum() / N，其中 N = len(x)。然而，如果指定了 ddof，则会使用除数 N - ddof。在标准统计实践中，ddof=1 提供了无偏估计的方差，适用于无限总体。ddof=0提供了正态分布变量方差的最大似然估计。该函数计算的标准偏差是估计方差的平方根，因此即使使用 ddof=1，它也不会是标准偏差的无偏估计。

请注意，对于复数，std 在平方之前取绝对值，因此结果总是实数且非负。

对于浮点输入，std 是使用与输入相同的精度来计算的。根据输入数据的不同，这可能导致结果不准确，特别是对于 float32（见下面的例子）。使用 dtype 关键字指定更高精度的累加器可以缓解这个问题。

例子

>>> a = np.array([[1, 2], [3, 4]])
>>> np.std(a)
1.1180339887498949 # may vary
>>> np.std(a, axis=0)
array([1.,  1.])
>>> np.std(a, axis=1)
array([0.5,  0.5]) 

在单精度中，std() 可能不准确：

>>> a = np.zeros((2, 512*512), dtype=np.float32)
>>> a[0, :] = 1.0
>>> a[1, :] = 0.1
>>> np.std(a)
0.45000005 

在 float64 中计算标准偏差更精确：

>>> np.std(a, dtype=np.float64)
0.44999999925494177 # may vary 

指定一个 where 参数：

>>> a = np.array([[14, 8, 11, 10], [7, 9, 10, 11], [10, 15, 5, 10]])
>>> np.std(a)
2.614064523559687 # may vary
>>> np.std(a, where=[[True], [True], [False]])
2.0 

numpy.var

原文：numpy.org/doc/1.26/reference/generated/numpy.var.html

numpy.var(a, axis=None, dtype=None, out=None, ddof=0, keepdims=<no value>, *, where=<no value>)

沿指定轴计算方差。

返回数组元素的方差，是分布扩散的一种度量。默认情况下，计算扁平化数组的方差，否则计算沿指定轴的方差。

参数：

a 像数组

包含要求方差的数字的数组。如果a不是数组，则会尝试转换。

axisNone 或整数或整数元组，可选

计算方差的轴或轴。默认是计算扁平化数组的方差。

版本 1.7.0 中的新功能。

如果这是一个整数元组，将在多个轴上执行方差，而不是以前的单个轴或所有轴。

dtype数据类型，可选

用于计算方差的类型。对于整数型数组，默认值为float64；对于浮点类型数组，它与数组类型相同。

out ndarray，可选

替代输出数组，其中放置结果。它必须具有与预期输出相同的形状，但必要时会进行类型转换。

ddof 整数，可选

“自由度差”: 计算中使用的除数为N - ddof，其中N表示元素数量。 默认情况下，ddof为零。

keepdims 布尔值，可选

如果设置为 True，那么被减少的轴会作为大小为一的维度保留在结果中。使用此选项，结果将正确地广播到输入数组。

如果传递了默认值，则keepdims将不会传递给var方法的ndarray子类中，但任何非默认值将会传递。如果子类的方法没有实现keepdims，则会引发任何异常。

where 布尔值数组，可选

包括在方差中的元素。有关详细信息，请参见reduce。

版本 1.20.0 中的新功能。

返回：

方差 ndarray，参见上面的 dtype 参数

如果out=None，则返回一个包含方差的新数组；否则，返回对输出数组的引用。

另请参见

std，mean，nanmean，nanstd，nanvar

输出类型确定

注意

方差是平均偏离均值的平方，即var = mean(x)，其中x = abs(a - a.mean())**2。

均值通常计算为 x.sum() / N，其中 N = len(x)。然而，如果指定了 ddof，则会使用除数 N - ddof。在标准统计实践中，ddof=1 提供了对假设无限总体方差的无偏估计。ddof=0 对于正态分布的变量提供了方差的最大似然估计。

注意，在处理复数时，先取绝对值再进行平方，以确保结果始终为实数且非负。

对于浮点输入，方差的计算与输入数据的精度相同。根据输入数据的不同，这可能导致结果不准确，尤其是对于 float32（请参见下面的示例）。使用 dtype 关键字指定更高精度的累加器可以缓解问题。

示例

>>> a = np.array([[1, 2], [3, 4]])
>>> np.var(a)
1.25
>>> np.var(a, axis=0)
array([1.,  1.])
>>> np.var(a, axis=1)
array([0.25,  0.25]) 

在单精度下，var() 可能不准确：

>>> a = np.zeros((2, 512*512), dtype=np.float32)
>>> a[0, :] = 1.0
>>> a[1, :] = 0.1
>>> np.var(a)
0.20250003 

使用 float64 计算方差更准确：

>>> np.var(a, dtype=np.float64)
0.20249999932944759 # may vary
>>> ((1-0.55)**2 + (0.1-0.55)**2)/2
0.2025 

指定 where 参数：

>>> a = np.array([[14, 8, 11, 10], [7, 9, 10, 11], [10, 15, 5, 10]])
>>> np.var(a)
6.833333333333333 # may vary
>>> np.var(a, where=[[True], [True], [False]])
4.0 

numpy.nanmedian

原文：numpy.org/doc/1.26/reference/generated/numpy.nanmedian.html

numpy.nanmedian(a, axis=None, out=None, overwrite_input=False, keepdims=<no value>)

沿指定轴计算中位数，同时忽略 NaN。

返回数组元素的中位数。

自版本 1.9.0 新增。

参数：

aarray_like

输入数组或可转换为数组的对象。

axis, optional

计算中位数的轴或轴。默认是沿数组的扁平版本计算中位数。自版本 1.9.0 开始支持一系列轴。

outndarray, optional

用于放置结果的备用输出数组。它必须具有与预期输出相同的形状和缓冲区长度，但根据需要将被转换为输出的类型。

overwrite_inputbool, optional

如果为 True，则允许使用输入数组a的内存进行计算。调用median将修改输入数组。当您不需要保留输入数组的内容时，这将节省内存。将输入视为未定义，但可能已全部或部分排序。默认值为 False。如果overwrite_input为True，且a不是已经是ndarray，则会引发错误。

keepdimsbool, optional

如果设置为 True，则减少的轴将作为大小为 1 的维度保留在结果中。使用此选项，结果将对原始a正确广播。

如果这不是默认值，将通过（在空数组的特殊情况下）传递给基础数组的mean函数。如果数组是子类，且mean没有 kwarg keepdims，这将引发 RuntimeError。

返回：

medianndarray

持有结果的新数组。如果输入包含小于float64的整数或浮点数，则输出数据类型为np.float64。否则，输出的数据类型与输入的数据类型相同。如果指定了out，则返回该数组。

另请参见

mean, median, percentile

注意

给定长度为N的向量V，V的中位数是排序副本V_sorted的中间值，即V_sorted[(N-1)/2]，当N为奇数时，V_sorted的两个中间值的平均值，当N为偶数时。

示例

>>> a = np.array([[10.0, 7, 4], [3, 2, 1]])
>>> a[0, 1] = np.nan
>>> a
array([[10., nan,  4.],
 [ 3.,  2.,  1.]])
>>> np.median(a)
nan
>>> np.nanmedian(a)
3.0
>>> np.nanmedian(a, axis=0)
array([6.5, 2\. , 2.5])
>>> np.median(a, axis=1)
array([nan,  2.])
>>> b = a.copy()
>>> np.nanmedian(b, axis=1, overwrite_input=True)
array([7.,  2.])
>>> assert not np.all(a==b)
>>> b = a.copy()
>>> np.nanmedian(b, axis=None, overwrite_input=True)
3.0
>>> assert not np.all(a==b) 

numpy.nanmean

原文：numpy.org/doc/1.26/reference/generated/numpy.nanmean.html

numpy.nanmean(a, axis=None, dtype=None, out=None, keepdims=<no value>, *, where=<no value>)

沿指定轴计算算术平均值，忽略 NaN。

返回数组元素的平均值。默认情况下，通过平坦数组进行平均，否则通过指定的轴进行平均。对于整数输入，默认情况下使用float64中间和返回值。

对于所有-NaN 切片，返回 NaN 并引发RuntimeWarning。

版本 1.8.0 中的新功能。

参数：

aarray_like

包含所需平均值的数字的数组。如果a不是数组，则会尝试转换。

axis，可选

计算平均值的轴或轴。默认值是计算平均值的扁平数组。

dtype数据类型，可选

用于计算平均值的类型。对于整数输入，默认值为float64；对于非精确输入，与输入 dtype 相同。

outndarray，可选

交替的输出数组，其中放置结果。默认值为None；如果提供，它必须具有与预期输出相同的形状，但如果需要，类型将被转换。有关更多详细信息，请参见输出类型确定。

keepdimsbool, optional

如果设置为 True，则被减少的轴会作为尺寸为一的维度留在结果中。使用此选项，结果将正确地广播对原始a。

如果值不是默认值，则keepdims将通过传递给mean或sum的子类的方法。如果子类方法未实现keepdims，则将引发任何异常。

wherebool 类型数组，可选

包含在均值中的元素。有关详细信息，请参阅reduce。

版本 1.22.0 中的新功能。

返回：

mndarray，见上面的 dtype 参数

如果out=None，返回包含平均值的新数组，否则返回对输出数组的引用。对于只包含 NaN 的切片，返回 NaN。

另见

average

加权平均

mean

不忽略 NaN 的算术平均值

var, nanvar

注意

算术平均值是沿轴向的非 NaN 元素的总和除以非 NaN 元素的数量。

请注意，对于浮点数输入，均值是使用输入数据的相同精度计算的。根据输入数据的不同，这可能会导致结果不准确，特别是对于float32。使用dtype关键字指定更高精度的累加器可以缓解这个问题。

例子

>>> a = np.array([[1, np.nan], [3, 4]])
>>> np.nanmean(a)
2.6666666666666665
>>> np.nanmean(a, axis=0)
array([2.,  4.])
>>> np.nanmean(a, axis=1)
array([1.,  3.5]) # may vary 

numpy.nanstd

原文：numpy.org/doc/1.26/reference/generated/numpy.nanstd.html

numpy.nanstd(a, axis=None, dtype=None, out=None, ddof=0, keepdims=<no value>, *, where=<no value>)

计算沿指定轴的标准差，同时忽略 NaN。

返回非 NaN 数组元素的标准差，即分布的展开度量，默认情况下计算平均值的标准差，否则计算指定轴上的标准差。

对于所有包含全为 NaN 或自由度为零的切片，都会返回 NaN 并引发RuntimeWarning。

新版本 1.8.0 中更新。

参数：

aarray_like

计算非 NaN 值的标准差。

axis，可选

计算标准差的轴或轴。默认值是计算扁平化数组的标准差。

dtypedtype，可选

用于计算标准差的类型。对于整数类型的数组，默认值是 float64，对于浮点类型的数组，它与数组类型相同。

outndarray，可选

替代输出数组，其中存放结果。它必须具有与预期输出相同的形状，但如有必要，计算值的类型（类型）将被转换。

ddofint，可选

表示自由度的度。计算中使用的除数是N - ddof，其中N表示非 NaN 元素的数量。默认情况下ddof为零。

keepdimsbool，可选

如果设置为 True，则将被减少的轴保留为大小为一的维度。使用此选项，结果将正确广播到原始a。

如果此值不是默认值，则将其原样传递给子类的相关函数。如果这些函数没有keepdims kwarg，则会引发运行时错误。

wherearray_like of bool，可选

要包括在标准差中的元素。有关详细信息，请参见reduce。

新版本 1.22.0 中更新。

返回：

standard_deviationndarray，参见上述 dtype 参数。

如果out为 None，则返回一个包含标准差的新数组，否则返回对输出数组的引用。如果 ddof 大于等于切片中的非 NaN 元素数量或切片只包含 NaN，则该切片的结果为 NaN。

另请参阅

var，mean，std

nanvar，nanmean

输出类型确定

注意

标准差是平均值与平方偏差的平均值的平方根：std = sqrt(mean(abs(x - x.mean())**2))。

平均平方偏差通常计算为x.sum() / N，其中N = len(x)。然而，如果指定了ddof，那么除数将改为使用N - ddof。在标准统计实践中，ddof=1提供了无偏估计的无限总体方差。ddof=0提供了正态分布变量方差的最大似然估计。此函数计算的标准差是估计方差的平方根，所以即使ddof=1，它也不会是标准偏差的无偏估计。

请注意，对于复数，std 在平方前取绝对值，以使结果始终是实数且非负数。

对于浮点输入，std 是使用输入精度计算的。根据输入数据，这可能导致结果不准确，特别是对于 float32（参见下面的示例）。使用dtype关键字指定更高精度的累加器可以缓解这个问题。

示例

>>> a = np.array([[1, np.nan], [3, 4]])
>>> np.nanstd(a)
1.247219128924647
>>> np.nanstd(a, axis=0)
array([1., 0.])
>>> np.nanstd(a, axis=1)
array([0.,  0.5]) # may vary 

numpy.nanvar

原文：numpy.org/doc/1.26/reference/generated/numpy.nanvar.html

numpy.nanvar(a, axis=None, dtype=None, out=None, ddof=0, keepdims=<no value>, *, where=<no value>)

沿着指定轴计算方差，同时忽略 NaN。

返回数组元素的方差，表示分布的扩展程度。默认情况下，通过对扁平化数组进行计算来计算方差，否则通过指定的轴进行计算。

对于所有为 NaN 的片段或自由度为零的片段，将返回 NaN，并引发RuntimeWarning。

新特性在版本 1.8.0 中添加。

参数：

aarray_like

包含所需方差的数字的数组。如果a不是数组，则会尝试进行转换。

axis，可选

计算方差的轴或轴。默认是计算扁平化数组的方差。

dtype数据类型，可���

用于计算方差的数据类型。对于整数类型的数组，默认值是float64；对于浮点数类型的数组，其数据类型与数组类型相同。

outndarray，可选

可选的输出数组，用来存放结果。它必须与预期的输出具有相同的形状，但如果需要会进行类型转换。

ddofint，可选

“自由度差值”: 计算中使用的除数为N - ddof，其中N表示非 NaN 元素的数量。默认情况下ddof为零。

keepdimsbool，可选

如果设置为 True，则被缩减的轴在结果中保留为具有大小为 1 的维度。使用此选项，结果将正确地广播到原始a。

wherearray_like of bool，可选

包含在方差中的元素。详情参见reduce。

新特性在版本 1.22.0 中添加。

返回：

variancendarray，参见上面的 dtype 参数

如果out为 None，则返回一个包含方差的新数组，否则返回对输出数组的引用。如果 ddof >= 切片中非 NaN 元素的数量，或者切片仅包含 NaN，则该切片的结果为 NaN。

另请参阅

std

标准差

mean

平均值

var

忽略 NaN 时的方差

nanstd，nanmean

输出类型确定

注意事项

方差是平均值的平方偏差，即，var = mean(abs(x - x.mean())**2)。

平均值通常计算为x.sum() / N，其中N = len(x)。如果指定了ddof，则使用除数N - ddof。在标准统计实践中，ddof=1提供了假设无限总体方差的无偏估计。ddof=0为正态分布变量的方差提供了最大似然估计。

请注意，对于复数，先取绝对值再平方，以确保结果始终是实数且非负。

对于浮点输入，方差是使用与输入相同的精度计算的。根据输入数据，这可能导致结果不准确，特别是对于float32（见下面的示例）。使用dtype关键字指定更高精度的累加器可以缓解此问题。

要使此函数在 ndarray 的子类上工作，它们必须使用 kwarg keepdims定义sum。

例子

>>> a = np.array([[1, np.nan], [3, 4]])
>>> np.nanvar(a)
1.5555555555555554
>>> np.nanvar(a, axis=0)
array([1.,  0.])
>>> np.nanvar(a, axis=1)
array([0.,  0.25])  # may vary 

numpy.corrcoef

原文：numpy.org/doc/1.26/reference/generated/numpy.corrcoef.html

numpy.corrcoef(x, y=None, rowvar=True, bias=<no value>, ddof=<no value>, *, dtype=None)

返回 Pearson 积矩相关系数。

请参考cov文档获取更多细节。相关系数矩阵 R 与协方差矩阵 C 之间的关系为

[R_{ij} = \frac{ C_{ij} } { \sqrt{ C_{ii} C_{jj} } }]

R 的值介于 -1 到 1 之间，包括端点。

参数:

xarray_like

包含多个变量和观测值的 1-D 或 2-D 数组。x 的每一行代表一个变量，每一列代表所有这些变量的单个观测值。也请参阅下方的 rowvar。

yarray_like, 可选

一个包含额外变量和观测值的集合。y 的形状与 x 相同。

rowvar布尔值，可选

如果 rowvar 为 True（默认情况），则每行代表一个变量，列中包含观测值。否则，关系被转置：每列代表一个变量，而行包含观测值。

bias_NoValue, 可选

无效果，请勿使用。

自版本 1.10.0 弃用。

ddof_NoValue, 可选

无效果，请勿使用。

自版本 1.10.0 弃用。

dtype数据类型，可选

结果的数据类型。默认情况下，返回的数据类型至少具有numpy.float64 精度。

1.20 版本中推出。

返回:

Rndarray

变量的相关系数矩阵。

另请参见

cov

协方差矩阵

备注

由于浮点舍入的结果，最终数组可能不会是 Hermite 矩阵，对角线元素可能不会是 1，元素可能不满足不等式 abs(a) <= 1。为了改善这种情况，实部和虚部被剪切到区间[-1, 1]，但在复杂情况下帮助不大。

此函数接受但忽略参数 bias 和 ddof。这是为了向后兼容以前版本的函数。这些参数对函数的返回值没有影响，在这个版本和以前的 numpy 版本中可以安全地忽略。

示例

在此示例中，我们生成两个随机数组，xarr 和 yarr，并计算行-wise 和列-wise 的 Pearson 相关系数 R。由于默认情况下 rowvar 为真，我们首先找到 xarr 的变量之间的行-wise Pearson 相关系数。

>>> import numpy as np
>>> rng = np.random.default_rng(seed=42)
>>> xarr = rng.random((3, 3))
>>> xarr
array([[0.77395605, 0.43887844, 0.85859792],
 [0.69736803, 0.09417735, 0.97562235],
 [0.7611397 , 0.78606431, 0.12811363]])
>>> R1 = np.corrcoef(xarr)
>>> R1
array([[ 1\.        ,  0.99256089, -0.68080986],
 [ 0.99256089,  1\.        , -0.76492172],
 [-0.68080986, -0.76492172,  1\.        ]]) 

如果我们增加另一组变量和观测值 yarr，我们可以计算 xarr 和 yarr 变量之间的按行 Pearson 相关系数。

>>> yarr = rng.random((3, 3))
>>> yarr
array([[0.45038594, 0.37079802, 0.92676499],
 [0.64386512, 0.82276161, 0.4434142 ],
 [0.22723872, 0.55458479, 0.06381726]])
>>> R2 = np.corrcoef(xarr, yarr)
>>> R2
array([[ 1\.        ,  0.99256089, -0.68080986,  0.75008178, -0.934284  ,
 -0.99004057],
 [ 0.99256089,  1\.        , -0.76492172,  0.82502011, -0.97074098,
 -0.99981569],
 [-0.68080986, -0.76492172,  1\.        , -0.99507202,  0.89721355,
 0.77714685],
 [ 0.75008178,  0.82502011, -0.99507202,  1\.        , -0.93657855,
 -0.83571711],
 [-0.934284  , -0.97074098,  0.89721355, -0.93657855,  1\.        ,
 0.97517215],
 [-0.99004057, -0.99981569,  0.77714685, -0.83571711,  0.97517215,
 1\.        ]]) 

最后，如果我们使用选项 rowvar=False，那么现在列会被视为变量，我们将在 xarr 和 yarr 中变量之间计算列-wise Pearson 相关系数。

>>> R3 = np.corrcoef(xarr, yarr, rowvar=False)
>>> R3
array([[ 1\.        ,  0.77598074, -0.47458546, -0.75078643, -0.9665554 ,
 0.22423734],
 [ 0.77598074,  1\.        , -0.92346708, -0.99923895, -0.58826587,
 -0.44069024],
 [-0.47458546, -0.92346708,  1\.        ,  0.93773029,  0.23297648,
 0.75137473],
 [-0.75078643, -0.99923895,  0.93773029,  1\.        ,  0.55627469,
 0.47536961],
 [-0.9665554 , -0.58826587,  0.23297648,  0.55627469,  1\.        ,
 -0.46666491],
 [ 0.22423734, -0.44069024,  0.75137473,  0.47536961, -0.46666491,
 1\.        ]]) 

numpy.correlate

原文：numpy.org/doc/1.26/reference/generated/numpy.correlate.html

numpy.correlate(a, v, mode='valid')

两个一维序列的互相关。

此函数计算信号处理文本中通常定义的相关性：

[c_k = \sum_n a_{n+k} \cdot \overline{v}_n]

其中 a 和 v 序列在必要时进行零填充，(\overline x) 表示复共轭。

参数：

a, varray_like

输入序列。

mode, 可选

参考 convolve 文档字符串。请注意，默认值为 ‘valid’，与 convolve 不同，后者使用 ‘full’。

old_behaviorbool

old_behavior 在 NumPy 1.10 中已移除。如果需要旧行为，请使用 multiarray.correlate。

返回：

outndarray

a 和 v 的离散互相关。

另请参见

convolve

两个一维序列的离散线性卷积。

multiarray.correlate

互相关的旧版本，无复共轭。

scipy.signal.correlate

使用 FFT 在大数组上具有优越性能。

注意事项

上述相关性的定义并不唯一，有时相关性可能有不同的定义。另一个常见的定义是：

[c'k = \sum_n a \cdot \overline{v_{n+k}}]

与 (c_k) 通过 (c'k = c) 相关。

在大数组中，numpy.correlate 可能执行缓慢（即 n = 1e5），因为它不使用 FFT 来计算卷积；在这种情况下，scipy.signal.correlate 可能更可取。

示例

>>> np.correlate([1, 2, 3], [0, 1, 0.5])
array([3.5])
>>> np.correlate([1, 2, 3], [0, 1, 0.5], "same")
array([2\. ,  3.5,  3\. ])
>>> np.correlate([1, 2, 3], [0, 1, 0.5], "full")
array([0.5,  2\. ,  3.5,  3\. ,  0\. ]) 

使用复数序列：

>>> np.correlate([1+1j, 2, 3-1j], [0, 1, 0.5j], 'full')
array([ 0.5-0.5j,  1.0+0.j ,  1.5-1.5j,  3.0-1.j ,  0.0+0.j ]) 

当两个输入序列 a 和 v 交换位置时，注意到你会得到时间反转、复共轭的结果 ((\overline{c_{-k}}))：

>>> np.correlate([0, 1, 0.5j], [1+1j, 2, 3-1j], 'full')
array([ 0.0+0.j ,  3.0+1.j ,  1.5+1.5j,  1.0+0.j ,  0.5+0.5j]) 

numpy.cov

原文：numpy.org/doc/1.26/reference/generated/numpy.cov.html

numpy.cov(m, y=None, rowvar=True, bias=False, ddof=None, fweights=None, aweights=None, *, dtype=None)

给定数据和权重，估算协方差矩阵。

协方差指示了两个变量一起变化的程度。如果我们检查 N 维样本，(X = [x_1, x_2, ... x_N]^T)，那么协方差矩阵元素 (C_{ij}) 即为(x_i)和(x_j)的协方差。元素 (C_{ii}) 即为(x_i)的方差。

请参见算法概述中的注释。

参数：

marray_like

包含多个变量和观察值的一维或二维数组。 m的每一行代表一个变量，每一列代表所有这些变量的单个观察值。也参见下面的 rowvar。

yarray_like，可选

另一组变量和观察值。y与m具有相同的形式。

rowvarbool，可选

如果 rowvar 为 True（默认值），则每行代表一个变量，列中包含观察。否则，关系被转置：每列代表一个变量，而行包含观察。

biasbool，可选

默认归一化（False）是由(N - 1)实现的，其中N是给定的观察数量（无偏估计）。如果 bias 为 True，则正常化为N。这些值可以在 numpy 版本 >= 1.5 中通过使用关键字ddof进行覆盖。

ddofint，可选

如果不是None，则会覆盖 bias 隐含的默认值。请注意，即使 fweights 和 aweights 都被指定，当ddof=1时也会返回无偏估计，而ddof=0将返回简单平均值。详情请参阅注释。默认值为None。

版本 1.5 中的新增内容。

fweightsarray_like，int，可选

整数频率权重的一维数组；每个观察向量应重复的次数。

版本 1.10 中的新增内容。

aweightsarray_like，可选

观察向量权重的一维数组。这些相对权重对于被认为“重要”的观察通常很大，对于被认为不太“重要”的观察则较小。如果ddof=0，权重数组可以用于为观察向量分配概率。

版本 1.10 中的新增内容。

dtype数据类型，可选

结果的数据类型。默认情况下，返回数据类型至少为numpy.float64精度。

版本 1.20 中的新增内容。

返回：

outndarray

变量的协方差矩阵。

另请参阅

corrcoef

标准化协方差矩阵

注释

假设观察在观察数组 m 的列中，并且为简洁起见，令f = fweights和a = aweights。计算加权协方差的步骤如下：

>>> m = np.arange(10, dtype=np.float64)
>>> f = np.arange(10) * 2
>>> a = np.arange(10) ** 2.
>>> ddof = 1
>>> w = f * a
>>> v1 = np.sum(w)
>>> v2 = np.sum(w * a)
>>> m -= np.sum(m * w, axis=None, keepdims=True) / v1
>>> cov = np.dot(m * w, m.T) * v1 / (v1**2 - ddof * v2) 

请注意，当a == 1时，归一化因子v1 / (v1**2 - ddof * v2)应为1 / (np.sum(f) - ddof)。

示例

考虑两个变量，(x_0)和(x_1)，它们之间存在完美的负相关关系：

>>> x = np.array([[0, 2], [1, 1], [2, 0]]).T
>>> x
array([[0, 1, 2],
 [2, 1, 0]]) 

注意当(x_0)增加时，(x_1)减少。协方差矩阵清楚地显示了这一点：

>>> np.cov(x)
array([[ 1., -1.],
 [-1.,  1.]]) 

请注意元素(C_{0,1})，显示了(x_0)和(x_1)之间的相关性为负。

此外，注意x和y是如何结合在一起的：

>>> x = [-2.1, -1,  4.3]
>>> y = [3,  1.1,  0.12]
>>> X = np.stack((x, y), axis=0)
>>> np.cov(X)
array([[11.71      , -4.286     ], # may vary
 [-4.286     ,  2.144133]])
>>> np.cov(x, y)
array([[11.71      , -4.286     ], # may vary
 [-4.286     ,  2.144133]])
>>> np.cov(x)
array(11.71) 

numpy.histogram

原文：numpy.org/doc/1.26/reference/generated/numpy.histogram.html

numpy.histogram(a, bins=10, range=None, density=None, weights=None)

计算数据集的直方图。

参数:

a类似数组

输入数据。直方图是在扁平化数组上计算的。

bins整数或标量序列或字符串，可选

如果bins为整数，则定义给定范围内等宽箱的数量（默认为 10）。如果bins为序列，则定义一个单调递增的箱边数组，包括最右边的边缘，允许不均匀的箱宽。

新版本 1.11.0 中引入。

如果bins为字符串，则定义用于计算最佳箱宽的方法，定义为histogram_bin_edges。

range（浮点数，浮点数），可选

箱子的下限和上限。如果未提供，则范围简单地为(a.min(), a.max())。超出范围的值将被忽略。范围的第一个元素必须小于或等于第二个元素。range也会影响自动箱计算。虽然根据range内的实际数据计算出最优的箱宽，但箱数将填满整个范围，包括不包含数据的部分。

weights类似数组，可选

与a形状相同的权重数组。仅对a中的每个值对应的权重对箱计数做贡献（而不是 1）。如果density为 True，则权重将被归一化，以使范围上的密度积分保持为 1。

density布尔型，可选

如果为False，结果将包含每个箱中的样本数。如果为True，结果是箱中概率密度函数的值，在此范围上归一化为 1。请注意，直方图值的总和除非选择单位宽度的箱子，否则将不等于 1；这不是概率质量函数。

返回：

hist数组

直方图的值。请参阅密度和权重以了解可能的语义。

bin_edges浮点数数组

返回箱边（hist 的长度+1）。

另请参阅

histogramdd, bincount, searchsorted, digitize, histogram_bin_edges

注释

所有除了最后（右手边最大）箱子都是半开放的。换句话说，如果bins为：

[1, 2, 3, 4] 

那么第一个箱子是[1, 2)（包括 1，但不包括 2），第二个是[2, 3)。然而，最后一个箱子是[3, 4]，它包括4。

示例

>>> np.histogram([1, 2, 1], bins=[0, 1, 2, 3])
(array([0, 2, 1]), array([0, 1, 2, 3]))
>>> np.histogram(np.arange(4), bins=np.arange(5), density=True)
(array([0.25, 0.25, 0.25, 0.25]), array([0, 1, 2, 3, 4]))
>>> np.histogram([[1, 2, 1], [1, 0, 1]], bins=[0,1,2,3])
(array([1, 4, 1]), array([0, 1, 2, 3])) 

>>> a = np.arange(5)
>>> hist, bin_edges = np.histogram(a, density=True)
>>> hist
array([0.5, 0\. , 0.5, 0\. , 0\. , 0.5, 0\. , 0.5, 0\. , 0.5])
>>> hist.sum()
2.4999999999999996
>>> np.sum(hist * np.diff(bin_edges))
1.0 

新版本 1.11.0 中引入。

使用 2 个顶峰随机数据和 2000 个点的自动箱选择方法示例：

>>> import matplotlib.pyplot as plt
>>> rng = np.random.RandomState(10)  # deterministic random data
>>> a = np.hstack((rng.normal(size=1000),
...                rng.normal(loc=5, scale=2, size=1000)))
>>> _ = plt.hist(a, bins='auto')  # arguments are passed to np.histogram
>>> plt.title("Histogram with 'auto' bins")
Text(0.5, 1.0, "Histogram with 'auto' bins")
>>> plt.show() 

numpy.histogram2d

numpy.org/doc/1.26/reference/generated/numpy.histogram2d.html

numpy.histogram2d(x, y, bins=10, range=None, density=None, weights=None)

计算两个数据样本的二维直方图。

参数：

x array_like，形状(N,)

包含要进行直方图制作的点的 x 坐标的数组。

y array_like，形状(N,)

包含要进行直方图制作的点的 y 坐标的数组。

bins int 或 array_like 或[int, int]或[array, array]，可选

bin 规范：

• 如果为 int，则两个维度的 bin 数量(nx=ny=bins)。
• 如果是 array_like，则两个维度的 bin 边缘(x_edges=y_edges=bins)。
• 如果[int, int]，每个维度的 bin 数量(nx, ny = bins)。
• 如果为[array, array]，则两个维度中的 bin 边缘(x_edges, y_edges = bins)。
• 一个组合[int, array]或[array, int]，其中 int 是 bin 的数量，array 是 bin 的边缘。

range array_like，形状(2,2)，可选

沿每个维度的 bin 的最左边和最右边的边缘(如果在bins参数中没有明确指定)：[[xmin, xmax], [ymin, ymax]]。此范围之外的所有值将被视为异常值，不计入直方图。

density bool，可选

如果为 False，返回每个 bin 中的样本数量。如果为 True，返回 bin 处的概率density函数，bin_count / sample_count / bin_area。

weights array_like，形状(N,)，可选

一个加权值数组w_i，对每个样本(x_i, y_i)进行加权。如果density为 True，则将对权重进行归一化为 1。如果density为 False，则返回的直方图的值等于落入每个 bin 的样本的权重之和。

返回：

H ndarray，形状(nx, ny)

与样本x和y的二维直方图。x中的值沿第一个维度进行直方图处理，而y中的值沿第二个维度进行直方图处理。

xedges ndarray，形状(nx+1,)

第一个维度的 bin 边缘。

yedges ndarray，形状(ny+1,)

第二个维度的 bin 边缘。

参见

histogram

1D 直方图

histogramdd

多维直方图

注意

当density为 True 时，返回的直方图是样本密度，定义为对bin_value * bin_area的乘积的所有 bin 的总和为 1。

请注意，直方图不遵循笛卡尔坐标系的惯例，其中x值在横轴上，y值在纵轴上。相反，x沿数组的第一个维度(垂直)进行直方图处理，y沿数组的第二个维度(水平)进行直方图处理。这确保与histogramdd的兼容性。

示例

>>> from matplotlib.image import NonUniformImage
>>> import matplotlib.pyplot as plt 

使用可变 bin 宽度构建 2-D 直方图。首先定义 bin 的边缘：

>>> xedges = [0, 1, 3, 5]
>>> yedges = [0, 2, 3, 4, 6] 

接下来我们创建一个具有随机 bin 内容的直方图 H：

>>> x = np.random.normal(2, 1, 100)
>>> y = np.random.normal(1, 1, 100)
>>> H, xedges, yedges = np.histogram2d(x, y, bins=(xedges, yedges))
>>> # Histogram does not follow Cartesian convention (see Notes),
>>> # therefore transpose H for visualization purposes.
>>> H = H.T 

imshow（https://matplotlib.org/stable/api/_as-gen/matplotlib.pyplot.imshow.html#matplotlib.pyplot.imshow）只能显示方形箱子：

>>> fig = plt.figure(figsize=(7, 3))
>>> ax = fig.add_subplot(131, title='imshow: square bins')
>>> plt.imshow(H, interpolation='nearest', origin='lower',
...         extent=[xedges[0], xedges[-1], yedges[0], yedges[-1]])
<matplotlib.image.AxesImage object at 0x...> 

pcolormesh（https://matplotlib.org/stable/api/_as-gen/matplotlib.pyplot.pcolormesh.html#matplotlib.pyplot.pcolormesh）可以显示实际的边缘：

>>> ax = fig.add_subplot(132, title='pcolormesh: actual edges',
...         aspect='equal')
>>> X, Y = np.meshgrid(xedges, yedges)
>>> ax.pcolormesh(X, Y, H)
<matplotlib.collections.QuadMesh object at 0x...> 

NonUniformImage（https://matplotlib.org/stable/api/image_api.html#matplotlib.image.NonUniformImage）可用于显示实际的箱边和插值：

>>> ax = fig.add_subplot(133, title='NonUniformImage: interpolated',
...         aspect='equal', xlim=xedges[[0, -1]], ylim=yedges[[0, -1]])
>>> im = NonUniformImage(ax, interpolation='bilinear')
>>> xcenters = (xedges[:-1] + xedges[1:]) / 2
>>> ycenters = (yedges[:-1] + yedges[1:]) / 2
>>> im.set_data(xcenters, ycenters, H)
>>> ax.add_image(im)
>>> plt.show() 

也可以构建一个二维直方图而不指定箱边：

>>> # Generate non-symmetric test data
>>> n = 10000
>>> x = np.linspace(1, 100, n)
>>> y = 2*np.log(x) + np.random.rand(n) - 0.5
>>> # Compute 2d histogram. Note the order of x/y and xedges/yedges
>>> H, yedges, xedges = np.histogram2d(y, x, bins=20) 

现在我们可以使用pcolormesh（https://matplotlib.org/stable/api/_as-gen/matplotlib.pyplot.pcolormesh.html#matplotlib.pyplot.pcolormesh）绘制直方图，并使用hexbin（https://matplotlib.org/stable/api/_as-gen/matplotlib.pyplot.hexbin.html#matplotlib.pyplot.hexbin）进行比较。

>>> # Plot histogram using pcolormesh
>>> fig, (ax1, ax2) = plt.subplots(ncols=2, sharey=True)
>>> ax1.pcolormesh(xedges, yedges, H, cmap='rainbow')
>>> ax1.plot(x, 2*np.log(x), 'k-')
>>> ax1.set_xlim(x.min(), x.max())
>>> ax1.set_ylim(y.min(), y.max())
>>> ax1.set_xlabel('x')
>>> ax1.set_ylabel('y')
>>> ax1.set_title('histogram2d')
>>> ax1.grid() 

>>> # Create hexbin plot for comparison
>>> ax2.hexbin(x, y, gridsize=20, cmap='rainbow')
>>> ax2.plot(x, 2*np.log(x), 'k-')
>>> ax2.set_title('hexbin')
>>> ax2.set_xlim(x.min(), x.max())
>>> ax2.set_xlabel('x')
>>> ax2.grid() 

>>> plt.show() 

numpy.histogramdd

原文：numpy.org/doc/1.26/reference/generated/numpy.histogramdd.html

numpy.histogramdd(sample, bins=10, range=None, density=None, weights=None)

计算一些数据的多维直方图。

参数：

sample（N，D）数组，或（N，D）array_like

要制作直方图的数据。

注意当 array_like 时，样本的不寻常解释：

• 当数组时，每行是 D 维空间中的一个坐标，例如histogramdd(np.array([p1, p2, p3]))。

• 当 array_like 时，每个元素是单个坐标的值列表，例如 histogramdd((X, Y, Z))。

应优先使用第一种形式。

bins序列或 int，可选

箱子规格：

• 一系列描述沿每个维度单调增加的箱边的数组。

• 每个维度的箱数（nx，ny，... = bins）

• 所有维度的箱数（nx=ny=…= bins）。

range序列，可选

长度为 D 的序列，每个序列都是一个可选的（lower，upper）元组，给出如果边界没有在bins中显式地给出时要使用的外部箱边缘。序列中的 None 条目导致相应维度的最小值和最大值被用于。默认值 None 相当于传递了 D 个 None 值的元组。

density布尔值，可选

如果为 False，返回每个箱中的样本数。如果为 True，则返回在箱中的概率密度函数，bin_count / sample_count / bin_volume。

weights（N，）array_like，可选

一系列值w_i，用于加权每个样本(x_i, y_i, z_i, ...)。如果密度为 True，则权重被标准化为 1。如果密度为 False，则返回的直方图的值等于属于落入每个箱中的样本的权重之和。

返回：

H ndarray

样本 x 的多维直方图。请参阅密度和权重以了解不同的可能语义。

edges列表

由 D 个数组描述每个维度的箱边的列表。

另请参阅

histogram

1-D 直方图

histogram2d

2-D 直方图

示例

>>> r = np.random.randn(100,3)
>>> H, edges = np.histogramdd(r, bins = (5, 8, 4))
>>> H.shape, edges[0].size, edges[1].size, edges[2].size
((5, 8, 4), 6, 9, 5) 

numpy.bincount

原文：numpy.org/doc/1.26/reference/generated/numpy.bincount.html

numpy.bincount(x, /, weights=None, minlength=0)

统计非负整数数组中每个值的出现次数。

bins 的数量（大小为 1）比x中的最大值大 1。如果指定了minlength，输出数组中至少会有这么多个 bins（如果有必要，根据x的内容，它可能会更长）。每个 bin 给出x中其索引值出现的次数。如果指定了weights，输入数组将被它加权，即如果在位置i找到值n，则out[n] += weight[i]，而不是out[n] += 1。

参数：

xarray_like，1 维，非负整数

输入数组。

weightsarray_like，可选

权重，与x的形状相同的数组。

minlengthint，可选

输出数组的最小数量的 bin。

版本 1.6.0 中的新内容。

返回结果：

out一维整数数组

将输入数组进行分箱的结果。out的长度等于np.amax(x)+1。

引发：

ValueError

如果输入不是一维的，或者包含负值的元素，或者minlength为负。

TypeError

如果输入的类型为浮点数或复数。

另请参见

histogram, digitize, unique

示例

>>> np.bincount(np.arange(5))
array([1, 1, 1, 1, 1])
>>> np.bincount(np.array([0, 1, 1, 3, 2, 1, 7]))
array([1, 3, 1, 1, 0, 0, 0, 1]) 

>>> x = np.array([0, 1, 1, 3, 2, 1, 7, 23])
>>> np.bincount(x).size == np.amax(x)+1
True 

输入数组需要为整数类型，否则会引发 TypeError：

>>> np.bincount(np.arange(5, dtype=float))
Traceback (most recent call last):
  ...
TypeError: Cannot cast array data from dtype('float64') to dtype('int64')
according to the rule 'safe' 

bincount的一种可能用途是使用weights关键字对数组的可变大小块进行求和。

>>> w = np.array([0.3, 0.5, 0.2, 0.7, 1., -0.6]) # weights
>>> x = np.array([0, 1, 1, 2, 2, 2])
>>> np.bincount(x,  weights=w)
array([ 0.3,  0.7,  1.1]) 

numpy.histogram_bin_edges

原文：numpy.org/doc/1.26/reference/generated/numpy.histogram_bin_edges.html

numpy.histogram_bin_edges(a, bins=10, range=None, weights=None)

用于计算histogram函数使用的箱边缘的函数。

参数：

aarray_like

输入数据。直方图是在平坦的数组上计算的。

binsint 或标量序列或 str， 可选

如果bins是一个整数，则它定义了给定范围内等宽箱的数量（默认为 10）。如果bins是一个序列，则它定义了箱边缘，包括右边的边缘，允许非均匀的箱宽。

如果bins是下面列表中的字符串之一, histogram_bin_edges将利用所选的方法来计算最佳箱宽，从而计算出难以掉落在所要求范围内的数据的箱的数量（有关估计器的更多细节，请参见注释）。虽然箱宽对范围内的实际数据最佳，但箱数量将被计算，以填满整个范围，包括空的部分。对于可视化，建议使用‘auto’选项。不支持自动箱大小选择的加权数据。

‘auto’

‘sturges’和‘fd’估计器的最大值。提供全面的优越性能。

‘fd’（Freedman Diaconis 估计器）

鲁棒（对异常值具有韧性）的估计器，需要考虑数据的变化性和数据规模。

‘doane’

与 Sturges’估计器的改进版本，更适用于非正态数据集。

‘scott’

考虑数据变异性和数据规模的相对不那么鲁棒的估计器。

‘stone’

基于留一法交叉验证估计积分平方误差。可以看作是 Scott’s 法规的一般化。

‘rice’

估计器不考虑变异性，只考虑数据大小。通常高估所需的箱的数量。

‘sturges’

R 的默认方法，只考虑数据规模。仅适用于高斯数据，并且低估大型非高斯数据集的箱的数量。

‘sqrt’

数据规模的平方根估计器，由 Excel 和其他程序使用，因其速度和简单性。

浮点数, 浮点数), 可选

箱的上限范围。如果未提供，范围简单地是(a.min(), a.max())。超出范围的值将被忽略。范围的第一个元素必须小于或等于第二个元素。range也会影响自动箱计算。虽然基于range内实际数据计算出最佳的箱宽，但箱数量将填满整个范围，包括不含数据的部分。

weightsarray_like, 可选

与a形状相同的权重数组。a中的每个值只对箱计数贡献其关联的权重（而不是 1）。目前还没有任何箱估计器使用这个，但将来可能会使用。

返回：

bin_edges浮点数 dtype 的数组

向 histogram 传入的边缘

另请参阅

histogram

注意

通过文献提供的方法来估计最佳柱数，这些方法受到了 R 提供直方图可视化的启发。注意，将柱的数量与 (n^{1/3}) 成比例是渐近最优的，这也是大多数估计器中出现的原因。这些只是提供柱数量的良好起点的插入方法。在下面的方程中，(h) 是柱宽，(n_h) 是柱数量。所有计算柱计数的估计器都使用数据的 ptp 重新调整为柱宽度。最终的柱计数是通过 np.round(np.ceil(range / h)) 得到的。最终的柱宽度通常小于下面估计器返回的值。

‘auto’（‘sturges’ 和 ‘fd’ 估计器的最大值）

通过不同估计器之间的权衡得到一个良好的值。对于小数据集，通常选择 Sturges 值，而对于大数据集，通常默认为 FD。避免了 FD 和 Sturges 对小和大数据集的过于保守行为。切换点通常是 (a.size \approx 1000)。

‘fd’（Freedman-Diaconis 估计器）

[h = 2 \frac{IQR}{n^{1/3}}]

The binwidth is proportional to the interquartile range (IQR) and inversely proportional to cube root of a.size. Can be too conservative for small datasets, but is quite good for large datasets. The IQR is very robust to outliers.

‘scott’

[h = \sigma \sqrt[3]{\frac{24 \sqrt{\pi}}{n}}]

The binwidth is proportional to the standard deviation of the data and inversely proportional to cube root of x.size. Can be too conservative for small datasets, but is quite good for large datasets. The standard deviation is not very robust to outliers. Values are very similar to the Freedman-Diaconis estimator in the absence of outliers.

‘rice’

[n_h = 2n^{1/3}]

柱的数量仅与 a.size 的立方根成比例。它往往会高估柱的数量，而且它不考虑数据的变异性。

‘sturges’

[n_h = \log _{2}(n) + 1]

柱的数量是 a.size 的以 2 为底的对数。该估计器假设数据呈正态分布，对于较大、非正态的数据过于保守。这是 R 中 hist 方法的默认方法。

‘doane’

[ \begin{align}\begin{aligned}n_h = 1 + \log_{2}(n) + \log_{2}\left(1 + \frac{|g_1|}{\sigma_{g_1}}\right)\g_1 = mean\left[\left(\frac{x - \mu}{\sigma}\right)³\right]\\sigma_{g_1} = \sqrt{\frac{6(n - 2)}{(n + 1)(n + 3)}}\end{aligned}\end{align} ]

对非正态数据产生更好的估计的 Sturges 公式的改进版本。该估计器试图解释数据的偏斜。

‘sqrt’

[n_h = \sqrt n]

最简单和最快速的估计器。只考虑数据的大小。

示例

>>> arr = np.array([0, 0, 0, 1, 2, 3, 3, 4, 5])
>>> np.histogram_bin_edges(arr, bins='auto', range=(0, 1))
array([0\.  , 0.25, 0.5 , 0.75, 1\.  ])
>>> np.histogram_bin_edges(arr, bins=2)
array([0\. , 2.5, 5\. ]) 

为了与直方图保持一致，一个预先计算的箱子数组被不经修改地传递：

>>> np.histogram_bin_edges(arr, [1, 2])
array([1, 2]) 

这个函数允许计算一组箱子，并在多个直方图中重复使用：

>>> shared_bins = np.histogram_bin_edges(arr, bins='auto')
>>> shared_bins
array([0., 1., 2., 3., 4., 5.]) 

>>> group_id = np.array([0, 1, 1, 0, 1, 1, 0, 1, 1])
>>> hist_0, _ = np.histogram(arr[group_id == 0], bins=shared_bins)
>>> hist_1, _ = np.histogram(arr[group_id == 1], bins=shared_bins) 

>>> hist_0; hist_1
array([1, 1, 0, 1, 0])
array([2, 0, 1, 1, 2]) 

哪种方法提供的结果更容易比较，而不是为每个直方图使用单独的箱子：

>>> hist_0, bins_0 = np.histogram(arr[group_id == 0], bins='auto')
>>> hist_1, bins_1 = np.histogram(arr[group_id == 1], bins='auto')
>>> hist_0; hist_1
array([1, 1, 1])
array([2, 1, 1, 2])
>>> bins_0; bins_1
array([0., 1., 2., 3.])
array([0\.  , 1.25, 2.5 , 3.75, 5\.  ]) 

numpy.digitize

原文：numpy.org/doc/1.26/reference/generated/numpy.digitize.html

numpy.digitize(x, bins, right=False)

返回输入数组中每个值所属的区间的索引。

right	区间顺序	返回的索引 i 满足
False	递增	bins[i-1] <= x < bins[i]
True	递增	bins[i-1] < x <= bins[i]
False	递减	bins[i-1] > x >= bins[i]
True	递减	bins[i-1] >= x > bins[i]

如果x中的值超出bins的范围，则适当返回 0 或len(bins)。

参数：

xarray_like

要进行分箱的输入数组。在 NumPy 1.10.0 之前，此数组必须是一维的，但现在可以具有任何形状。

binsarray_like

区间数组。必须是一维且单调递增的。

rightbool，可选

指示区间是否包括右边缘或左边缘。默认行为是（right==False），表示区间不包括右边缘。在这种情况下，左边缘是开放的，即，对于单调递增的区间，bins[i-1] <= x < bins[i] 是默认行为。

返回：

indices整数的 ndarray

与x相同形状的索引输出数组。

引发：

值错误

如果 bins 不是单调的。

类型错误

如果输入的类型是复数。

另请参阅

bincount, histogram, unique, searchsorted

注意事项

如果x中的值使其超出区间范围，则尝试使用digitize 返回的索引索引bins将导致 IndexError。

新版本 1.10.0 中新增。

np.digitize 是基于 np.searchsorted 实现的。这意味着使用二分搜索对值进行分箱，对于更大数量的区间，比以前的线性搜索更具规模优势。它还消除了输入数组必须是一维的要求。

对于单调 _ 递增 _ 的 bins，以下是等效的：

np.digitize(x, bins, right=True)
np.searchsorted(bins, x, side='left') 

请注意，由于参数的顺序已颠倒，因此侧边也必须如此。searchsorted 调用稍微更快，因为它不执行任何单调性检查。或许更重要的是，它支持所有的数据类型。

示例

>>> x = np.array([0.2, 6.4, 3.0, 1.6])
>>> bins = np.array([0.0, 1.0, 2.5, 4.0, 10.0])
>>> inds = np.digitize(x, bins)
>>> inds
array([1, 4, 3, 2])
>>> for n in range(x.size):
...   print(bins[inds[n]-1], "<=", x[n], "<", bins[inds[n]])
...
0.0 <= 0.2 < 1.0
4.0 <= 6.4 < 10.0
2.5 <= 3.0 < 4.0
1.0 <= 1.6 < 2.5 

>>> x = np.array([1.2, 10.0, 12.4, 15.5, 20.])
>>> bins = np.array([0, 5, 10, 15, 20])
>>> np.digitize(x,bins,right=True)
array([1, 2, 3, 4, 4])
>>> np.digitize(x,bins,right=False)
array([1, 3, 3, 4, 5]) 

测试支持（numpy.testing）

原文：numpy.org/doc/1.26/reference/routines.testing.html

所有 numpy 测试脚本的通用测试支持。

这个单一模块应该在一个位置提供所有 numpy 测试的通用功能，因此 test scripts 可以直接导入它并立即运行。更多背景信息，请参阅测试指南

断言

assert_allclose(actual, desired[, rtol, ...])	如果两个对象不等到期望的公差，将引发 AssertionError。
assert_array_almost_equal_nulp(x, y[, nulp])	相对于它们的间距比较两个数组。
assert_array_max_ulp(a, b[, maxulp, dtype])	检查所有数组项在最后位置上的单位最多相差 N 个单位。
assert_array_equal(x, y[, err_msg, verbose, ...])	如果两个 array_like 对象不相等，则引发 AssertionError。
assert_array_less(x, y[, err_msg, verbose])	如果两个 array_like 对象不按顺序排列，则引发 AssertionError。
assert_equal(actual, desired[, err_msg, verbose])	如果两个对象不等，则引发 AssertionError。
assert_raises(assert_raises)	除非在使用参数 args 和关键字参数 kwargs 调用可调用函数时抛出 exception_class 类的异常，否则将失败。
assert_raises_regex(exception_class, ...)	除非在使用参数 args 和关键字参数 kwargs 调用可调用函数时抛出类为 exception_class 并且带有匹配预期正则表达式的消息的异常，否则将失败。
assert_warns(warning_class, *args, **kwargs)	除非给定的可调用函数引发指定的警告，否则将失败。
assert_no_warnings(*args, **kwargs)	如果给定的可调用对象产生任何警告，则失败。
assert_no_gc_cycles(*args, **kwargs)	如果给定的可调用对象产生任何引用循环，则失败。
assert_string_equal(actual, desired)	测试两个字符串是否相等。

断言（不建议使用）

建议使用 assert_allclose、assert_array_almost_equal_nulp 或 assert_array_max_ulp 替代这些函数，以进行更一致的浮点数比较。

assert_(val[, msg])	在发布模式下运行的断言。
assert_almost_equal(actual, desired[, ...])	如果两个项目在所需精度上不相等，则引发 AssertionError。
assert_approx_equal(actual, desired[, ...])	如果两个项目在有效数字上不相等，则引发 AssertionError。
assert_array_almost_equal(x, y[, decimal, ...])	如果两个对象在所需精度上不相等，则引发 AssertionError。
print_assert_equal(test_string, actual, desired)	测试两个对象是否相等，如果测试失败则打印错误消息。

装饰器

decorate_methods(cls, decorator[, testmatch])	将装饰器应用于类中所有与正则表达式匹配的方法。

测试运行

clear_and_catch_warnings([record, modules])	重置警告注册表以捕获警告的上下文管理器。
measure(code_str[, times, label])	返回在调用者命名空间中执行代码的经过时间。
rundocs([filename, raise_on_error])	运行给定文件中的 doctests。
suppress_warnings([forwarding_rule])	上下文管理器和装饰器的作用与warnings.catch_warnings相似。

指南

• 测试指南

  • 介绍

  • 测试 NumPy

    • 从 Python 内部运行测试

    • 从命令行运行测试

    • 运行测试的其他方法

  • 编写自己的测试

    • 在测试中使用 C 代码

      • build_and_import_extension

    • 测试标记

    • 更简单的设置和拆卸函数/方法

    • 参数化测试

    • Doctests(文档测试)

    • tests/

    • __init__.py和setup.py

  • 技巧和窍门

    • 创建许多相似的测试

    • 已知失败和跳过测试

    • 对随机数据进行测试

    • numpy.test的文档

      • test

断言

assert_allclose(actual, desired[, rtol, ...])	如果两个对象在期望的容差范围内不相等，则引发 AssertionError。
assert_array_almost_equal_nulp(x, y[, nulp])	相对于它们的间距比较两个数组。
assert_array_max_ulp(a, b[, maxulp, dtype])	检查数组的所有元素在最后一位单位内的差异最多为 N 个单位。
assert_array_equal(x, y[, err_msg, verbose, ...])	如果两个类似数组对象不相等，则引发 AssertionError。
assert_array_less(x, y[, err_msg, verbose])	如果两个类似数组对象的顺序不是按照小于来排列，则引发 AssertionError。
assert_equal(actual, desired[, err_msg, verbose])	如果两个对象不相等，则引发 AssertionError。
assert_raises(assert_raises)	除非在调用参数为 args 和关键字参数为 kwargs 的可调用函数时抛出 exception_class 类的异常，则不通过。
assert_raises_regex(exception_class, ...)	除非在调用参数为 args 和关键字参数为 kwargs 的可调用函数时抛出的消息与预期的正则表达式匹配的类为 exception_class 的异常，则不通过。
assert_warns(warning_class, *args, **kwargs)	除非给定的可调用函数引发指定的警告，否则不通过。
assert_no_warnings(*args, **kwargs)	如果给定的可调用函数产生任何警告，则不通过。
assert_no_gc_cycles(*args, **kwargs)	如果给定的可调用函数产生任何引用循环，则不通过。
assert_string_equal(actual, desired)	测试两个字符串是否相等。

断言（不推荐使用）

建议使用 assert_allclose、assert_array_almost_equal_nulp 或 assert_array_max_ulp 中的一个，而不是使用这些函数进行更一致的浮点数比较。

assert_(val[, msg])	在发布模式下工作的断言。
assert_almost_equal(actual, desired[, ...])	如果两个项目不在期望的精度范围内相等，则引发 AssertionError。
assert_approx_equal(actual, desired[, ...])	如果两个项目不符合预期的有效位数，则引发 AssertionError。
assert_array_almost_equal(x, y[, decimal, ...])	如果两个对象不符合期望精度，则引发 AssertionError。
print_assert_equal(test_string, actual, desired)	测试两个对象是否相等，如果测试失败则打印错误信息。

装饰器

decorate_methods(cls, decorator[, testmatch])	对类中匹配正则表达式的所有方法应用装饰器。

测试运行

clear_and_catch_warnings([record, modules])	上下文管理器，用于捕获警告的情况下重置警告注册表
measure(code_str[, times, label])	返回在调用者命名空间中执行代码的经过时间。
rundocs([filename, raise_on_error])	运行给定文件中的 doctests。
suppress_warnings([forwarding_rule])	上下文管理器和装饰器，做了类似于 warnings.catch_warnings 的事情。

指南

• 测试指南

  • 介绍

  • 测试 NumPy

    • 从 Python 中运行测试

    • 从命令行运行测试

    • 运行测试的其他方法

  • 编写自己的测试

    • 在测试中使用 C 代码

      • build_and_import_extension

    • 为测试打标签

    • 更容易的设置和拆卸功能/方法

    • 参数化测试

    • Doctests

    • tests/

    • __init__.py 和 setup.py

  • 技巧

    • 创建许多相似的测试

    • 已知失败 & 跳过测试

    • 随机数据上的测试

    • numpy.test的文档

      • test

numpy.testing.assert_allclose

原文：numpy.org/doc/1.26/reference/generated/numpy.testing.assert_allclose.html

testing.assert_allclose(actual, desired, rtol=1e-07, atol=0, equal_nan=True, err_msg='', verbose=True)

如果两个对象不相等，就会引发 AssertionError。

给定两个类数组对象，检查它们的形状和所有元素是否相等（但参见标量的特殊处理）。如果形状不匹配或任何值冲突，则会引发异常。与 numpy 中的标准用法不同，NaN 会像数字一样进行比较，如果两个对象在相同位置都有 NaN，则不会引发断言。

该测试相当于allclose(actual, desired, rtol, atol)（注意allclose具有不同的默认值）。它比较actual和desired的差异与atol + rtol * abs(desired)。

版本 1.5.0 中的新内容。

参数：

actual类数组

获得的数组。

desired类数组

期望的数组。

rtol浮点数，可选

相对容差。

atol浮点数，可选

绝对容差。

equal_nan布尔值，可选。

如果为 True，NaN 会比较相等。

err_msg字符串，可选

失败时打印的错误消息。

verbose布尔值，可选

如果为 True，冲突的值将附加到错误消息中。

引发：

断言错误

如果实际值和期望值在指定精度上不相等。

参见

assert_array_almost_equal_nulp，assert_array_max_ulp

注意

当actual和desired之一是标量而另一个是类数组时，函数会检查类数组对象的每个元素是否等于标量。

示例

>>> x = [1e-5, 1e-3, 1e-1]
>>> y = np.arccos(np.cos(x))
>>> np.testing.assert_allclose(x, y, rtol=1e-5, atol=0) 

numpy.testing.assert_array_almost_equal_nulp

原文：numpy.org/doc/1.26/reference/generated/numpy.testing.assert_array_almost_equal_nulp.html

testing.assert_array_almost_equal_nulp(x, y, nulp=1)

相对于它们的间距比较两个数组。

这是一种相对稳健的方法，可比较幅度变化的两个数组。

参数：

x, yarray_like

输入数组。

nulpint，可选

公差的最大最后一位单位数（请参见注意事项）。默认值为 1。

返回：

无

引发：

AssertionError

如果一个或多个元素的x和y之间的间距大于nulp。

参见

assert_array_max_ulp

检查数组的所有项是否在最后一位最多相差 N 个单位。

spacing

返回x和最近的相邻数字之间的距离。

注意事项

如果不符合以下条件，则会引发断言：

abs(x - y) <= nulp * spacing(maximum(abs(x), abs(y))) 

举例

>>> x = np.array([1., 1e-10, 1e-20])
>>> eps = np.finfo(x.dtype).eps
>>> np.testing.assert_array_almost_equal_nulp(x, x*eps/2 + x) 

>>> np.testing.assert_array_almost_equal_nulp(x, x*eps + x)
Traceback (most recent call last):
  ...
AssertionError: X and Y are not equal to 1 ULP (max is 2) 

numpy.testing.assert_array_max_ulp

原文：numpy.org/doc/1.26/reference/generated/numpy.testing.assert_array_max_ulp.html

testing.assert_array_max_ulp(a, b, maxulp=1, dtype=None)

检查数组中所有项目的最后一位的单位之间的差异是否至多为 N 个。

参数：

a, barray_like

要比较的输入数组。

maxulpint，可选

a和b元素之间可以有的最大单位数。默认值为 1。

dtypedtype，可选

如果提供，则转换a和b的数据类型。默认值为 None。

返回：

retndarray

包含a和b之间可表示的浮点数的数组。

引发：

断言错误

如果一个或多个元素的差异超过maxulp。

另请参阅

assert_array_almost_equal_nulp

相对于它们的间距比较两个数组。

注意

用于计算 ULP 差异，此 API 不区分 NAN 的各种表示形式（0x7fc00000 和 0xffc00000 之间的 ULP 差异为零）。

示例

>>> a = np.linspace(0., 1., 100)
>>> res = np.testing.assert_array_max_ulp(a, np.arcsin(np.sin(a))) 

numpy.testing.assert_array_equal

原文：numpy.org/doc/1.26/reference/generated/numpy.testing.assert_array_equal.html

testing.assert_array_equal(x, y, err_msg='', verbose=True, *, strict=False)

如果两个类似数组对象不相等，则引发 AssertionError。

给定两个类似数组的对象，检查形状是否相等，并且这些对象的所有元素是否相等（但请参见标量的特殊处理的注释部分）。如果形状不匹配或值冲突，将引发异常。与 numpy 中的标准用法相反，NaN 将被视为数字进行比较，如果两个对象在相同位置具有 NaN，则不会引发断言。

建议使用浮点数验证相等性时应保持常规谨慎。

参数：

xarray_like

要检查的实际对象。

yarray_like

所需的，期望的对象。

err_msgstr，可选

在比较标量与数组时引发 AssertionError 的错误消息。

verbosebool，可选

如果为 True，则冲突的值将追加到错误消息中。

strictbool，可选

如果为 True，则在数组对象的形状或数据类型不匹配时引发 AssertionError。禁用了在注释部分提到的标量的特殊处理。

版本 1.24.0 中的新功能。

引发：

AssertionError

如果实际对象和期望对象不相等。

另请参阅

assert_allclose

使用所需的相对和/或绝对精度比较两个类似数组的对象是否相等。

assert_array_almost_equal_nulp，assert_array_max_ulp，assert_equal

注释

当 x 和 y 中的一个是标量，另一个是类似数组时，函数将检查类似数组对象的每个元素是否等于标量。可以使用 strict 参数禁用此行为。

示例

第一个断言不会引发异常：

>>> np.testing.assert_array_equal([1.0,2.33333,np.nan],
...                               [np.exp(0),2.33333, np.nan]) 

对于浮点数存在数值不精确的断言失败：

>>> np.testing.assert_array_equal([1.0,np.pi,np.nan],
...                               [1, np.sqrt(np.pi)**2, np.nan])
Traceback (most recent call last):
  ...
AssertionError:
Arrays are not equal

Mismatched elements: 1 / 3 (33.3%)
Max absolute difference: 4.4408921e-16
Max relative difference: 1.41357986e-16
 x: array([1\.      , 3.141593,      nan])
 y: array([1\.      , 3.141593,      nan]) 

对于这些情况，请使用 assert_allclose 或 nulp（浮点数值的数量）函数之一：

>>> np.testing.assert_allclose([1.0,np.pi,np.nan],
...                            [1, np.sqrt(np.pi)**2, np.nan],
...                            rtol=1e-10, atol=0) 

正如在注释部分中提到的，assert_array_equal 对标量具有特殊处理。此处的测试检查 x 中的每个值是否为 3：

>>> x = np.full((2, 5), fill_value=3)
>>> np.testing.assert_array_equal(x, 3) 

使用 strict 来确保数组数据类型匹配：

>>> np.testing.assert_array_equal(x, 3, strict=True)
Traceback (most recent call last):
  ...
AssertionError:
Arrays are not equal

(shapes (2, 5), () mismatch)
 x: array([[3, 3, 3, 3, 3],
 [3, 3, 3, 3, 3]])
 y: array(3) 

strict 参数还确保数组数据类型匹配：

>>> x = np.array([2, 2, 2])
>>> y = np.array([2., 2., 2.], dtype=np.float32)
>>> np.testing.assert_array_equal(x, y, strict=True)
Traceback (most recent call last):
  ...
AssertionError:
Arrays are not equal

(dtypes int64, float32 mismatch)
 x: array([2, 2, 2])
 y: array([2., 2., 2.], dtype=float32) 

numpy.testing.assert_array_less

原文：numpy.org/doc/1.26/reference/generated/numpy.testing.assert_array_less.html

testing.assert_array_less(x, y, err_msg='', verbose=True)

如果两个类似数组对象不按小于进行排序，则引发 AssertionError。

给定两个类似数组对象，检查形状是否相等，以及第一个对象的所有元素是否严格小于第二个对象的元素。在形状不匹配或值错误排序时引发异常。如果对象的维度为零，则形状不匹配不会引发异常。与 numpy 中的标准用法相反，NaNs 会被比较，如果两个对象在相同位置具有 NaNs，则不会引发断言。

参数：

x 类似数组对象

要检查的较小对象。

y 类似数组对象

要比较的较大对象。

err_msg 字符串

在失败情况下打印的错误消息。

verbose 布尔类型

如果为 True，则将冲突的值附加到错误消息中。

引发：

AssertionError

如果 x 在元素级别上不严格小于 y。

另请参见

assert_array_equal

测试对象是否相等

assert_array_almost_equal

测试对象是否相等，精度高达

示例

>>> np.testing.assert_array_less([1.0, 1.0, np.nan], [1.1, 2.0, np.nan])
>>> np.testing.assert_array_less([1.0, 1.0, np.nan], [1, 2.0, np.nan])
Traceback (most recent call last):
  ...
AssertionError:
Arrays are not less-ordered

Mismatched elements: 1 / 3 (33.3%)
Max absolute difference: 1.
Max relative difference: 0.5
 x: array([ 1.,  1., nan])
 y: array([ 1.,  2., nan]) 

>>> np.testing.assert_array_less([1.0, 4.0], 3)
Traceback (most recent call last):
  ...
AssertionError:
Arrays are not less-ordered

Mismatched elements: 1 / 2 (50%)
Max absolute difference: 2.
Max relative difference: 0.66666667
 x: array([1., 4.])
 y: array(3) 

>>> np.testing.assert_array_less([1.0, 2.0, 3.0], [4])
Traceback (most recent call last):
  ...
AssertionError:
Arrays are not less-ordered

(shapes (3,), (1,) mismatch)
 x: array([1., 2., 3.])
 y: array([4]) 

numpy.testing.assert_equal

原文：numpy.org/doc/1.26/reference/generated/numpy.testing.assert_equal.html

testing.assert_equal(actual, desired, err_msg='', verbose=True)

如果两个对象不相等，则引发断言错误。

给定两个对象（标量、列表、元组、字典或 numpy 数组），检查这些对象的所有元素是否相等。在出现第一个冲突值时引发异常。

当actual和desired中的一个是标量，另一个是类似数组时，该函数会检查数组对象的每个元素是否等于标量。

该函数将处理 NaN 的比较，就好像 NaN 是一个“正常”的数字一样。也就是说，如果两个对象在相同位置都有 NaN，那么不会引发断言错误。这与 IEEE 关于 NaN 的标准相反，该标准规定 NaN 与任何东西的比较都必须返回 False。

参数：

actual 类似数组

要检查的对象。

desired 类似数组

期望的对象。

err_msg str，可选

在发生失败时要打印的错误消息。

verbose 布尔，可选

如果为 True，则冲突的值将添加到错误消息中。

引发：

断言错误

如果 actual 和 desired 不相等。

示例

>>> np.testing.assert_equal([4,5], [4,6])
Traceback (most recent call last):
  ...
AssertionError:
Items are not equal:
item=1
 ACTUAL: 5
 DESIRED: 6 

以下比较不会引发异常。输入中存在 NaN，但它们位于相同位置。

>>> np.testing.assert_equal(np.array([1.0, 2.0, np.nan]), [1, 2, np.nan]) 

numpy.testing.assert_raises

原文：numpy.org/doc/1.26/reference/generated/numpy.testing.assert_raises.html

testing.assert_raises(exception_class, callable, *args, **kwargs) assert_raises(exception_class)

testing.assert_raises(exception_class) → None

当使用参数 args 和关键字参数 kwargs 调用可调用对象时，如果抛出了 exception_class 类的异常，则失败。如果抛出了不同类型的异常，它不会被捕获，测试用例将被视为发生错误，就像发生了意外异常一样。

或者，assert_raises可以作为上下文管理器使用：

>>> from numpy.testing import assert_raises
>>> with assert_raises(ZeroDivisionError):
...     1 / 0 

等价于

>>> def div(x, y):
...     return x / y
>>> assert_raises(ZeroDivisionError, div, 1, 0) 

numpy.testing.assert_raises_regex

原文：numpy.org/doc/1.26/reference/generated/numpy.testing.assert_raises_regex.html

testing.assert_raises_regex(exception_class, expected_regexp, callable, *args, **kwargs) assert_raises_regex(exception_class, expected_regexp)

调用时使用参数 args 和关键字参数 kwargs 调用时，除非 callable 抛出与 expected_regexp 匹配的消息的 exception_class 类的异常，否则失败。

也可以像assert_raises一样作为上下文管理器使用。

备注

自 1.9.0 版本开始新增。

numpy.testing.assert_warns

原文：numpy.org/doc/1.26/reference/generated/numpy.testing.assert_warns.html

testing.assert_warns(warning_class, *args, **kwargs)

除非给定的可调用对象引发指定的警告，否则将失败。

当使用参数 args 和关键字参数 kwargs 调用时，应由可调用对象抛出 warning_class 类型的警告。如果抛出了不同类型的警告，则不会捕获。

如果调用时省略了除警告类之外的所有参数，则可用作上下文管理器：

使用 assert_warns(SomeWarning)：

do_something()

能够用作上下文管理器是 NumPy v1.11.0 中的新功能。

版本 1.4.0 中的新功能。

参数：

warning_class类

定义了 func 预期抛出的警告的类。

func可调用对象，可选

可调用对象进行测试

*args参数

func 的参数。

****kwargs**关键字参数

func 的关键字参数。

返回：

func 返回的值。

示例

>>> import warnings
>>> def deprecated_func(num):
...     warnings.warn("Please upgrade", DeprecationWarning)
...     return num*num
>>> with np.testing.assert_warns(DeprecationWarning):
...     assert deprecated_func(4) == 16
>>> # or passing a func
>>> ret = np.testing.assert_warns(DeprecationWarning, deprecated_func, 4)
>>> assert ret == 16 

numpy.testing.assert_no_warnings

原文：numpy.org/doc/1.26/reference/generated/numpy.testing.assert_no_warnings.html

testing.assert_no_warnings(*args, **kwargs)

如果给定的可调用对象产生任何警告，则失败。

如果所有参数被省略调用，则可用作上下文管理器：

使用 assert_no_warnings()：

do_something()

在 NumPy v1.11.0 中新增了作为上下文管理器使用的功能。

新版本 1.7.0 中新增功能。

参数：

funccallable

要测试的可调用对象。

*args参数

传递给 func 的参数。

****kwargs**关键字参数

传递给 func 的关键字参数。

返回：

func 返回的值。

numpy.testing.assert_no_gc_cycles

numpy.org/doc/1.26/reference/generated/numpy.testing.assert_no_gc_cycles.html

testing.assert_no_gc_cycles(*args, **kwargs)

如果给定的可调用函数产生任何引用循环，则失败。

如果所有参数都被省略调用，可以用作上下文管理器：

with assert_no_gc_cycles():

do_something()

自版本 1.15.0 新增。

参数：

func可调用函数

要测试的可调用函数。

*args参数

传递给func的参数。

****kwargs**关键字参数

传递给func的关键字参数。

返回：

什么都没有。结果被有意丢弃以确保所有循环

被发现。

numpy.testing.assert_string_equal

原文：numpy.org/doc/1.26/reference/generated/numpy.testing.assert_string_equal.html

testing.assert_string_equal(actual, desired)

测试两个字符串是否相等。

如果给定的字符串相等，assert_string_equal 什么也不做。 如果它们不相等，就会引发一个 AssertionError，并显示字符串之间的差异。

参数：

actualstr

要测试是否与期望字符串相等的字符串。

desiredstr

期望的字符串。

示例

>>> np.testing.assert_string_equal('abc', 'abc')
>>> np.testing.assert_string_equal('abc', 'abcd')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
...
AssertionError: Differences in strings:
- abc+ abcd?    + 

numpy.testing.assert_

原文：numpy.org/doc/1.26/reference/generated/numpy.testing.assert_.html

testing.assert_(val, msg='')

断言在发布模式下起作用。接受可调用的消息以延迟到失败时再进行评估。

Python 内置的 assert 在执行优化模式的代码时不起作用（使用 -O 标志）- 它不会生成任何字节码。

有关使用方法的文档，请参考 Python 文档。

numpy.testing.assert_almost_equal

原文：numpy.org/doc/1.26/reference/generated/numpy.testing.assert_almost_equal.html

testing.assert_almost_equal(actual, desired, decimal=7, err_msg='', verbose=True)

如果两个项目没有达到期望的精度，则引发 AssertionError。

注意

建议使用assert_allclose、assert_array_almost_equal_nulp或assert_array_max_ulp中的一个，而不是使用此函数进行更一致的浮点数比较。

该测试验证actual和desired的元素是否满足。

abs(desired-actual) < float64(1.5 * 10**(-decimal))

这个测试比最初文档中描述的宽松，但与assert_array_almost_equal中的实际实现一致，直到舍入不确定性。在冲突值时会引发异常。对于 ndarrays，这会委托给 assert_array_almost_equal

参数：

actual类似数组

要检查的对象。

desired类似数组

预期的对象。

decimalint，可选

期望的精度，默认为 7。

err_msgstr，可选

失败时打印的错误消息。

verbosebool，可选

如果为 True，则冲突的值将附加到错误消息中。

引发：

AssertionError

如果实际和期望不等到指定精度。

另请参阅

assert_allclose

使用期望的相对和/或绝对精度比较两个类似数组对象的相等性。

assert_array_almost_equal_nulp, assert_array_max_ulp, assert_equal

示例

>>> from numpy.testing import assert_almost_equal
>>> assert_almost_equal(2.3333333333333, 2.33333334)
>>> assert_almost_equal(2.3333333333333, 2.33333334, decimal=10)
Traceback (most recent call last):
  ...
AssertionError:
Arrays are not almost equal to 10 decimals
 ACTUAL: 2.3333333333333
 DESIRED: 2.33333334 

>>> assert_almost_equal(np.array([1.0,2.3333333333333]),
...                     np.array([1.0,2.33333334]), decimal=9)
Traceback (most recent call last):
  ...
AssertionError:
Arrays are not almost equal to 9 decimals

Mismatched elements: 1 / 2 (50%)
Max absolute difference: 6.66669964e-09
Max relative difference: 2.85715698e-09
 x: array([1\.         , 2.333333333])
 y: array([1\.        , 2.33333334]) 

numpy.testing.assert_approx_equal

原文：numpy.org/doc/1.26/reference/generated/numpy.testing.assert_approx_equal.html

testing.assert_approx_equal(actual, desired, significant=7, err_msg='', verbose=True)

如果两个值的值在有效数字位数上不相等，则引发 AssertionError。

注意

建议使用assert_allclose、assert_array_almost_equal_nulp或assert_array_max_ulp中的一个替代本函数，以进行更一致的浮点数比较。

给定两个数字，检查它们是否近似相等。近似相等定义为一致的有效数字个数。

参数：

actualscalar

要检查的对象。

desiredscalar

期望的对象。

significantint，可选

所需精度，默认为 7。

err_msgstr，可选

失败时要打印的错误消息。

verbosebool，可选

如果为 True，则冲突的值将附加到错误消息。

引发：

AssertionError

如果实际值和期望值在指定精度内不相等。

另请参见

assert_allclose

用所需相对精度和/或绝对精度比较两个类似数组的对象是否相等。

assert_array_almost_equal_nulp、assert_array_max_ulp、assert_equal

示例

>>> np.testing.assert_approx_equal(0.12345677777777e-20, 0.1234567e-20)
>>> np.testing.assert_approx_equal(0.12345670e-20, 0.12345671e-20,
...                                significant=8)
>>> np.testing.assert_approx_equal(0.12345670e-20, 0.12345672e-20,
...                                significant=8)
Traceback (most recent call last):
  ...
AssertionError:
Items are not equal to 8 significant digits:
 ACTUAL: 1.234567e-21
 DESIRED: 1.2345672e-21 

引发异常的计算条件是

>>> abs(0.12345670e-20/1e-21 - 0.12345672e-20/1e-21) >= 10**-(8-1)
True 

numpy.testing.assert_array_almost_equal

原文：numpy.org/doc/1.26/reference/generated/numpy.testing.assert_array_almost_equal.html

testing.assert_array_almost_equal(x, y, decimal=6, err_msg='', verbose=True)

如果两个对象不相等到所需的精度，则引发断言错误。

注意

建议使用assert_allclose之一，而不是使用此函数进行更一致的浮点比较assert_array_almost_equal_nulp或assert_array_max_ulp。

测试验证actual和desired的元素满足相同的形状和。

abs(desired-actual) < 1.5 * 10**(-decimal)

这是一个比最初记录的测试宽松的测试，但与实际实现的结果到四舍五入的差异一致。在形状不匹配或存在冲突值时引发异常。与 numpy 中的标准用法相反，NaN 与数字进行比较，如果两个对象在相同位置具有 NaN，则不会引发断言。

Parameters:

xarray_like

要检查的实际对象。

yarray_like

所需的，期望的对象。

decimalint, optional

所需的精度，默认为 6。

err_msgstr, optional

失败时要打印的错误消息。

verbosebool, optional

如果为 True，则冲突的值将追加到错误消息中。

Raises:

断言错误

如果实际和期望的不等直至指定精度。

另请参阅

assert_allclose

用所需的相对和/或绝对精度比较两个array_like对象的相等性。

assert_array_almost_equal_nulp, assert_array_max_ulp, assert_equal

示例

第一个 assert 不会引发异常

>>> np.testing.assert_array_almost_equal([1.0,2.333,np.nan],
...                                      [1.0,2.333,np.nan]) 

>>> np.testing.assert_array_almost_equal([1.0,2.33333,np.nan],
...                                      [1.0,2.33339,np.nan], decimal=5)
Traceback (most recent call last):
  ...
AssertionError:
Arrays are not almost equal to 5 decimals

Mismatched elements: 1 / 3 (33.3%)
Max absolute difference: 6.e-05
Max relative difference: 2.57136612e-05
 x: array([1\.     , 2.33333,     nan])
 y: array([1\.     , 2.33339,     nan]) 

>>> np.testing.assert_array_almost_equal([1.0,2.33333,np.nan],
...                                      [1.0,2.33333, 5], decimal=5)
Traceback (most recent call last):
  ...
AssertionError:
Arrays are not almost equal to 5 decimals

x and y nan location mismatch:
 x: array([1\.     , 2.33333,     nan])
 y: array([1\.     , 2.33333, 5\.     ]) 

numpy.testing.print_assert_equal

原文：numpy.org/doc/1.26/reference/generated/numpy.testing.print_assert_equal.html

testing.print_assert_equal(test_string, actual, desired)

测试两个对象是否相等，如果测试失败则打印错误消息。

测试使用 actual == desired 进行。

参数：

测试字符串str

提供给 AssertionError 的消息。

实际值对象

要根据期望值进行相等性测试的对象。

期望值对象

期望的结果。

示例

>>> np.testing.print_assert_equal('Test XYZ of func xyz', [0, 1], [0, 1])
>>> np.testing.print_assert_equal('Test XYZ of func xyz', [0, 1], [0, 2])
Traceback (most recent call last):
...
AssertionError: Test XYZ of func xyz failed
ACTUAL:
[0, 1]
DESIRED:
[0, 2] 

numpy.testing.decorate_methods

原文：numpy.org/doc/1.26/reference/generated/numpy.testing.decorate_methods.html

testing.decorate_methods(cls, decorator, testmatch=None)

将装饰器应用于类中匹配正则表达式的所有方法。

给定的装饰器应用于所有由正则表达式testmatch匹配的cls的公共方法（testmatch.search(methodname)）。以下划线开头的私有方法将被忽略。

参数：

cls类

要装饰方法的类。

decorator函数

要应用装饰器的方法

testmatch编译后的正则表达式或字符串，可选

正则表达式。默认值为 None，此时使用 nose 默认值（re.compile(r'(?:^|[\b_\.%s-])[Tt]est' % os.sep)）。如果testmatch是一个字符串，则首先将其编译为正则表达式。

numpy.testing.clear_and_catch_warnings

原文：numpy.org/doc/1.26/reference/generated/numpy.testing.clear_and_catch_warnings.html

class numpy.testing.clear_and_catch_warnings(record=False, modules=())

重置警告注册表以捕获警告的上下文管理器

警告可能很棘手，因为每当触发警告时，Python 会在calling模块中添加一个__warningregistry__成员。这使得在此模块中无法重新触发警告，无论您在警告过滤器中放置什么。此上下文管理器在其构造函数中接受modules的序列作为关键字参数，并：

• 在进入时存储和删除给定modules中的任何__warningregistry__条目；

• 在退出时将__warningregistry__重置为其先前状态。

这样可以在上下文管理器内部触发任何警告，而不会干扰外部警告的状态。

为了与 Python 3.0 兼容，请考虑所有参数只能是关键字参数。

参数：

recordbool，可选

指定是否应该由warnings.showwarning()的自定义实现捕获警告，并将其附加到上下文管理器返回的列表中。否则，上下文管理器将返回 None。附加到列表的对象是参数，其属性反映了showwarning()的参数。

modules序列，可选

重置警告注册表以便在进入时重置警告注册表的模块序列，退出时恢复警告注册表。为了正常工作，所有的“ignore”过滤器都应该按照这些模块之一进行过滤。

示例

>>> import warnings
>>> with np.testing.clear_and_catch_warnings(
...         modules=[np.core.fromnumeric]):
...     warnings.simplefilter('always')
...     warnings.filterwarnings('ignore', module='np.core.fromnumeric')
...     # do something that raises a warning but ignore those in
...     # np.core.fromnumeric 

numpy.testing.measure

原文：numpy.org/doc/1.26/reference/generated/numpy.testing.measure.html

testing.measure(code_str, times=1, label=None)

返回调用者命名空间中执行代码所经过的时间。

提供的代码字符串使用 Python 内建的 compile 进行编译。计时的精度是 10 毫秒。如果代码在这个时间尺度上执行得很快，它可以多次执行，以获得合理的计时精度。

参数：

code_str 字符串

要进行计时的代码。

times 整数，可选

代码执行的次数。默认值为 1。代码只编译一次。

label 字符串，可选

用于标识 code_str 的标签。它作为 compile 的第二个参数传入（用于运行时错误消息）。

返回：

elapsed 浮点数

执行 code_str times 次的总经过时间，单位为秒。

示例

>>> times = 10
>>> etime = np.testing.measure('for i in range(1000): np.sqrt(i**2)', times=times)
>>> print("Time for a single execution : ", etime / times, "s")  
Time for a single execution :  0.005 s 

numpy.testing.rundocs

链接：numpy.org/doc/1.26/reference/generated/numpy.testing.rundocs.html

testing.rundocs(filename=None, raise_on_error=True)

运行给定文件中的文档测试。

默认情况下，rundocs在失败时会引发一个 AssertionError。

参数：

filenamestr

要运行文档测试的文件路径。

raise_on_errorbool

是否在文档测试失败时引发 AssertionError。默认为 True。

注释

用户/开发者可以通过在test()调用中添加doctests参数来运行文档测试。例如，要运行所有测试（包括文档测试）fornumpy.lib：

>>> np.lib.test(doctests=True) 

numpy.testing.suppress_warnings

原文：numpy.org/doc/1.26/reference/generated/numpy.testing.suppress_warnings.html

class numpy.testing.suppress_warnings(forwarding_rule='always')

上下文管理器和装饰器的功能与warnings.catch_warnings类似。

然而，这也提供了一种解决bugs.python.org/issue4180的过滤机制。

这个 bug 导致 Python 3.4 之前的版本在被忽略一次后无法可靠地再次显示警告（即使在 catch_warnings 内部）。这意味着很难使用“ignore”过滤器，因为后续的测试可能需要查看警告。此外，它允许更容易地针对测试警告进行特定设置，还可嵌套使用。

参数：

forwarding_rulestr, optional

选择“always”、“once”、“module”或“location”之一。类似于常规警告模块的过滤模式，有助于减少大部分噪音的输出。未抑制和未记录的警告将根据此规则转发。默认为“always”。“location”相当于警告的“default”，根据警告来源的确切位置匹配。

注意事项

在上下文管理器内添加的过滤器在退出时将被丢弃。进入时将自动应用所有在上层定义的过滤器。

当添加记录过滤器时，匹配的警告将存储在log属性中，以及在record返回的列表中。

如果添加了过滤器并提供了module关键字，则在应用、进入上下文或退出上下文时还将清除此模块的警告注册表。如果配置为仅打印一次（默认）并且在进入上下文之前已经打印过，则可能导致警告再次显示。

嵌套此上下文管理器在“always”（默认）的转发规则下能正常工作。未经过滤和未记录的警告将被传递出去，并由外层级别匹配。在最外层级别上，它们将被打印（或被另一个警告上下文捕获）。转发规则参数可以修改这种行为。

类似于catch_warnings，此上下文管理器不支持多线程。

示例

使用上下文管理器：

with np.testing.suppress_warnings() as sup:
    sup.filter(DeprecationWarning, "Some text")
    sup.filter(module=np.ma.core)
    log = sup.record(FutureWarning, "Does this occur?")
    command_giving_warnings()
    # The FutureWarning was given once, the filtered warnings were
    # ignored. All other warnings abide outside settings (may be
    # printed/error)
    assert_(len(log) == 1)
    assert_(len(sup.log) == 1)  # also stored in log attribute 

或者作为装饰器：

sup = np.testing.suppress_warnings()
sup.filter(module=np.ma.core)  # module must match exactly
@sup
def some_function():
    # do something which causes a warning in np.ma.core
    pass 

方法

__call__(func)	函数装饰器，可将某些抑制应用于整个函数。
filter([category, message, module])	添加一个新的抑制过滤器，或者在状态进入时应用它。
record([category, message, module])	追加一个新的记录过滤器，或者在状态进入时应用它。

测试准则

原文：numpy.org/doc/1.26/reference/testing.html

介绍

直到 1.15 版本，NumPy 使用了nose测试框架，现在使用pytest框架。老的框架仍在维护，以支持使用旧 numpy 框架的下游项目，但所有 NumPy 的测试应该使用 pytest。

我们的目标是 NumPy 中的每个模块和包都应该有一套全面的单元测试。这些测试应该对给定例程的全部功能进行测试，以及对错误或意外输入参数的鲁棒性。设计良好且覆盖率良好的测试对于重构的易用性有着巨大的影响。每当发现例程中的新 bug 时，您应该为该特定情况编写一个新的测试，并将其添加到测试套件中，以防止该 bug 不经意地再次回归。

注意

SciPy 使用numpy.testing中的测试框架，因此下面显示的所有 NumPy 示例也适用于 SciPy

测试 NumPy

NumPy 可以以多种方式进行测试，选择您感到舒适的任何方式。

从 Python 内部运行测试

您可以通过numpy.test测试已安装的 NumPy，例如，要运行 NumPy 的全面测试套件，请使用以下命令：

>>> import numpy
>>> numpy.test(label='slow') 

测试方法可能需要两个或更多参数；第一个label是一个指定应该被测试的内容的字符串，第二个verbose是一个给出输出详细程度的整数。参见 docstring numpy.test获取详情。label的默认值为'fast' - 运行标准测试。字符串'full'将运行全部测试，包括那些被识别为运行缓慢的测试。如果verbose为 1 或更小，则测试将只显示有关运行的测试的信息消息；但如果大于 1，则测试还将提供有关缺少测试的警告。因此，如果要运行每个测试并获取有关哪些模块没有测试的消息：

>>> numpy.test(label='full', verbose=2)  # or numpy.test('full', 2) 

最后，如果您只对测试 NumPy 的一个子集感兴趣，例如core模块，请使用以下命令：

>>> numpy.core.test() 

从命令行运行测试

如果要构建 NumPy 以便对 NumPy 本身进行工作，请使用spin工具。要运行 NumPy 的全面测试套件：

$ spin test -m full 

测试 NumPy 的一个子集：

$ spin test -t numpy/core/tests 

有关测试的详细信息，请参阅测试构建

其他运行测试的方法

使用您喜爱的 IDE（例如vscode或pycharm）运行测试

撰写您自己的测试

如果你正在编写一个希望成为 NumPy 一部分的包，请在开发包的同时编写测试。NumPy 包目录中的每个 Python 模块、扩展模块或子包都应有一个相应的test_<name>.py文件。Pytest 会检查这些文件以寻找测试方法（命名为test*）和测试类（命名为Test*）。

假设你有一个 NumPy 模块numpy/xxx/yyy.py，其中包含一个函数zzz()。为了测试这个函数，你会创建一个名为test_yyy.py的测试模块。如果你只需要测试zzz的一个方面，你可以简单地添加一个测试函数：

def test_zzz():
    assert zzz() == 'Hello from zzz' 

更常见的是，我们需要将多个测试组合在一起，因此我们创建一个测试类：

import pytest

# import xxx symbols
from numpy.xxx.yyy import zzz
import pytest

class TestZzz:
    def test_simple(self):
        assert zzz() == 'Hello from zzz'

    def test_invalid_parameter(self):
        with pytest.raises(ValueError, match='.*some matching regex.*'):
            ... 

在这些测试方法中，使用assert和相关函数来测试某个假设是否成立。如果断言失败，测试也失败。pytest在内部重写assert语句，以在失败时提供信息性的输出，因此应优先使用它而不是旧版的numpy.testing.assert_。而在使用-O标志以优化模式运行 Python 时，普通的assert语句会被忽略，但在使用 pytest 运行测试时，这并不是一个问题。

类似地，应优先使用 pytest 函数pytest.raises和pytest.warns而不是它们的旧版对应物numpy.testing.assert_raises和numpy.testing.assert_warns，因为 pytest 的变体更广泛使用，并在与match正则表达式一起使用时允许更明确地定位警告和错误。

注意，test_函数或方法不应该有文档字符串，因为这会使得在使用verbose=2（或类似的详细设置）运行测试套件时难以识别测试。必要时使用普通的注释(#)。

同样，由于很多 NumPy 代码是没有单元测试的传统代码，仍然有几个模块尚未进行测试。请随意选择其中一个模块并为其开发测试。

在测试中使用 C 代码

NumPy 暴露了丰富的 C-API。这些是使用 c 扩展模块编写的，其“仿佛”不知道 NumPy 内部结构，而只使用官方 C-API 接口进行测试。这样的模块示例包括用户定义的rational dtype 的测试在_rational_tests中，或二进制发行版中的 ufunc 机制测试在_umath_tests中。从 1.21 版本开始，你还可以在测试中编写一些 C 代码，这些代码将在本地编译为 c 扩展模块并加载到 Python 中。

numpy.testing.extbuild.build_and_import_extension(modname, functions, *, prologue='', build_dir=None, include_dirs=[], more_init='')

从函数片段functions列表中构建和导入 c 扩展模块modname。

参数：

函数片段列表

每个片段都是一个 func_name、调用约定、片段的序列。

序言字符串

通常在其余部分之前的代码，通常是额外的#include或#define宏。

build_dirpathlib.Path

在哪里构建模块，通常是一个临时目录

include_dirs列表

编译时额外的目录查找包括文件

more_init字符串

出现在模块 PyMODINIT_FUNC 中的代码

返回：

输出：模块

模块已被加载并准备好使用

示例

>>> functions = [("test_bytes", "METH_O", """
 if ( !PyBytesCheck(args)) {
 Py_RETURN_FALSE;
 }
 Py_RETURN_TRUE;
""")]
>>> mod = build_and_import_extension("testme", functions)
>>> assert not mod.test_bytes(u'abc')
>>> assert mod.test_bytes(b'abc') 

标记测试

像上面的未加标签的测试一样，会在默认的numpy.test()运行中运行。如果您想将测试标记为慢 - 因此保留给完整的numpy.test(label='full')运行，您可以使用pytest.mark.slow进行标记：

import pytest

@pytest.mark.slow
def test_big(self):
    print('Big, slow test') 

同样对于方法：

class test_zzz:
    @pytest.mark.slow
    def test_simple(self):
        assert_(zzz() == 'Hello from zzz') 

更容易的设置和拆卸函数/方法

Testing 会按名称查找模块级或类方法级设置和拆卸功能；因此：

def setup_module():
  """Module-level setup"""
    print('doing setup')

def teardown_module():
  """Module-level teardown"""
    print('doing teardown')

class TestMe:
    def setup_method(self):
  """Class-level setup"""
        print('doing setup')

    def teardown_method():
  """Class-level teardown"""
        print('doing teardown') 

设置和拆卸功能和方法被称为“fixtures”，应该谨慎使用。pytest支持各种作用域的更一般的 fixture，可以通过特殊参数自动使用。例如，在测试中使用特殊参数名tmpdir来创建临时目录。

参数化测试

测试的一个非常好的特性是允许跨一系列参数轻松进行测试 - 这对于标准单元测试来说是一个棘手的问题。使用pytest.mark.parametrize装饰器。

Doctests

Doctests 是一种方便的方式来记录函数的行为并允许同时测试该行为。交互式 Python 会话的输出可以包含在函数的文档字符串中，测试框架可以运行示例并将实际输出与预期输出进行比较。

可以通过在test()调用中添加doctests参数来运行 Doctests；例如，要运行 numpy.lib 的所有测试（包括 Doctests）：

>>> import numpy as np
>>> np.lib.test(doctests=True) 

和这些测试一样，Doctests 会被视为在已经执行了import numpy as np的新 Python 实例中运行。属于 NumPy 子包的测试将已经导入该子包。例如，对于numpy/linalg/tests/中的测试，将创建命名空间，以便from numpy import linalg已经执行。

tests/

相比将代码和测试放在同一个目录中，我们将给定子包的所有测试放在一个tests/子目录中。例如，对于我们的示例，如果numpy/xxx/中尚不存在该目录，则需要创建一个tests/目录。因此，test_yyy.py的路径是numpy/xxx/tests/test_yyy.py。

一旦编写了numpy/xxx/tests/test_yyy.py，可以通过转到tests/目录并键入以下内容来运行测试：

python test_yyy.py 

或者，如果您将numpy/xxx/tests/添加到 Python 路径中，也可以在解释器中交互式地运行测试，就像这样：

>>> import test_yyy
>>> test_yyy.test() 

__init__.py和setup.py

通常，将tests/目录添加到 Python 路径中并不理想。相反，最好直接从模块xxx中调用测试。为此，只需将以下行放置在包的__init__.py文件的末尾：

...
def test(level=1, verbosity=1):
    from numpy.testing import Tester
    return Tester().test(level, verbosity) 

您还需要在 setup.py 的配置部分中添加测试目录：

...
def configuration(parent_package='', top_path=None):
    ...
    config.add_subpackage('tests')
    return config
... 

现在，您可以执行以下操作来测试您的模块：

>>> import numpy
>>> numpy.xxx.test() 

此外，在调用整个 NumPy 测试套件时，将找到并运行您的测试：

>>> import numpy
>>> numpy.test()
# your tests are included and run automatically! 

技巧与窍门

创建许多类似的测试

如果您有一组必须以轻微变化运行多次的测试，那么创建一个包含所有公共测试的基类，然后为每个变化创建一个子类可能会有所帮助。NumPy 中存在几个此技术的示例；以下是来自numpy/linalg/tests/test_linalg.py的摘录：

class LinalgTestCase:
    def test_single(self):
        a = array([[1., 2.], [3., 4.]], dtype=single)
        b = array([2., 1.], dtype=single)
        self.do(a, b)

    def test_double(self):
        a = array([[1., 2.], [3., 4.]], dtype=double)
        b = array([2., 1.], dtype=double)
        self.do(a, b)

    ...

class TestSolve(LinalgTestCase):
    def do(self, a, b):
        x = linalg.solve(a, b)
        assert_allclose(b, dot(a, x))
        assert imply(isinstance(b, matrix), isinstance(x, matrix))

class TestInv(LinalgTestCase):
    def do(self, a, b):
        a_inv = linalg.inv(a)
        assert_allclose(dot(a, a_inv), identity(asarray(a).shape[0]))
        assert imply(isinstance(a, matrix), isinstance(a_inv, matrix)) 

在这种情况下，我们想要测试使用几种数据类型的矩阵来解决线性代数问题，使用linalg.solve和linalg.inv。常见的测试用例（用于单精度、双精度等矩阵）收集在LinalgTestCase中。

已知失败与跳过测试

有时您可能希望跳过测试或将其标记为已知失败，例如当测试套件在编写它的代码之前，或者如果测试仅在特定架构上失败时。

要跳过一个测试，只需使用skipif：

import pytest

@pytest.mark.skipif(SkipMyTest, reason="Skipping this test because...")
def test_something(foo):
    ... 

如果SkipMyTest评估为非零，则将测试标记为跳过，并且详细测试输出中的消息是给定给skipif的第二个参数。类似地，可以使用xfail将测试标记为已知失败：

import pytest

@pytest.mark.xfail(MyTestFails, reason="This test is known to fail because...")
def test_something_else(foo):
    ... 

当然，可以使用skip或xfail无条件地跳过测试或将其标记为已知失败，而不带参数。

测试运行结束时会显示跳过和已知失败测试的总数。跳过的测试在测试结果中标记为'S'（对于verbose > 1，标记为'SKIPPED'），已知失败的测试标记为'x'（或对于verbose > 1，标记为'XFAIL'）。

随机数据的测试

随机数据的测试很好，但由于测试失败旨在暴露新的错误或回归，因此一个大部分时间都通过但偶尔在没有代码更改的情况下失败的测试是没有帮助的。通过在生成随机数据之前设置随机数种子来使随机数据具有确定性。使用 Python 的random.seed(some_number)或 NumPy 的numpy.random.seed(some_number)，取决于随机数的来源。

或者，您可以使用Hypothesis生成任意数据。Hypothesis 为您管理 Python 和 NumPy 的随机种子，并提供一种非常简洁和强大的描述数据的方式（包括hypothesis.extra.numpy，例如一组互相广播的形状）。

与随机生成相比的优势包括工具，可以在不需要固定种子的情况下重新播放和共享失败，为每次失败报告最小示例，并且触发错误的技术优于朴素的随机技术。

用于numpy.test的文档

numpy.test(label='fast', verbose=1, extra_argv=None, doctests=False, coverage=False, durations=-1, tests=None)

Pytest 测试运行器。

通常将测试函数添加到软件包的 init.py 中，如下所示：

from numpy._pytesttester import PytestTester
test = PytestTester(__name__).test
del PytestTester 

调用此测试函数会查找并运行与模块及其所有子模块相关的所有测试。

参数：

module_namemodule name

要测试的模块的名称。

备注

与先前基于nose的实现不同，该类不是公开的，因为它执行了一些numpy特定的警告抑制。

属性：

module_namestr

要测试的软件包的完整路径。

介绍

在 1.15 版本之前，NumPy 使用了 nose 测试框架，现在使用 pytest 框架。旧框架仍然得到维护，以支持使用旧 numpy 框架的下游项目，但所有 NumPy 的测试都应该使用 pytest。

我们的目标是，NumPy 中的每个模块和包都应该有一套完善的单元测试。这些测试应该在给定例程的全功能性以及对错误或意外输入参数的鲁棒性方面进行测试。设计良好且覆盖率良好的测试对于重构的便利性有着巨大影响。每当在例程中发现新错误时，您应该为该特定情况编写一个新的测试，并将其添加到测试套件中，以防止该错误不经意地潜回。

注意

SciPy 使用来自numpy.testing的测试框架，因此下面显示的所有 NumPy 示例也适用于 SciPy。

测试 NumPy

NumPy 可以以多种方式进行测试，选择您感到舒适的任何方式。

从 Python 内部运行测试

您可以通过numpy.test来测试已安装的 NumPy，例如，要运行 NumPy 的完整测试套件，请使用以下方法：

>>> import numpy
>>> numpy.test(label='slow') 

测试方法可能需要两个或多个参数；第一个label是一个指定应该进行测试的字符串，第二个verbose是一个整数，表示输出冗余级别。有关详细信息，请参见 docstring numpy.test。label的默认值为‘fast’ - 这将运行标准测试。字符串‘full’将运行完整的测试套件，包括被标识为运行缓慢的测试。如果verbose为 1 或更少，测试将只显示有关运行的测试的信息消息；但如果大于 1，则测试还将提供有关缺少测试的警告。因此，如果您想运行每个测试并获取有关哪些模块没有测试的消息：

>>> numpy.test(label='full', verbose=2)  # or numpy.test('full', 2) 

最后，如果您只对测试 NumPy 的子集感兴趣，例如core模块，请使用以下方法：

>>> numpy.core.test() 

从命令行运行测试

如果你想构建 NumPy 以便在 NumPy 本身上工作，请使用spin实用程序。要运行 NumPy 的完整测试套件：

$ spin test -m full 

测试 NumPy 的子集：

$ spin test -t numpy/core/tests 

有关测试的详细信息，请参阅测试构建

其他运行测试的方法

使用你最喜欢的 IDE，比如vscode或pycharm来运行测试

从 Python 内部运行测试

你可以通过numpy.test来测试安装的 NumPy，例如，要运行 NumPy 的完整测试套件，请使用以下命令：

>>> import numpy
>>> numpy.test(label='slow') 

测试方法可能需要两个或更多参数；第一个label是一个字符串，指定应该测试什么，第二个verbose是一个整数，表示输出详细程度。有关详细信息，请参阅numpy.test的文档字符串。label的默认值是'fast' - 这将运行标准测试。字符串'full'将运行所有测试，包括标识为运行缓慢的测试。如果verbose为 1 或更低，则测试将仅显示有关运行的测试的信息消息；但如果大于 1，则测试还将提供有关缺少测试的警告。所以如果你想运行每个测试并得到关于哪些模块没有测试的消息：

>>> numpy.test(label='full', verbose=2)  # or numpy.test('full', 2) 

最后，如果你只对测试 NumPy 的子集感兴趣，比如core模块，可以使用以下命令：

>>> numpy.core.test() 

从命令行运行测试

如果你想构建 NumPy 以便在 NumPy 本身上工作，请使用spin实用程序。要运行 NumPy 的完整测试套件：

$ spin test -m full 

测试 NumPy 的子集：

$ spin test -t numpy/core/tests 

有关测试的详细信息，请参阅测试构建

其他运行测试的方法

使用你最喜欢的 IDE，比如vscode或pycharm来运行测试

编写你自己的测试

如果你正在编写一个希望成为 NumPy 一部分的软件包，请在开发软件包时编写测试。NumPy 软件包目录中的每个 Python 模块、扩展模块或子软件包都应该有一个对应的test_<name>.py文件。Pytest 会检查这些文件中的测试方法（命名为test*）和测试类（命名为Test*）。

假设你有一个 NumPy 模块numpy/xxx/yyy.py，其中包含一个函数zzz()。要测试这个函数，你需要创建一个名为test_yyy.py的测试模块。如果你只需要测试zzz的一个方面，你可以简单地添加一个测试函数：

def test_zzz():
    assert zzz() == 'Hello from zzz' 

更多时候，我们需要将许多测试组合在一起，因此创建一个测试类：

import pytest

# import xxx symbols
from numpy.xxx.yyy import zzz
import pytest

class TestZzz:
    def test_simple(self):
        assert zzz() == 'Hello from zzz'

    def test_invalid_parameter(self):
        with pytest.raises(ValueError, match='.*some matching regex.*'):
            ... 

在这些测试方法中，使用assert和相关函数来测试某个假设是否有效。如果断言失败，则测试失败。pytest在内部重写assert语句以在失败时给出信息性的输出，因此应该优先使用它而不是遗留的变体numpy.testing.assert_。而在使用-O参数以优化模式运行 Python 时，简单的assert语句将被忽略，但在使用 pytest 运行测试时不会出现这个问题。

同样地，应该优先使用 pytest 函数pytest.raises和pytest.warns，而不是遗留的对应项numpy.testing.assert_raises和numpy.testing.assert_warns，因为 pytest 的变体更广泛地被使用，并允许与match正则表达式一起更明确地定位警告和错误。

请注意，test_函数或方法不应该有文档字符串，因为这样会使得在使用verbose=2（或类似的详细程度设置）运行测试套件的输出中很难识别测试。必要时使用纯注释（#）。

另外，由于 NumPy 的大部分代码都是没有经过单元测试的遗留代码，仍然有几个模块尚未经过测试。请随意选择其中一个模块并为其开发测试。

在测试中使用 C 代码

NumPy 公开了丰富的 C-API。这些是使用 c 扩展模块进行测试的，这些模块被编写得就像它们对 NumPy 的内部一无所知一样，而只是使用官方的 C-API 接口。这些模块的示例包括_rational_tests中对用户定义的rational数据类型的测试，以及二进制发布包中的一部分——在_umath_tests中的 ufunc 机制测试。从 1.21 版本开始，您还可以在测试中编写一小段 C 代码，该代码将被本地编译为 c 扩展模块，并加载到 python 中。

numpy.testing.extbuild.build_and_import_extension(modname, functions, *, prologue='', build_dir=None, include_dirs=[], more_init='')

从片段列表functions中构建并导入 c 扩展模块modname。

参数：

functions片段列表

每个片段都是一个 func_name,调用约定,片段的序列。

prologuestring

出现在其余部分之前的代码，通常是额外的#include或#define宏

build_dirpathlib.Path

模块的构建目录，通常是临时目录

include_dirslist

编译时查找包含文件的额外目录

more_initstring

出现在模块 PyMODINIT_FUNC 中的代码

返回：

out: 模块

模块已加载并准备就绪

示例

>>> functions = [("test_bytes", "METH_O", """
 if ( !PyBytesCheck(args)) {
 Py_RETURN_FALSE;
 }
 Py_RETURN_TRUE;
""")]
>>> mod = build_and_import_extension("testme", functions)
>>> assert not mod.test_bytes(u'abc')
>>> assert mod.test_bytes(b'abc') 

测试标签

像上面那样未标记的测试会在默认的 numpy.test() 运行中运行。如果要将测试标记为慢速 - 因此保留给完整的 numpy.test(label='full') 运行，则可以使用 pytest.mark.slow 标记它：

import pytest

@pytest.mark.slow
def test_big(self):
    print('Big, slow test') 

对于方法也是类似的：

class test_zzz:
    @pytest.mark.slow
    def test_simple(self):
        assert_(zzz() == 'Hello from zzz') 

更容易的设置和拆卸函数/方法

测试通过名称查找模块级别或类方法级别的设置和拆卸函数；因此：

def setup_module():
  """Module-level setup"""
    print('doing setup')

def teardown_module():
  """Module-level teardown"""
    print('doing teardown')

class TestMe:
    def setup_method(self):
  """Class-level setup"""
        print('doing setup')

    def teardown_method():
  """Class-level teardown"""
        print('doing teardown') 

将函数和方法的设置和拆卸函数称为“固件”，并且应该谨慎使用。pytest 支持各种作用域的更通用的固件，可以通过特殊参数自动使用。例如，特殊参数名称 tmpdir 用于在测试中创建临时目录。

参数化测试

测试的一个非常好的特性是允许轻松地在一系列参数上进行测试 - 这对于标准单元测试来说是一个讨厌的问题。使用 pytest.mark.parametrize 装饰器。

Doctests

Doctests 是一种方便的方式，用于记录函数的行为并同时允许测试该行为。交互式 Python 会话的输出可以包含在函数的文档字符串中，测试框架可以运行示例并将实际输出与预期输出进行比较。

可以通过将 doctests 参数添加到 test() 调用中来运行 doctests；例如，要运行 numpy.lib 的所有测试（包括 doctests）：

>>> import numpy as np
>>> np.lib.test(doctests=True) 

doctests 被运行，就好像它们在一个已执行 import numpy as np 的新的 Python 实例中一样。作为 NumPy 子包的一部分的测试将已经导入该子包。例如，在 numpy/linalg/tests/ 中的测试中，将创建命名空间，使得 from numpy import linalg 已经执行。

tests/

与其将代码和测试保存在同一个目录中，不如将给定子包的所有测试放在一个 tests/ 子目录中。对于我们的示例，如果尚不存在，您将需要在 numpy/xxx/ 中创建一个 tests/ 目录。因此，test_yyy.py 的路径是 numpy/xxx/tests/test_yyy.py。

一旦编写了 numpy/xxx/tests/test_yyy.py，就可以转到 tests/ 目录并键入以下内容来运行测试：

python test_yyy.py 

或者，如果将 numpy/xxx/tests/ 添加到 Python 路径中，可以像这样在解释器中交互式运行测试：

>>> import test_yyy
>>> test_yyy.test() 

__init__.py 和 setup.py

通常，将 tests/ 目录添加到 Python 路径不是一个理想的做法。相反，最好直接从模块 xxx 调用测试。为此，只需将以下行放在包的 __init__.py 文件的末尾：

...
def test(level=1, verbosity=1):
    from numpy.testing import Tester
    return Tester().test(level, verbosity) 

您还需要在 setup.py 的配置部分中添加 tests 目录：

...
def configuration(parent_package='', top_path=None):
    ...
    config.add_subpackage('tests')
    return config
... 

现在，您可以执行以下操作来测试您的模块：

>>> import numpy
>>> numpy.xxx.test() 

此外，在调用整个 NumPy 测试套件时，将找到并运行您的测试：

>>> import numpy
>>> numpy.test()
# your tests are included and run automatically! 

在测试中使用 C 代码

NumPy 提供了丰富的 C-API . 使用这些时会使用基于官方 C-API 接口编写的 c 扩展模块进行测试，这些模块“好像”对 NumPy 的内部一无所知。这样的模块示例包括 _rational_tests 中针对用户定义的 rational dtype 的测试，或者 _umath_tests 中的 ufunc 机制测试，这些都是二进制分发的一部分。从版本 1.21 开始，您还可以在测试中编写一些 C 代码片段，这些代码片段将在本地编译成 c 扩展模块并加载到 python 中。

numpy.testing.extbuild.build_and_import_extension(modname, functions, *, prologue='', build_dir=None, include_dirs=[], more_init='')

从函数片段列表 functions 中构建并导入 c 扩展模块 modname。

参数：

functions函数片段列表

每个片段是一个函数名、调用约定、代码片段的序列。

prologue字符串

前面加上的代码，通常是额外的 #include 或 #define 宏。

build_dirpathlib.Path

模块构建位置，通常为临时目录

include_dirs列表

编译时查找包含文件的额外目录

more_init字符串

出现在模块 PyMODINIT_FUNC 中的代码

返回：

输出：模块

模块已经加载并准备就绪

示例

>>> functions = [("test_bytes", "METH_O", """
 if ( !PyBytesCheck(args)) {
 Py_RETURN_FALSE;
 }
 Py_RETURN_TRUE;
""")]
>>> mod = build_and_import_extension("testme", functions)
>>> assert not mod.test_bytes(u'abc')
>>> assert mod.test_bytes(b'abc') 

标记测试

类似上述的无标签测试会在默认的 numpy.test() 运行中运行。如果要将测试标记为慢速 - 因此保留为完整的 numpy.test(label='full') 运行，可以使用 pytest.mark.slow 进行标记：

import pytest

@pytest.mark.slow
def test_big(self):
    print('Big, slow test') 

同样适用于方法：

class test_zzz:
    @pytest.mark.slow
    def test_simple(self):
        assert_(zzz() == 'Hello from zzz') 

更容易的设置和拆卸函数/方法

测试会根据名称查找模块级或类方法级的设置和拆卸函数；因此：

def setup_module():
  """Module-level setup"""
    print('doing setup')

def teardown_module():
  """Module-level teardown"""
    print('doing teardown')

class TestMe:
    def setup_method(self):
  """Class-level setup"""
        print('doing setup')

    def teardown_method():
  """Class-level teardown"""
        print('doing teardown') 

为函数和方法的设置和拆卸函数称为“ fixtures”，应该谨慎使用。pytest 支持各种范围的通用 fixture，可以通过特殊参数自动使用。例如，测试中使用的特殊参数名称 tmpdir 用于创建临时目录。

参数化测试

一个非常好的测试功能是允许在一系列参数上进行轻松测试 - 这对于标准单元测试来说是一项麻烦的问题。使用 pytest.mark.parametrize 装饰器。

文档测试

Doctest（文档测试）是一种方便的方式来记录函数的行为，并同时允许对该行为进行测试。可以将交互式 Python 会话的输出包含在函数的文档字符串中，测试框架可以运行示例并将实际输出与预期输出进行比较。

可以通过将 doctests 参数添加到 test() 调用中来运行文档测试；例如，要运行 numpy.lib 的所有测试（包括文档测试）：

>>> import numpy as np
>>> np.lib.test(doctests=True) 

文档测试会被视为在一个全新的已执行 import numpy as np 的 Python 实例中运行。作为 NumPy 子包一部分的测试将已经导入该子包。例如，在 numpy/linalg/tests/ 中的一个测试中，已经创建了这样的命名空间，以便 from numpy import linalg 已经执行。

tests/

而不是将代码和测试放在同一目录中，我们将给定子包的所有测试放入tests/子目录中。例如，对于我们的示例，如果numpy/xxx/中没有tests/目录，您需要创建一个tests/目录。因此，test_yyy.py的路径是numpy/xxx/tests/test_yyy.py。

写完numpy/xxx/tests/test_yyy.py后，可以进入tests/目录并键入以下命令来运行测试：

python test_yyy.py 

或者，如果将numpy/xxx/tests/添加到 Python 路径中，您可以在解释器中像这样运行测试：

>>> import test_yyy
>>> test_yyy.test() 

__init__.py和setup.py

通常情况下，将tests/目录添加到 Python 路径中并不理想。相反，最好直接从模块xxx中调用测试。为此，在包的__init__.py文件的末尾添加以下几行即可：

...
def test(level=1, verbosity=1):
    from numpy.testing import Tester
    return Tester().test(level, verbosity) 

您还需要在setup.py的配置部分中添加测试目录：

...
def configuration(parent_package='', top_path=None):
    ...
    config.add_subpackage('tests')
    return config
... 

现在，您可以按照以下方式测试您的模块：

>>> import numpy
>>> numpy.xxx.test() 

另外，当调用整个 NumPy 测试套件时，将找到并运行您的测试：

>>> import numpy
>>> numpy.test()
# your tests are included and run automatically! 

小贴士和技巧

创建许多类似的测试

如果您有一组必须以微小变化多次运行的测试，可以创建一个包含所有常见测试的基类，然后为每个变体创建一个子类。NumPy 中存在多种此类技术的示例；以下是其中一个示例的摘录：numpy/linalg/tests/test_linalg.py。

class LinalgTestCase:
    def test_single(self):
        a = array([[1., 2.], [3., 4.]], dtype=single)
        b = array([2., 1.], dtype=single)
        self.do(a, b)

    def test_double(self):
        a = array([[1., 2.], [3., 4.]], dtype=double)
        b = array([2., 1.], dtype=double)
        self.do(a, b)

    ...

class TestSolve(LinalgTestCase):
    def do(self, a, b):
        x = linalg.solve(a, b)
        assert_allclose(b, dot(a, x))
        assert imply(isinstance(b, matrix), isinstance(x, matrix))

class TestInv(LinalgTestCase):
    def do(self, a, b):
        a_inv = linalg.inv(a)
        assert_allclose(dot(a, a_inv), identity(asarray(a).shape[0]))
        assert imply(isinstance(a, matrix), isinstance(a_inv, matrix)) 

在这种情况下，我们希望使用几种数据类型的矩阵解决线性代数问题，使用linalg.solve和linalg.inv进行测试。常见的测试用例（例如单精度、双精度等矩阵）都收集在LinalgTestCase中。

已知的失败和跳过测试

有时，您可能希望跳过测试或将其标记为已知失败，例如在编写测试套件时在编写代码之前，或者如果测试仅在特定架构上失败。

要跳过测试，只需使用skipif：

import pytest

@pytest.mark.skipif(SkipMyTest, reason="Skipping this test because...")
def test_something(foo):
    ... 

如果SkipMyTest对非零进行评估，则测试将被标记为跳过，而详细测试输出中的消息将是skipif给出的第二个参数。类似地，可以使用xfail将测试标记为已知失败：

import pytest

@pytest.mark.xfail(MyTestFails, reason="This test is known to fail because...")
def test_something_else(foo):
    ... 

当然，可以使用skip或xfail无条件跳过测试或将其标记为已知失败，而无需参数。

在测试运行结束时，显示跳过测试和已知失败测试的总数。跳过的测试在测试结果中标记为'S'（或者对于verbose > 1，标记为'SKIPPED'），已知失败的测试标记为'x'（或者对于verbose > 1，标记为'XFAIL'）。

随机数据的测试

随机数据上的测试是很好的，但是由于测试失败的目的是暴露新的 bug 或回归，一个大多数时间通过但偶尔会因为没有代码更改而失败的测试是没有帮助的。通过在生成之前设置随机数种子使随机数据可重现。可以使用 Python 的random.seed(some_number)或 NumPy 的numpy.random.seed(some_number)，取决于随机数的来源。

或者，你可以使用Hypothesis生成任意数据。Hypothesis 为你管理 Python 和 Numpy 的随机种子，并提供一种非常简明而强大的方式来描述数据（包括hypothesis.extra.numpy，例如用于一组可互相广播的形状）。

在随机生成上的优势包括工具可以重播和共享失败而不需要固定种子，为每个失败报告最小的例子，以及为触发 bug 提供比朴素随机更好的技术。

numpy.test的文档

numpy.test(label='fast', verbose=1, extra_argv=None, doctests=False, coverage=False, durations=-1, tests=None)

Pytest 测试运行器。

测试函数通常被添加到包的 init.py 中，如下所示：

from numpy._pytesttester import PytestTester
test = PytestTester(__name__).test
del PytestTester 

调用此测试函数会找到并运行与模块及其所有子模块关联的所有测试。

参数：

module_namemodule name

要测试的模块的名称。

注释

与先前基于nose的实现不同，这个类并不是公开的，因为它执行了一些numpy特定的警告抑制。

属性：

module_namestr

要测试的包的完整路径。

创建许多类似的测试

如果你有一系列的测试需要多次运行，并且需要做一些小的变化，创建一个包含所有公共测试的基类，然后为每个变种创建一个子类是很有帮助的。NumPy 中存在这种技术的几个例子；下面摘录自numpy/linalg/tests/test_linalg.py：

class LinalgTestCase:
    def test_single(self):
        a = array([[1., 2.], [3., 4.]], dtype=single)
        b = array([2., 1.], dtype=single)
        self.do(a, b)

    def test_double(self):
        a = array([[1., 2.], [3., 4.]], dtype=double)
        b = array([2., 1.], dtype=double)
        self.do(a, b)

    ...

class TestSolve(LinalgTestCase):
    def do(self, a, b):
        x = linalg.solve(a, b)
        assert_allclose(b, dot(a, x))
        assert imply(isinstance(b, matrix), isinstance(x, matrix))

class TestInv(LinalgTestCase):
    def do(self, a, b):
        a_inv = linalg.inv(a)
        assert_allclose(dot(a, a_inv), identity(asarray(a).shape[0]))
        assert imply(isinstance(a, matrix), isinstance(a_inv, matrix)) 

在这种情况下，我们想测试使用几种数据类型的矩阵来解决线性代数问题，使用linalg.solve和linalg.inv。通常的测试案例（单精度、双精度等矩阵）都被收集在LinalgTestCase中。

已知的失败与跳过的测试

有时你可能希望跳过一个测试或将其标记为已知的失败，比如在编写测试套件之前编写的代码，或者测试只在特定体系结构上失败。

要跳过一个测试，简单地使用skipif：

import pytest

@pytest.mark.skipif(SkipMyTest, reason="Skipping this test because...")
def test_something(foo):
    ... 

如果SkipMyTest评估为非零，则测试被标记为跳过，详细测试输出中的消息是skipif给定的第二个参数。同样，可以使用xfail将测试标记为已知失败：

import pytest

@pytest.mark.xfail(MyTestFails, reason="This test is known to fail because...")
def test_something_else(foo):
    ... 

当然，也可以使用skip或xfail无需参数无条件跳过测试或将其标记为已知的失败。

测试运行结束时显示跳过和已知失败测试的总数。跳过的测试在测试结果中标记为'S'（或verbose > 1时标记为'SKIPPED'），已知失败的测试标记为'x'（或verbose > 1时标记为'XFAIL'）。

随机数据测试

随机数据测试虽然很好，但由于测试失败意味着暴露新的错误或回归，因此大部分时间通过但偶尔失败而没有代码更改的测试并不有用。通过在生成之前设置随机数种子来使随机数据具有确定性。根据随机数的来源使用 Python 的random.seed(some_number)或 NumPy 的numpy.random.seed(some_number)。

或者，您可以使用Hypothesis生成任意数据。Hypothesis 为您管理 Python 和 Numpy 的随机种子，并提供了一种非常简洁而强大的描述数据的方法（包括hypothesis.extra.numpy，例如一组相互广播的形状）。

与随机生成相比的优点包括工具可以重放和分享失败而不需要固定的种子，为每个失败报告提供最小示例，并且触发错误的技术比朴素随机更好。

numpy.test的文档

numpy.test(label='fast', verbose=1, extra_argv=None, doctests=False, coverage=False, durations=-1, tests=None)

Pytest 测试运行器。

测试函数通常像这样添加到包的 init.py 中：

from numpy._pytesttester import PytestTester
test = PytestTester(__name__).test
del PytestTester 

调用此测试函数会查找并运行与模块及其所有子模块相关联的所有测试。

参数：

module_name模块名

要测试的模块的名称。

笔记

与之前基于nose的实现不同，这个类不会公开暴露，因为它执行了一些特定于numpy的警告抑制。

属性：

module_namestr

要测试的包的完整路径。