From 9e5d69c11b6018da9efbb91ffd6aa6834bc12657 Mon Sep 17 00:00:00 2001
From: Kyle Meyer <kyle@kyleam.com>
Date: Thu, 11 Sep 2014 21:01:37 -0400
Subject: [PATCH] DOC: Correct and expand Series.nonzero docstring

- Mention that a tuple of indices is returned and explain why.
- Instead of numpy.ndarray.nonzero, point to numpy.nonzero, which has
  the full documentation.
- Add example.
---
 pandas/core/series.py | 22 +++++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)

diff --git a/pandas/core/series.py b/pandas/core/series.py
index 2c166c231ae34..519e4c4457f04 100644
--- a/pandas/core/series.py
+++ b/pandas/core/series.py
@@ -331,11 +331,27 @@ def compress(self, condition, axis=0, out=None, **kwargs):
 
     def nonzero(self):
         """
-        return the a boolean array of the underlying data is nonzero
+        Return the indices of the elements that are non-zero
 
-        See also
+        This method is equivalent to calling `numpy.nonzero` on the
+        series data. For compatability with NumPy, the return value is
+        the same (a tuple with an array of indices for each dimension),
+        but it will always be a one-item tuple because series only have
+        one dimension.
+
+        Examples
+        --------
+        >>> s = pd.Series([0, 3, 0, 4])
+        >>> s.nonzero()
+        (array([1, 3]),)
+        >>> s.iloc[s.nonzero()[0]]
+        1    3
+        3    4
+        dtype: int64
+
+        See Also
         --------
-        numpy.ndarray.nonzero
+        numpy.nonzero
         """
         return self.values.nonzero()