Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

DOC: Add unravel_index examples to np.arg[min|max|sort] #9333

Closed
wants to merge 5 commits into from
Closed

DOC: Add unravel_index examples to np.arg[min|max|sort] #9333

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
08d8225
Exemples for np.arg[min|max|sort] on how to retrieve indices for d-di…
ElieGouzien Jun 29, 2017
364a575
Exemples for np.arg[min|max|sort] on how to retrieve indices for d-di…
ElieGouzien Jun 29, 2017
2b514e3
Exemples for np.arg[min|max|sort] : use of "coordinates" instead of "…
ElieGouzien Jun 29, 2017
51d0710
Revert "coordinates" to "indices".
ElieGouzien Aug 4, 2017
cf43db7
Doc : show that the result of the exemple is directly usable as indices.
ElieGouzien Aug 7, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
18 changes: 18 additions & 0 deletions numpy/core/fromnumeric.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -890,6 +890,14 @@ def argsort(a, axis=-1, kind='quicksort', order=None):
array([[0, 1],
[0, 1]])

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you add a short description here to explain the example? That would also be appreciated in the other examples.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about "Retrieving global sorting indices:" ?
I'm not native English speaker so don't hesitate to propose a reformulated version.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe: "Indices along each axis for sorting the flattened array"

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Numpy superpowers come from the fact that the user can forget that he lives in a flat space, so I prefer avoiding a description of how it works to privilege what we get. See my new commit for my next intent (which is far from perfect).

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)]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This might be clearer as:

>>> 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)
<whatever it is>

Repeating the call to unravel_index is obscuring the point, and assert_equal isn't that useful in docs. (we don't run doctests)


Sorting with keys:

>>> x = np.array([(1, 0), (0, 1)], dtype=[('x', '<i4'), ('y', '<i4')])
Expand Down Expand Up @@ -952,6 +960,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)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would be nice to show that the result of this can be used to index directly into a, and the same for the argsort example

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For sure, it's committed. Let me know if you like the way I've written it.

>>> np.testing.assert_equal(a[(1, 2)], np.max(a))

>>> b = np.arange(6)
>>> b[1] = 5
>>> b
Expand Down Expand Up @@ -1008,6 +1021,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
Expand Down