Merge pull request #16078 from rossbar/doc/axis_to_new_or_different

DOC: Add axis to random module "new or different" docs

2 files changed, 15 insertions, 0 deletions

diff --git a/doc/source/reference/random/index.rst b/doc/source/reference/random/index.rst
index bda9c4d96..d559f2327 100644
--- a/doc/source/reference/random/index.rst
+++ b/doc/source/reference/random/index.rst
@@ -168,6 +168,9 @@ What's New or Different
   Python's `random.random`.
 * All BitGenerators in numpy use `SeedSequence` to convert seeds into
   initialized states.
+* The addition of an ``axis`` keyword argument to methods such as 
+  `Generator.choice`, `Generator.permutation`,  and `Generator.shuffle` 
+  improves support for sampling from and shuffling multi-dimensional arrays.
 
 See :ref:`new-or-different` for a complete list of improvements and
 differences from the traditional ``Randomstate``.
diff --git a/doc/source/reference/random/new-or-different.rst b/doc/source/reference/random/new-or-different.rst
index 1d6b09faf..03e7775a0 100644
--- a/doc/source/reference/random/new-or-different.rst
+++ b/doc/source/reference/random/new-or-different.rst
@@ -115,3 +115,15 @@ And in more detail:
   rg.random(out=existing[:2])
   print(existing)
 
+* Optional ``axis`` argument for methods like `~.Generator.choice`,
+  `~.Generator.permutation` and `~.Generator.shuffle` that controls which
+  axis an operation is performed over for multi-dimensional arrays.
+
+.. ipython:: python
+
+  rg = Generator(PCG64(123456789))
+  a = np.arange(12).reshape((3, 4))
+  a
+  rg.choice(a, axis=1, size=5)
+  rg.shuffle(a, axis=1)        # Shuffle in-place
+  a