Numpy: ENH：替代 `random.shuffle`，带有 `axis` 参数。

不明白为什么这需要成为替代方案——为什么不添加一个
shuffle 的轴参数？ 默认为 None，如 np.sum。

2014 年 10 月 11 日星期六晚上 9:36，Warren Weckesser通知@github.com
写道：

有一个替代 numpy.random.shuffle 的替代方案会很好
接受一个轴参数，并独立地洗牌
一维切片。 这是一个我称之为 disarrange 的实现。
它有效，但如果有一个更有效的 C 实现会很好。

def disarrange(a,axis=-1)：
"""
沿给定轴原地随机播放a 。

Apply numpy.random.shuffle to the given axis of `a`.
Each one-dimensional slice is shuffled independently.
"""
b = a.swapaxes(axis, -1)
# Shuffle `b` in-place along the last axis.  `b` is a view of `a`,
# so `a` is shuffled in place, too.
shp = b.shape[:-1]
for ndx in np.ndindex(shp):
    np.random.shuffle(b[ndx])
return

例子：

在 [156] 中：a = np.arange(20).reshape(4,5)

在 [157] 中：一个
出[157]：
数组([[ 0, 1, 2, 3, 4],
[ 5, 6, 7, 8, 9],
[10, 11, 12, 13, 14],
[15, 16, 17, 18, 19]])

在 [158] 中：disarrange(a,axis=-1)

在 [159] 中：一个
出[159]：
数组([[ 2, 0, 4, 3, 1],
[ 8, 6, 7, 9, 5],
[11, 14, 13, 10, 12],
[19, 18, 16, 17, 15]])

在 [160] 中：a = np.arange(20).reshape(4,5)

在[161]中：disarrange(a,axis=0)

在 [162] 中：一个
出[162]：
数组([[ 5, 11, 7, 13, 14],
[ 0, 6, 2, 3, 4],
[10, 1, 17, 18, 19],
[15, 16, 12, 8, 9]])

这个请求是由 stackoverflow 上的这个问题引起的：
http://stackoverflow.com/questions/26310346/quickly-calculate-randomized-3d-numpy-array-from-2d-numpy-array/

—
直接回复此邮件或在 GitHub 上查看
https://github.com/numpy/numpy/issues/5173。

纳撒尼尔·J·史密斯
博士后研究员 - 信息学 - 爱丁堡大学
http://vorpus.org

shuffle的当前行为并不像axis=None 。 它将其参数视为一维序列。

In [181]: a = np.arange(20).reshape(4,5)

In [182]: np.random.shuffle(a)

In [183]: a
Out[183]: 
array([[ 0,  1,  2,  3,  4],
       [15, 16, 17, 18, 19],
       [ 5,  6,  7,  8,  9],
       [10, 11, 12, 13, 14]])

您可以将其解释为axis=0 ，但缺少的功能是一维切片的独立改组。

对于二维数组，您可以混洗a.T以模拟axis=1 ，但这不会让您独立混洗：

In [184]: a = np.arange(20).reshape(4,5)

In [185]: np.random.shuffle(a.T)

In [186]: a
Out[186]: 
array([[ 4,  1,  0,  3,  2],
       [ 9,  6,  5,  8,  7],
       [14, 11, 10, 13, 12],
       [19, 16, 15, 18, 17]])

在disarrange ，我希望axis=None得像np.random.shuffle(a.flat) 。

如果通过向shuffle添加适当的参数来控制它的行为来实现替代改组，那会很好，但我没有关于该 API 的建议。

也许可以将两个参数添加到shuffle ： axis和independent （或类似的东西）。 新签名将是：

def shuffle(a, independent=False, axis=0)

当independent为 False 时，它​​的作用类似于当前的shuffle 。 当为 True 时，它​​的作用类似于disarrange 。

哦，呃，我只是假设它与类比更一致
功能类似于 sort :-(。如果这种方式会更好
shuffling-of-slices 写成 idx = arange(...); 洗牌（idx）；
multi_dim_array[idx, ...]; 但没有人问我:-)

我对具有匹配调用约定的 shuffle 版本 +1
np.sort，但作为一项规则，我们应该检查列表。 他们可能有
关于关键问题的建议，比如最好的名字:-)

（也许“争夺”？）

2014 年 10 月 11 日星期六晚上 10:31，Warren Weckesser < [email protected]

写道：

shuffle 的当前行为并不像轴 = 无。 它对待
它的参数是一个一维序列。

在 [181] 中：a = np.arange(20).reshape(4,5)

在 [182] 中：np.random.shuffle(a)

在 [183]​​ 中：一个
出[183]​​：
数组([[ 0, 1, 2, 3, 4],
[15, 16, 17, 18, 19],
[ 5, 6, 7, 8, 9],
[10, 11, 12, 13, 14]])

您可以将其解释为轴 = 0，但缺少的功能是
一维切片的独立改组。

对于二维数组，您可以随机播放 aT 以模拟轴 = 1，但这不会
让你独立洗牌：

在 [184] 中：a = np.arange(20).reshape(4,5)

在 [185]: np.random.shuffle(aT)

在 [186] 中：一个
出[186]：
数组([[ 4, 1, 0, 3, 2],
[ 9, 6, 5, 8, 7],
[14, 11, 10, 13, 12],
[19, 16, 15, 18, 17]])

在混乱中，我希望 axis=None 表现得像
np.random.shuffle(a.flat)。

如果通过添加实现替代洗牌就可以了
适当的参数来控制它的行为，但我不
对该 API 提出建议。

—
直接回复此邮件或在 GitHub 上查看
https://github.com/numpy/numpy/issues/5173#issuecomment -58765220。

纳撒尼尔·J·史密斯
博士后研究员 - 信息学 - 爱丁堡大学
http://vorpus.org

啊，将所需的行为描述为sort的模拟是一个好主意。

哦，呃，我只是假设它与 sort 等类似函数更一致

我也很惊讶，根据对 stackoverflow 问题的评论，至少还有另外两个有经验的 numpy 用户感到惊讶。 我将在邮件列表上开始讨论。

我想如果普通用户目前弄错了，那么它是值得的
提到另一个选项——我们_可以_添加一个参数来选择
这两种行为，开始默认为当前行为，
并且在经过多次 FutureWarning 和大喊大叫之后在某个时候切换默认值
来警告人们。 但这是一个丑陋的过渡...

在周六，二零一四年十月十一日晚上11:00，沃伦Weckesser < [email protected]

写道：

哦，呃，我只是假设它与类比更一致
排序等功能

我也很惊讶，基于 stackoverflow 上的评论
问题，至少有另外两个经验丰富的 numpy 用户感到惊讶。 患病的
在邮件列表上开始讨论。

—
直接回复此邮件或在 GitHub 上查看
https://github.com/numpy/numpy/issues/5173#issuecomment -58766099。

纳撒尼尔·J·史密斯
博士后研究员 - 信息学 - 爱丁堡大学
http://vorpus.org

他们也可能对诸如最佳名称之类的关键问题提出建议。

我们需要一个名为 Sue 的函数。

只是想 +1 这个功能，因为我也期望它存在，类似于 sort(axis=N)。 是否对邮件列表做出了任何决定？

邮件列表线程在这里：
http://thread.gmane.org/gmane.comp.python.numeric.general/59014

这将非常有用！

我也很感激！

根据https://stackoverflow.com/a/35647011/3401634 ，对于多维数组X

np.random.shuffle(X)

是相同的

np.take(X, np.random.permutation(X.shape[0]), axis=0, out=X)

那么为什么不实施

np.random.shuffle(X, axis=axis)

作为

np.take(X, np.random.permutation(X.shape[axis]), axis=axis, out=X)

使用默认的axis=0 ？

有这方面的消息吗？ 我很惊讶这个功能不存在。 现在我使用np.apply_along_axis和np.random.permutation作为解决方法。

由于#13829，现在可以关闭吗？

（请注意，在处理此处的示例时，我在新的 shuffle 代码中发现了一个错误。在接下来的内容中，我使用了 https://github.com/numpy/numpy/pull/14662 中提出的修复程序，该修复程序已合并。）

@wkschwartz ，#13829 中的更改很有用，但这不是此处要求的增强功能。 #13829 中添加的轴仍然将数组视为要打乱的一维序列。 新的轴参数允许用户指定哪个轴被视为一维轴，但它不会在轴内进行独立的随机播放。

例如，

In [1]: import numpy as np                                                      

In [2]: rng = np.random.default_rng()                                           

In [3]: x = np.arange(20).reshape(2, 10)                                        

In [4]: x                                                                       
Out[4]: 
array([[ 0,  1,  2,  3,  4,  5,  6,  7,  8,  9],
       [10, 11, 12, 13, 14, 15, 16, 17, 18, 19]])

In [5]: rng.shuffle(x, axis=1)                                                  

In [6]: x                                                                       
Out[6]: 
array([[ 5,  9,  6,  4,  7,  0,  3,  2,  1,  8],
       [15, 19, 16, 14, 17, 10, 13, 12, 11, 18]])

您可以看到行没有被独立洗牌。 列已重新排列，但每列中的值相同。

这个问题中要求的行为是独立洗牌，如我上面给出的disarrange代码：

In [10]: x = np.arange(20).reshape(2, 10)                                       

In [11]: x                                                                      
Out[11]: 
array([[ 0,  1,  2,  3,  4,  5,  6,  7,  8,  9],
       [10, 11, 12, 13, 14, 15, 16, 17, 18, 19]])

In [12]: disarrange(x, axis=1)                                                  

In [13]: x                                                                      
Out[13]: 
array([[ 4,  3,  7,  8,  0,  6,  5,  2,  9,  1],
       [12, 15, 19, 17, 18, 14, 10, 13, 11, 16]])

我想再次浮出水面，也许也是为了周三的会议。 我们刚刚为choice和permutation添加了更高维度的功能，并且在 1.18 中甚至是轴参数（因此它是全新的）。

所有这些都使用当前的shuffle逻辑shuffle the subarrays along this axis ，而不是shuffle along (individual) axis ，我认为这可以说是应该发生的事情。 即它在给定的轴上“过”而不是“沿着”或在给定的轴内洗牌。

但是，几乎在所有情况下， axis在 NumPy 中都表示沿轴，希望很少有例外，例如apply_over_axes名称中带有“结束”。 所以我会如此大胆地声称，即使将参数重命名为over_axis=0也能更好地避免混淆！ 特别是对于随机数，可能很难注意到不正确的洗牌。

正如上面的 github 交叉引用中所指出的，我在https://github.com/numpy/numpy/pull/15121 上有一个正在进行的 PR

@WarrenWeckesser很酷，我个人更迫切关心的是我们在新 API 中以及最近在此方面扩展了过度含义。
我想知道我们是否不应该部分撤回它，例如至少重命名axis参数。 甚至暂时再次完全摆脱多维行为......

我现在可能只是反应过度，因为我有点恼火我错过了这个或者之前没有想到它......但我真的认为当前的逻辑非常危险。 这是很容易错过，它不提供沿着这意味着预期。 而这不是np.sort使用的意思。

@seberg ，感谢您提出这个问题。 我认为我们仍然需要就 API 达成共识。 我将尝试在这里简要总结过去的想法。 我将遵循您对axis两种解释使用“over”和“along”的约定。 我不知道在这一点上我们是否可以完全撤销对shuffle和permutation的axis现有的“沿”解释，但我认为很多人如果事实证明我们可以，我们会很高兴。 :)

在几年前的邮件列表讨论结束时，我最终认为解决方案是不更改shuffle和permutation的 API，而是引入两个沿轴随机化的新方法而不是超过它。 一种方法可以就地工作，另一种方法会返回一个副本。 我当时更喜欢permute和permuted这两个名字，但有人反对这些名字。 在去年 12 月的 PR 中，我称它们randomly_permute和randomly_permuted ，但这些名称应该被视为占位符。 在尝试决定这些名称之前，我们必须确定添加两个新函数是否是正确的方法。 从这里开始，为简洁起见，我将建议的新方法称为permute和permuted 。

使用新函数，我们将拥有以下相关的Generator方法：

meaning    operate     return
of axis    in-place     copy
-------    --------  -----------
"over"     shuffle   permutation
"along"    permute   permuted

（在轴上“操作”的方法shuffle和permutation已经存在。）

有人建议我们只有一个，而不是两个新方法，它带有一个参数来控制就地与复制行为。 为此提出了两条建议：

(a) 添加out参数。 要就地工作，请将输入数组作为out传递。 如果未提供out ，则返回洗牌副本。
(b) 添加布尔标志，例如copy或inplace ，用于指定所需的行为。

创建新方法的主要替代方法是向现有方法添加一个新参数，以更改axis的解释方式。 在列出这些之前，我将重申 Robert Kern 在邮件列表线程中关于如何在实践中使用额外参数的评论（这里指的是如下所示的independent参数）：

在我看来，有两种方法而不是
一。 我无法想象什么时候我不会使用字面的 True 或 False
为此，所以它真的应该是两种不同的方法。

（社论题外话：在这样的讨论中不可避免地会出现增加命名空间（在本例中为Generator命名空间）的问题（有时称为“命名空间污染”）。让我们同意，是的，所有在相同的情况下，较小的命名空间更好。但是，与大多数 API 设计决策一样，需要考虑权衡。如果我们保持命名空间较小，但创建具有笨拙或过于复杂的 API 的方法，我们不会获胜。）

说了这么多，这里有两个建议添加到shuffle的现有签名中。

(1) shuffle(x, axis=0, independent=False) ：布尔标志independent决定了axis的解释方式：False -> "over", True -> "along"。 （可能有比independent更好的名字。）
(2) shuffle(x, axis=0, iaxis=???) ：第二个参数iaxis给出了“沿着”行为的轴。 （这如何与axis交互需要一个明确的规范。大概给iaxis一个值会导致axis被忽略。）

我想我已经涵盖了所有出现的各种 API 想法。 如果有人知道其他人，请告诉我们。

我很高兴在这里增加 API。 我不确定有很多理由反对它：

• 我们可能会同意这是一个有用的
• 没有好的方法可以用现有的功能来实现它
• 使用kwarg进行总行为切换似乎不是正常模式，我认为 Rober Kern 完全正确。

我想这里发生的事情是shuffle和permutation （也许choice ）可以与索引操作（即take ）进行比较，其中对axis使用相同的含义。 我觉得有点奇怪的原因可能是这个定义的缺点是它永远不能推广到 ND 不像典型的数组感知函数（如果你使用arr[..., index]即使索引本身也可以。就是这样推广到数组堆栈，并对每个数组执行与之前相同的操作）。
需要注意的是take_along_axis提供“一起”的意思为ND普及take到ND正确的（即使它看起来很复杂）。 apply_along_axis和apply_over_axis是我得到“结束”的地方，虽然我不确定“结束”是不是正确的词......

我发现permutation （它不容易改变，但应该是shuffled ）是这里真正的异常值。 它是shuffle - shuffled ， permute - permuted然后我认为事情开始变得非常清晰和合理。 有人愿意添加shuffled并开始弃用permutation吗？ permutation与itertools.permutations行为也不是很一致，FWIW。

我确实认为permutation 、 permute 、 permuted是具有不同行为的听起来相似的名称的混淆三元组。 避免这种情况会很好（可能从长远来看）。

虽然扩展现有的 API 似乎很简单，但我认为@rkern关于没有从根本上改变行为的关键字的观点是最好的途径。

我想对于就地与非就地，我们在 NumPy 中有另一种out=拼写。 但是由于 shuffle 是就地的，这不是解决方案，而 shuffled 很好。 它可能用于permuted （即permuted(arr, out=arr)含义与permute(arr) ，除了 - 与 shuffle 不同 - 它会转换为ndarray ）。
无论如何，我喜欢弃用permutation以支持shuffled来清理新命名空间的计划！

我回到这个问题（以及 https://github.com/numpy/numpy/pull/15121 上的相关 PR）。

回到当我创建原始问题并尝试用当前的shuffle API 描述问题时，有人指出解释问题的一种方法是大多数人会期望axis参数的shuffle作用于相同axis的参数sort 。 与sort的类比非常好，所以看看我们如何处理就地操作与复制排序的问题可能会很有用。 函数numpy.sort()接受一个类似数组的参数并返回一个排序的副本。 对于就地排序，可以使用ndarray sort()方法。 因为它是现有 ndarray 上的一个方法，所以就地操作很清楚。 在 gh-15121 中，随机排列其参数的就地函数的参数必须是 ndarray，而不是类似任意数组。 否则，该函数将不得不执行np.array所做的所有形状发现，并且还拒绝结果为不可变的输入（例如，我们不能对[(1, 2, 3, 4), (5, 6, 7, 8)]进行就地洗牌）。

如果我们能够真正复制sort API，使用返回洗牌副本的函数和就地洗牌的ndarray方法，那就太好了，但我不认为添加这样的ndarray类的方法有可能被接受。

和一个ndarray _method_ 就地洗牌，但我不认为将这样的方法添加到ndarray类有任何被接受的机会。

如果没有单例生成器，我认为这是不可能实现的。

@bashtage写道

我发现permutation （它不容易改变，但应该是shuffled ）是这里真正的异常值。 [如果它] 是shuffle-shuffled ， permute-permuted那么我认为事情开始变得非常清晰和合理。 有人愿意添加shuffled并开始弃用permutation吗？

这就是邮件列表讨论（有点）在 2014 年聚合的内容。这是 Nathaniels 建议的链接： https :

他的scramble[d]就是我在https://github.com/numpy/numpy/pull/15121 中所说的randomly_permute[d] 。

如果我们添加shuffled作为permutation的替代，并调用沿轴permute[d]操作的新方法，则相关函数表为

meaning    operate
of axis    in-place   return copy
-------    ---------  -----------
"over"     shuffle    shuffled
"along"    permute    permuted

它具有很好的一致性。 在此版本的 API 中，所有方法都没有out参数。

在https://github.com/numpy/numpy/pull/15121 中，我最近添加了另一种方法，使用笨拙且明显的临时名称permuted_with_out演示了out参数可能如何用过的。 如果我们使用out参数，并坚持使用现有方法shuffle和permutation ，表格看起来像

meaning    operate
of axis    in-place                           return copy
-------    ---------------------------------  --------------------
"over"     shuffle(x, axis)                   permutation(x, axis)
"along"    permuted_with_out(x, axis, out=x)  permuted_with_out(x, axis)

但是如果我们要引入一个out参数，我们应该保持一致并在permutation使用它。 我们仍然可以考虑用permutation替换shuffled 。 由于新的shuffled方法有一个out参数，它允许就地操作， shuffle变得多余，可以与permutation一起弃用。 然后，切换到shuffled和permuted的“好”名称，表是

    meaning    operate
    of axis    in-place                  return copy
    -------    ------------------------  -----------------
    "over"     shuffled(x, axis, out=x)  shuffled(x, axis)
    "along"    permuted(x, axis, out=x)  permuted(x, axis)

请注意， out参数不仅仅用于就地操作。 它允许重复使用输出数组，从而可能避免创建临时数组。 这是此 API 相对于shuffle/shuffled/permute/permuted API 的优势，但我不确定这种优势究竟有多大。 这个 API 的缺点是弃用了两种方法， shuffle和permutation 。 这些可以是一段时间的“软”弃用（即在文档中不再强调它们的使用，但实际上暂时不添加弃用警告）以减轻直接影响。

这是我对变革的两个主要竞争者的总结。 我们有shuffle/shuffled/permute/permuted版本，或带有shuffled/permuted和out参数的版本。 如果早在 2014 年，有人参与实施所讨论的更改，我们可能已经有了shuffle/shuffled/permute/permuted版本。 但是使用out有几个（小？微不足道？）优点：两个名称而不是四个，并且out可能允许用户拥有更少的临时变量。 我会很高兴与任何一个。

人们怎么看？

在您列出的三个场景中，我会将它们按顺序排列为 1、3，并且远远落后于 2。这 2 个正在做完全不同的事情的排列似乎是一个很大的混乱来源。 我个人的偏好是避免强制使用 out 来访问功能； 我一直认为 out 是一种在某些情况下有意义的性能选择。 我真的不想教学生仅仅为了访问一个功能而使用。 我还假设，如果 3 x = shuffled(x, axis, out=x)也将return x而不是return None ，因此当它到位时，最终可能会得到x出现3次。

我个人的偏好是避免强制使用 out 来访问功能； 我一直认为 out 是一种在某些情况下有意义的性能选择。

但是就地改组_是_一种性能选择，不是吗？

但是就地改组_是_一种性能选择，不是吗？

如果可用，就地也可以是一种编码风格选择。 也许是一个令人困惑的，也许是容易出错的。

我个人的看法是，当 f(x, out=x) 总是感觉有点神奇，因为它有时被用作一种非常不明显的方式来快速实现某些目标。 f(x, inplace=True) 尽管看起来不像其他任何东西，但看起来清晰得多（看起来有点像旧的熊猫模式，但大部分已被删除）。

没错，但这是一种编码风格选择，在 NumPy 中似乎通常使用out=...拼写（除非您使用就地运算符或方法）。 或者也许这是一种编码风格选择，目前在大多数情况下 NumPy 并没有积极尝试简化......

我承认它有点神奇， inplace= kwarg 可能不那么神奇，但也没有真正的优先级？ 而且我不确定它看起来不那么神奇的主要原因是否是就地洗牌是这里算法的核心。 算法细节对大多数学生来说应该无关紧要，最终它使用out=还可以保护大约单个副本+相关的内存带宽，并且与 ufuncs 相当。 （很公平，对于 ufuncs out=input可能有点神奇，但它的常见魔法和已知模式 - 对于高级用户。）

虽然编写起来可能有点乏味，阅读起来也不太快，但np.shuffled(x, out=x)似乎很清楚这种行为是什么。 不明显的部分似乎只是性能影响，在我看来，这似乎是高级用户需要担心的问题。

对于那些提倡使用out的假设问题：如果我们没有现有的函数numpy.sort和ndarray.sort ，而我们现在添加了一个排序函数，首选 API 是numpy.sorted(a, axis=-1, kind=None, order=None, out=None) （无需为就地排序实现ndarray.sort方法）？

ndarray.sort以list.sort ndarray.sort为模型，因此无论如何它可能是一个明智的 API 选择。 也就是说，我会赞成np.sort不存在，而是np.sorted(..., out=...) 。

是的，我认为np.sort应该命名为np.sorted （毕竟就像 python 的sorted() ）。 由于只有方法具有就地行为，因此我认为没有太大的问题。

我不确定“无需实现ndarray.sort ”。 我认为该方法（或其就地行为）没有任何问题。 关于方法的问题仅仅是我们是否觉得提供一种方便的方法速记足够重要。
我想拥有一个就地函数版本也没有错。 not-in-place 版本对新用户来说似乎更好， out=模式对我来说很常见，高级用户得到了足够的服务。

我不确定“无需实现 ndarray.sort 方法”。 我认为该方法（或其就地行为）没有任何问题。

那是我的 API 思想实验的一部分。 我并不是要暗示我们现在拥有的东西有什么问题。 我只是说，如果我们从头开始——并且我将添加到我的假设前提中，我们不关心匹配列表的 Python API——那么用于排序的首选 API 将是numpy.sorted(..., out=...) ，我们不需要其他任何东西。

另一个问题，不是那么假设：如果在这里使用out是首选选项，那么，为了整个 NumPy 的 API 一致性，我们是否应该计划最终将out到numpy.sort ， numpy.partition 、 numpy.argsort ，还有其他所有目前没有的东西？

是的，在我看来，添加一个语义与 ufuncs 相同的out= kwarg 是几乎所有 NumPy API 函数的不错选择。 缺少out参数通常是一个等待进行的增强（尽管，我猜在实践中它可能是一个小的增强，在极少数情况下可能不值得增加太多的代码复杂性）。