DOC: Add examples for np.arg[min|max|sort]

Show how to retrieve indices for d-dim arrays.

[ci skip]

1 files changed, 18 insertions, 0 deletions

diff --git a/numpy/core/fromnumeric.py b/numpy/core/fromnumeric.py
index a94be7b4d..78b156f21 100644
--- a/numpy/core/fromnumeric.py
+++ b/numpy/core/fromnumeric.py
@@ -885,6 +885,14 @@ def argsort(a, axis=-1, kind='quicksort', order=None):
     array([[0, 1],
            [0, 1]])
 
+    Indices of the sorted elements of a N-dimensional array:
+    >>> np.unravel_index(np.argsort(x, axis=None), x.shape)
+    (array([0, 1, 1, 0]), array([0, 0, 1, 1]))
+    >>> from np.testing import assert_equal
+    >>> assert_equal(x[(array([0, 1, 1, 0]), array([0, 0, 1, 1]))], np.sort(x, axis=None))
+    >>> list(zip(*np.unravel_index(np.argsort(x, axis=None), x.shape)))
+    [(0, 0), (1, 0), (1, 1), (0, 1)]
+
     Sorting with keys:
 
     >>> x = np.array([(1, 0), (0, 1)], dtype=[('x', '<i4'), ('y', '<i4')])
@@ -947,6 +955,11 @@ def argmax(a, axis=None, out=None):
     >>> np.argmax(a, axis=1)
     array([2, 2])
 
+    Indices of the maximal elements of a N-dimensional array:
+    >>> np.unravel_index(np.argmax(a, axis=None), a.shape)
+    (1, 2)
+    >>> np.testing.assert_equal(a[(1, 2)], np.max(a))
+
     >>> b = np.arange(6)
     >>> b[1] = 5
     >>> b
@@ -1003,6 +1016,11 @@ def argmin(a, axis=None, out=None):
     >>> np.argmin(a, axis=1)
     array([0, 0])
 
+    Indices of the minimum elements of a N-dimensional array:
+    >>> np.unravel_index(np.argmin(a, axis=None), a.shape)
+    (0, 0)
+    >>> np.testing.assert_equal(a[(0, 0)], np.min(a))
+
     >>> b = np.arange(6)
     >>> b[4] = 0
     >>> b