---

NumPy 最大值函数辨析：numpy.max() vs numpy.amax() 深度解析

在数据科学、机器学习和科学计算领域，NumPy (Numerical Python) 是一个不可或缺的基础库。它提供了强大的 N 维数组对象（ndarray）以及用于处理这些数组的各种高效函数。在众多函数中，查找数组中的最大值是一项非常常见的操作。NumPy 为此提供了 numpy.max() 和 numpy.amax() 两个函数。初学者甚至一些有经验的用户可能会对这两个功能相似的函数感到困惑：它们之间有何区别？应该使用哪一个？性能有差异吗？本文将深入探讨这两个函数，剖析它们的异同、用法、参数、性能以及历史渊源，帮助您彻底理解并做出最佳选择。

一、核心功能与基本用法：殊途同归

让我们从最核心的问题开始：numpy.max() 和 numpy.amax() 在功能上有什么区别？

答案是：在当前版本的 NumPy 中，numpy.max() 和 numpy.amax() 在功能上是完全等价的，它们是彼此的别名（alias）。 这意味着无论您调用哪一个函数，底层执行的都是相同的代码，得到的结果也完全一致。

它们的核心功能是：

1. 找出数组中的最大值： 如果不指定任何轴（axis），函数将返回整个数组中的最大元素。
2. 沿指定轴找出最大值： 可以通过 axis 参数指定一个或多个轴，函数将沿着这些轴计算最大值，返回一个形状经过压缩的新数组（除非设置 keepdims=True）。

基本用法示例：

“`python
import numpy as np

创建一个一维数组

arr1d = np.array([1, 5, 2, 9, 3, 7])

使用 numpy.max() 查找全局最大值

max_val_1 = np.max(arr1d)
print(f”使用 np.max() 找到的最大值: {max_val_1}”) # 输出: 使用 np.max() 找到的最大值: 9

使用 numpy.amax() 查找全局最大值

max_val_2 = np.amax(arr1d)
print(f”使用 np.amax() 找到的最大值: {max_val_2}”) # 输出: 使用 np.amax() 找到的最大值: 9

创建一个二维数组

arr2d = np.array([[1, 6, 3],
[8, 2, 7],
[4, 9, 5]])

使用 numpy.max() 查找全局最大值

global_max_1 = np.max(arr2d)
print(f”\n二维数组全局最大值 (np.max): {global_max_1}”) # 输出: 二维数组全局最大值 (np.max): 9

使用 numpy.amax() 查找全局最大值

global_max_2 = np.amax(arr2d)
print(f”二维数组全局最大值 (np.amax): {global_max_2}”) # 输出: 二维数组全局最大值 (np.amax): 9

使用 numpy.max() 沿轴 0 (列) 查找最大值

max_axis0_1 = np.max(arr2d, axis=0)
print(f”沿轴 0 的最大值 (np.max): {max_axis0_1}”) # 输出: 沿轴 0 的最大值 (np.max): [8 9 7]

使用 numpy.amax() 沿轴 0 (列) 查找最大值

max_axis0_2 = np.amax(arr2d, axis=0)
print(f”沿轴 0 的最大值 (np.amax): {max_axis0_2}”) # 输出: 沿轴 0 的最大值 (np.amax): [8 9 7]

使用 numpy.max() 沿轴 1 (行) 查找最大值

max_axis1_1 = np.max(arr2d, axis=1)
print(f”沿轴 1 的最大值 (np.max): {max_axis1_1}”) # 输出: 沿轴 1 的最大值 (np.max): [6 8 9]

使用 numpy.amax() 沿轴 1 (行) 查找最大值

max_axis1_2 = np.amax(arr2d, axis=1)
print(f”沿轴 1 的最大值 (np.amax): {max_axis1_2}”) # 输出: 沿轴 1 的最大值 (np.amax): [6 8 9]
“`

从以上示例可以看出，对于相同的输入和参数，np.max() 和 np.amax() 的输出是完全一致的。

二、参数详解：共享的控制选项

numpy.max() 和 numpy.amax() 接受相同的参数集，这些参数提供了对最大值计算过程的精细控制。理解这些参数对于高效使用这两个函数至关重要。

• a (array_like): 输入数据，可以是 NumPy 数组，也可以是任何可以被转换为 NumPy 数组的对象（如列表、元组）。这是必须提供的参数。

• axis (None or int or tuple of ints, optional): 指定计算最大值的轴。

  • None (默认值): 计算整个数组的全局最大值，返回一个标量。
  • int: 指定单个轴。例如，对于二维数组，axis=0 表示沿列计算最大值，axis=1 表示沿行计算最大值。结果数组的维度会减少 1（除非 keepdims=True）。
  • tuple of ints: 指定多个轴。函数将沿着这些指定的轴计算最大值。结果数组的维度会相应减少。

  “`python
  arr = np.arange(12).reshape((3, 4))
  print(“原始数组:\n”, arr)

  [[ 0 1 2 3]

  [ 4 5 6 7]

  [ 8 9 10 11]]

  沿轴 0 计算最大值

  max_axis0 = np.max(arr, axis=0)
  print(“\n沿轴 0 最大值 (np.max):”, max_axis0) # [ 8 9 10 11]
  print(“结果形状:”, max_axis0.shape) # (4,)

  沿轴 1 计算最大值

  max_axis1 = np.amax(arr, axis=1) # 使用 amax 效果相同
  print(“\n沿轴 1 最大值 (np.amax):”, max_axis1) # [ 3 7 11]
  print(“结果形状:”, max_axis1.shape) # (3,)

  多维数组示例

  arr3d = np.arange(24).reshape((2, 3, 4))
  print(“\n3D 数组:\n”, arr3d)

  [[[ 0 1 2 3]

  [ 4 5 6 7]

  [ 8 9 10 11]]

  [[12 13 14 15]

  [16 17 18 19]

  [20 21 22 23]]]

  沿轴 (0, 1) 计算最大值

  max_axis01 = np.max(arr3d, axis=(0, 1))
  print(“\n沿轴 (0, 1) 最大值 (np.max):”, max_axis01) # [20 21 22 23]
  print(“结果形状:”, max_axis01.shape) # (4,)
  “`

• out (ndarray, optional): 指定用于存放结果的输出数组。

  • 如果提供此参数，结果将被写入 out 数组，而不是创建一个新的数组。
  • out 数组必须具有与预期输出兼容的形状和类型（dtype）。
  • 使用 out 参数可以避免不必要的内存分配，对于在循环中反复计算或处理大型数组时，可以提高性能和内存效率。

  “`python
  arr = np.array([1, 5, 2, 9])
  output_array = np.empty((), dtype=arr.dtype) # 创建一个标量形状的空数组

  np.max(arr, out=output_array)
  print(“\n使用 out 参数的结果:”, output_array) # 9 (注意这里直接打印 output_array)

  arr2d = np.array([[1, 6], [8, 2]])
  output_axis0 = np.empty(2, dtype=arr2d.dtype) # 创建形状为 (2,) 的空数组
  np.amax(arr2d, axis=0, out=output_axis0) # 使用 amax 效果相同
  print(“使用 out 参数 (axis=0):”, output_axis0) # [8 6]
  “`

• keepdims (bool, optional): 控制输出数组的维度。

  • False (默认值): 计算最大值时，被操作的轴将从结果的形状中移除。
  • True: 被操作的轴将保留在结果中，但其大小变为 1。这使得输出数组能够与原始数组进行广播（broadcasting）运算。

  “`python
  arr = np.array([[1, 6, 3], [8, 2, 7]])
  print(“\n原始数组:\n”, arr)
  print(“形状:”, arr.shape) # (2, 3)

  keepdims=False (默认)

  max_axis1_no_keepdims = np.max(arr, axis=1)
  print(“\n沿轴 1 最大值 (keepdims=False):”, max_axis1_no_keepdims) # [6 8]
  print(“形状 (keepdims=False):”, max_axis1_no_keepdims.shape) # (2,)

  keepdims=True

  max_axis1_keepdims = np.amax(arr, axis=1, keepdims=True) # 使用 amax 效果相同
  print(“\n沿轴 1 最大值 (keepdims=True):\n”, max_axis1_keepdims) # [[6] [8]]
  print(“形状 (keepdims=True):”, max_axis1_keepdims.shape) # (2, 1)

  演示广播：找出每行与该行最大值的差

  diff = arr – max_axis1_keepdims
  print(“\n原始数组与行最大值的差 (利用 keepdims):\n”, diff)

  [[-5 0 -3]

  [ 0 -6 -1]]

  ``
使用keepdims=True` 对于需要保持维度以便进行后续广播操作的场景非常有用，例如在标准化或比较操作中。

• initial (scalar, optional): 指定用于计算最大值的初始值。

  • 在计算开始前，内部的比较器会初始化为 initial。
  • 这对于处理空数组或空切片非常有用。如果没有提供 initial，对空数组调用 max 会引发 ValueError。
  • initial 的值应该小于或等于数组中可能出现的任何值，以确保它不会错误地成为最终的最大值（除非数组确实为空）。通常可以设置为理论上的最小值，如 np.iinfo(arr.dtype).min (对于整数) 或 -np.inf (对于浮点数)。

  “`python
  empty_arr = np.array([])

  对空数组调用 max (无 initial) 会报错

  try:
  np.max(empty_arr)
  except ValueError as e:
  print(f”\n对空数组调用 np.max (无 initial) 引发错误: {e}”)

  使用 initial 处理空数组

  max_empty_initial = np.max(empty_arr, initial=-np.inf)
  print(f”对空数组调用 np.max (initial=-np.inf): {max_empty_initial}”) # 输出: -inf

  arr = np.array([1, 5, 2])

  initial 值小于数组中所有元素，不影响结果

  max_with_initial_low = np.amax(arr, initial=-1) # 使用 amax 效果相同
  print(f”使用较低 initial ({max_with_initial_low})”) # 输出: 5

  initial 值大于数组中某些元素，会影响结果（通常不希望这样）

  max_with_initial_high = np.amax(arr, initial=10)
  print(f”使用较高 initial ({max_with_initial_high})”) # 输出: 10
  “`

• where (array_like of bool, optional): 指定一个布尔掩码，用于选择参与计算最大值的元素。

  • 只有在 where 数组对应位置为 True 的元素才会被考虑。
  • 对于 where 为 False 的位置，其元素将被忽略。
  • 需要与 initial 参数配合使用。因为如果某个轴上的所有元素都被 where 掩码排除了，那么该轴的结果将是 initial 的值。如果不提供 initial，在这种情况下会引发 ValueError。

  “`python
  arr = np.array([1, 8, 3, 9, 4, 7])
  mask = np.array([True, False, True, True, False, True])

  只考虑 mask 为 True 的元素

  max_where = np.max(arr, where=mask, initial=-1) # 必须提供 initial
  print(f”\n使用 where 掩码计算最大值: {max_where}”) # 输出: 9 (忽略了 8 和 4)

  arr2d = np.array([[10, 2, 15], [5, 12, 8]])
  mask2d = np.array([[True, False, True], [False, True, False]])

  沿轴 1 计算，考虑掩码

  max_where_axis1 = np.amax(arr2d, axis=1, where=mask2d, initial=-np.inf) # 使用 amax 效果相同
  print(f”使用 where 掩码沿轴 1 计算最大值: {max_where_axis1}”) # 输出: [15. 12.]
  # 第一行忽略 2, 最大是 15
  # 第二行忽略 5 和 8, 最大是 12

  如果某轴全被 mask，结果为 initial

  mask_all_false_axis1 = np.array([[False, False, False], [False, True, False]])
  max_all_masked = np.max(arr2d, axis=1, where=mask_all_false_axis1, initial=-1)
  print(f”第一行全被 mask 时的结果: {max_all_masked}”) # 输出: [-1 12]
  “`

由于 numpy.max() 和 numpy.amax() 是别名，它们共享完全相同的参数集和行为。理解这些参数是灵活运用 NumPy 进行数据分析的关键。

三、方法 vs 函数：ndarray.max()

除了 numpy.max() 和 numpy.amax() 这两个 函数 外，NumPy 数组对象（ndarray）自身也提供了一个名为 max() 的 方法。即，对于一个数组 arr，你可以调用 arr.max()。

arr.max() 与 np.max(arr) / np.amax(arr) 的关系：

• 功能相似性： arr.max() 在核心功能上与 np.max(arr) / np.amax(arr) 非常相似，都可以计算全局或沿指定轴的最大值。
• 参数兼容性： arr.max() 方法也接受 axis, out, keepdims, initial, where 这些参数，并且它们的行为与函数版本中的参数相同。
• 细微差异：
  • 调用方式： np.max() 是 NumPy 库级别的函数，需要将数组作为第一个参数传入；arr.max() 是数组对象的方法，通过对象实例调用。
  • 适用对象： np.max() 可以接受任何 array-like 对象（如列表）作为输入，它会先尝试将其转换为 NumPy 数组再进行计算。而 arr.max() 只能由 NumPy 数组对象调用。

示例比较：

“`python
arr = np.array([[1, 6], [8, 2]])

函数调用

max_func_1 = np.max(arr, axis=0)
max_func_2 = np.amax(arr, axis=0)

方法调用

max_method = arr.max(axis=0)

print(“\n函数 np.max() 结果:”, max_func_1) # [8 6]
print(“函数 np.amax() 结果:”, max_func_2) # [8 6]
print(“方法 arr.max() 结果:”, max_method) # [8 6]

对列表使用 np.max (可以)

my_list = [1, 5, 2, 9]
max_list_func = np.max(my_list)
print(“\nnp.max 对列表:”, max_list_func) # 9

对列表使用 .max() 方法 (会报错)

try:
max_list_method = my_list.max()
except AttributeError as e:
print(f”列表没有 .max() 方法: {e}”)
“`

在实际使用中，np.max(arr) 和 arr.max() 的选择更多是基于个人偏好和代码风格。np.max() 的写法可能更统一（与 np.sum, np.mean 等函数风格一致），而 arr.max() 的写法有时被认为更符合面向对象的风格。两者在功能和性能上基本没有显著差异（对于已经是 ndarray 的输入）。

四、性能考量：完全一致

既然 numpy.max() 和 numpy.amax() 是别名，并且指向 NumPy 底层相同的、高度优化的 C 语言实现，那么它们之间 不存在任何性能差异。选择哪一个函数对代码的执行速度没有任何影响。

NumPy 的聚合函数（如 max, min, sum 等）通常都经过精心优化，利用了 SIMD 指令集（如 SSE, AVX）等技术，对于大规模数组的操作非常高效。性能瓶颈通常不会出现在选择 max 还是 amax 上，而可能与数据大小、内存带宽、CPU 缓存等因素有关。

五、历史渊源与命名习惯：为何有两个名字？

amax 的存在主要是历史原因和早期命名习惯的遗留。在 NumPy 的早期发展阶段，可能存在不同的命名想法或从其他库（如 Numeric、Numarray，NumPy 的前身）继承而来的命名。a 前缀有时被用来表示“数组”（array）相关的操作，例如还有 amin (对应 min)。

随着 NumPy 的成熟和标准化，max 成为了更通用、更符合 Python 风格（与内建 max() 函数一致）的名称。为了保持向后兼容性，旧的名称 amax 被保留下来，并将其设为 max 的别名。

最佳实践与选择建议：

1. 一致性优先： 在您的代码库或项目中，选择一个名称（np.max 或 np.amax）并坚持使用。这有助于提高代码的可读性和一致性。
2. 推荐使用 np.max： 由于 max 与 Python 内建函数以及 NumPy 其他聚合函数（min, sum, mean）的命名更一致，np.max 通常是更受推荐的选择。大多数现代 NumPy 教程和文档也倾向于使用 np.max。
3. 理解别名： 重要的是要理解它们是等价的，看到 np.amax 时不必感到困惑，知道它等同于 np.max 即可。
4. 区分函数与方法： 清楚 np.max(arr) (函数) 和 arr.max() (方法) 的区别，并根据场景和风格选择。

六、处理特殊情况：NaN 值

值得注意的是，标准的 np.max 和 np.amax 在处理包含 NaN (Not a Number) 值的数组时，遵循“NaN 传播”原则：如果参与比较的元素中存在 NaN，则结果通常也是 NaN（除非所有非 NaN 元素都被 where 掩码排除了，且设置了 initial）。

“`python
arr_with_nan = np.array([1.0, np.nan, 5.0, 2.0])

max_nan = np.max(arr_with_nan)
print(f”\n包含 NaN 的数组使用 np.max: {max_nan}”) # 输出: nan

如果需要忽略 NaN 并找出其他元素的最大值，应使用 np.nanmax

max_ignore_nan = np.nanmax(arr_with_nan)
print(f”使用 np.nanmax 忽略 NaN: {max_ignore_nan}”) # 输出: 5.0
“`

因此，如果您的数据可能包含 NaN，并且您希望找到非 NaN 元素中的最大值，应该使用专门为此设计的 np.nanmax() 函数，而不是 np.max 或 np.amax。

七、总结与结论

numpy.max() 与 numpy.amax() 是 NumPy 库中用于查找数组最大值的两个函数。通过本文的详细分析，我们可以得出以下关键结论：

1. 功能等价： numpy.max() 和 numpy.amax() 是彼此的别名，功能完全相同，底层调用相同的实现。
2. 参数一致： 它们接受完全相同的参数（a, axis, out, keepdims, initial, where），并且参数的行为也一致。
3. 性能相同： 由于是别名，两者之间没有任何性能差异。
4. 方法存在： NumPy 数组对象还有一个 arr.max() 方法，功能与函数版本类似，主要区别在于调用方式和对输入类型的要求。
5. 历史遗留： amax 的存在主要是历史原因，max 是当前更推荐、更通用的名称。
6. 选择建议： 推荐使用 np.max 以保持命名一致性，但理解 np.amax 是其别名即可。在项目中保持统一风格最为重要。
7. NaN 处理： 对于可能包含 NaN 的数据，若需忽略 NaN 查找最大值，应使用 np.nanmax()。

总而言之，在 numpy.max() 和 numpy.amax() 之间无需纠结。它们是同一个工具的两个名字。选择您认为更清晰、更符合您项目风格的那一个（通常推荐 np.max），并专注于理解和运用它们强大的参数集来高效地完成您的数据分析任务。掌握这些基础函数是精通 NumPy 的重要一步。

---