@@ -36,11 +36,105 @@ Simple random data
3636
3737Permutations
3838============
39+ The methods for randomly permuting a sequence are
40+
3941.. autosummary ::
4042 :toctree: generated/
4143
4244 ~numpy.random.Generator.shuffle
4345 ~numpy.random.Generator.permutation
46+ ~numpy.random.Generator.permuted
47+
48+ The following table summarizes the behaviors of the methods.
49+
50+ +--------------+-------------------+------------------+
51+ | method | copy/in-place | axis handling |
52+ +==============+===================+==================+
53+ | shuffle | in-place | as if 1d |
54+ +--------------+-------------------+------------------+
55+ | permutation | copy | as if 1d |
56+ +--------------+-------------------+------------------+
57+ | permuted | either (use 'out' | axis independent |
58+ | | for in-place) | |
59+ +--------------+-------------------+------------------+
60+
61+ The following subsections provide more details about the differences.
62+
63+ In-place vs. copy
64+ ~~~~~~~~~~~~~~~~~
65+ The main difference between `Generator.shuffle ` and `Generator.permutation `
66+ is that `Generator.shuffle ` operates in-place, while `Generator.permutation `
67+ returns a copy.
68+
69+ By default, `Generator.permuted ` returns a copy. To operate in-place with
70+ `Generator.permuted `, pass the same array as the first argument *and * as
71+ the value of the ``out `` parameter. For example,
72+
73+ >>> rg = np.random.default_rng()
74+ >>> x = np.arange(0 , 15 ).reshape(3 , 5 )
75+ >>> x
76+ array([[ 0, 1, 2, 3, 4],
77+ [ 5, 6, 7, 8, 9],
78+ [10, 11, 12, 13, 14]])
79+ >>> y = rg.permuted(x, axis = 1 , out = x)
80+ >>> x
81+ array([[ 1, 0, 2, 4, 3], # random
82+ [ 6, 7, 8, 9, 5],
83+ [10, 14, 11, 13, 12]])
84+
85+ Note that when ``out `` is given, the return value is ``out ``:
86+
87+ >>> y is x
88+ True
89+
90+ Handling the ``axis `` parameter
91+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
92+ An important distinction for these methods is how they handle the ``axis ``
93+ parameter. Both `Generator.shuffle ` and `Generator.permutation ` treat the
94+ input as a one-dimensional sequence, and the ``axis `` parameter determines
95+ which dimension of the input array to use as the sequence. In the case of a
96+ two-dimensional array, ``axis=0 `` will, in effect, rearrange the rows of the
97+ array, and ``axis=1 `` will rearrange the columns. For example
98+
99+ >>> rg = np.random.default_rng()
100+ >>> x = np.arange(0 , 15 ).reshape(3 , 5 )
101+ >>> x
102+ array([[ 0, 1, 2, 3, 4],
103+ [ 5, 6, 7, 8, 9],
104+ [10, 11, 12, 13, 14]])
105+ >>> rg.permutation(x, axis = 1 )
106+ array([[ 1, 3, 2, 0, 4], # random
107+ [ 6, 8, 7, 5, 9],
108+ [11, 13, 12, 10, 14]])
109+
110+ Note that the columns have been rearranged "in bulk": the values within
111+ each column have not changed.
112+
113+ The method `Generator.permuted ` treats the ``axis `` parameter similar to
114+ how `numpy.sort ` treats it. Each slice along the given axis is shuffled
115+ independently of the others. Compare the following example of the use of
116+ `Generator.permuted ` to the above example of `Generator.permutation `:
117+
118+ >>> rg.permuted(x, axis = 1 )
119+ array([[ 1, 0, 2, 4, 3], # random
120+ [ 5, 7, 6, 9, 8],
121+ [10, 14, 12, 13, 11]])
122+
123+ In this example, the values within each row (i.e. the values along
124+ ``axis=1 ``) have been shuffled independently. This is not a "bulk"
125+ shuffle of the columns.
126+
127+ Shuffling non-NumPy sequences
128+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
129+ `Generator.shuffle ` works on non-NumPy sequences. That is, if it is given
130+ a sequence that is not a NumPy array, it shuffles that sequence in-place.
131+ For example,
132+
133+ >>> rg = np.random.default_rng()
134+ >>> a = [' A' ' B' ' C' ' D' ' E'
135+ >>> rg.shuffle(a) # shuffle the list in-place
136+ >>> a
137+ ['B', 'D', 'A', 'E', 'C'] # random
44138
45139Distributions
46140=============
0 commit comments