Merge pull request #9826 from charris/gh-9333

DOC: Add unravel_index examples to np.arg(min|max|sort)

1 files changed, 29 insertions, 5 deletions

diff --git a/numpy/core/fromnumeric.py b/numpy/core/fromnumeric.py
index a94be7b4d..ebeea6319 100644
--- a/numpy/core/fromnumeric.py
+++ b/numpy/core/fromnumeric.py
@@ -877,14 +877,22 @@ def argsort(a, axis=-1, kind='quicksort', order=None):
     array([[0, 3],
            [2, 2]])
 
-    >>> np.argsort(x, axis=0)
+    >>> np.argsort(x, axis=0)  # sorts along first axis (down)
     array([[0, 1],
            [1, 0]])
 
-    >>> np.argsort(x, axis=1)
+    >>> np.argsort(x, axis=1)  # sorts along last axis (across)
     array([[0, 1],
            [0, 1]])
 
+    Indices of the sorted elements of a N-dimensional array:
+
+    >>> ind = np.unravel_index(np.argsort(x, axis=None), x.shape)
+    >>> ind
+    (array([0, 1, 1, 0]), array([0, 0, 1, 1]))
+    >>> x[ind]  # same as np.sort(x, axis=None)
+    array([0, 2, 2, 3])
+
     Sorting with keys:
 
     >>> x = np.array([(1, 0), (0, 1)], dtype=[('x', '<i4'), ('y', '<i4')])
@@ -947,11 +955,19 @@ def argmax(a, axis=None, out=None):
     >>> np.argmax(a, axis=1)
     array([2, 2])
 
+    Indexes of the maximal elements of a N-dimensional array:
+
+    >>> ind = np.unravel_index(np.argmax(a, axis=None), a.shape)
+    >>> ind
+    (1, 2)
+    >>> a[ind]
+    5
+
     >>> b = np.arange(6)
     >>> b[1] = 5
     >>> b
     array([0, 5, 2, 3, 4, 5])
-    >>> np.argmax(b) # Only the first occurrence is returned.
+    >>> np.argmax(b)  # Only the first occurrence is returned.
     1
 
     """
@@ -1003,11 +1019,19 @@ 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:
+
+    >>> ind = np.unravel_index(np.argmin(a, axis=None), a.shape)
+    >>> ind
+    (0, 0)
+    >>> a[ind]
+    0
+
     >>> b = np.arange(6)
     >>> b[4] = 0
     >>> b
     array([0, 1, 2, 3, 0, 5])
-    >>> np.argmin(b) # Only the first occurrence is returned.
+    >>> np.argmin(b)  # Only the first occurrence is returned.
     0
 
     """
@@ -2457,7 +2481,7 @@ def prod(a, axis=None, dtype=None, out=None, keepdims=np._NoValue):
     raised on overflow.  That means that, on a 32-bit platform:
 
     >>> x = np.array([536870910, 536870910, 536870910, 536870910])
-    >>> np.prod(x) #random
+    >>> np.prod(x)  # random
     16
 
     The product of an empty array is the neutral element 1: