Repository: numpy/numpy
Pull request: DOC: Add note to ``nonzero`` docstring.
Document problems with using `x.nonzero` for indexing, i.e., never use x[y.nonzero()], use x[y.astype(bool)] instead.

Fixes #13522


Problem statement:
Docs are unclear about behavior of `nonzero` on zero-dim arrays.
<!-- Please describe the issue in detail here, and fill in the fields below -->

From the docs, I would expect `nonzero` on a zero-dim array to return an empty tuple:

> Returns a tuple of arrays, one for each dimension of a, containing the indices of the non-zero elements in that dimension.

### Reproducing code example:

```python
>>> np.array(5).ndim
0
>>> len(np.array(5).nonzero())
1
```

Hints from issue discussion:
cc @mwiebe who (as far as I can tell from git blame) implemented nonzero
You're right that the current behavior is wrong, but I don't think there's a sensible choice to make here.
```python
>>> np.array([[True]]).nonzero()
(array([0], dtype=int64), array([0], dtype=int64))
>>> np.array([[False]]).nonzero()
(array([], dtype=int64), array([], dtype=int64))
```
```python
>>> np.array([True]).nonzero()
(array([0], dtype=int64),)
>>> np.array([False]).nonzero()
(array([], dtype=int64),)
```
```python
>>> np.array(True).nonzero()
(array([0], dtype=int64),)
>>> np.array(False).nonzero()
(array([], dtype=int64),)
```

Perhaps `nonzero` should just throw an exception if called on a 0d array?
One thing to think about is what should `a[a.nonzero()]` return in each case? (`a=np.array(0)` and `a=np.array(5)`)
@umanwizard: The simple answer is "never use `x[y.nonzero()]`, use `x[y.astype(bool)]` instead"
@eric-wieser Should we change the docs informing the above as part of NOTE ?
That sounds like a good idea, although you could probably use more helpful phrasing than I used above.
Got it. @umanwizard Can you please tell the docs location so that I could proceed 
Sorry, I don't work on Numpy, I am not sure where the docs are in the repository.
It lives in the docstring for `nonzero` in `numpy/core/fromnumeric.py`. See also [how to document](http://www.numpy.org/devdocs/docs/index.html)

Commit message: Added NOTE in numpy\core\fromnumeric.py

Patch to review:
diff --git a/numpy/core/fromnumeric.py b/numpy/core/fromnumeric.py
index 7024ac2376c8..4fd358513596 100644
--- a/numpy/core/fromnumeric.py
+++ b/numpy/core/fromnumeric.py
@@ -1761,6 +1761,8 @@ def nonzero(a):
     """
     Return the indices of the elements that are non-zero.
 
+    NOTE - In place of using x[y.nonzero()], it is recommended to use x[y.astype(bool)].
+
     Returns a tuple of arrays, one for each dimension of `a`,
     containing the indices of the non-zero elements in that
     dimension. The values in `a` are always tested and returned in


Code review comments:
diff_hunk: @@ -1761,6 +1761,8 @@ def nonzero(a):
     """
     Return the indices of the elements that are non-zero.
 
+    NOTE - In place of using x[y.nonzero()], it is recommended to use x[y.astype(bool)].
+
path: numpy/core/fromnumeric.py
text: @user1:
Please move this to after the `Return` section as
  
```
Notes
-----
To obtain the non-zero values, it is recommended to use ``x[y.astype(bool)]`` which
will correctly handle 0-d arrays.
```
and refactor the paragraph at 1766 to better express the idea that `nonzero` is the wrong tool for directly indexing the array.
If a line goes over 80 characters, break it up.

@author:
@user1 Ping 

@user1:
the text "The corresponding non-zero ..." on line 1767 above needs rephrasing or removal.