DOC: Warn about behavior of ptp with signed integers.

* Add a warning to the docstrings of numpy.ma.MaskedArray.ptp and
  numpy.ptp about a problem with signed integer arrays.
* Add an example to the the docstring of numpy.ptp that demonstrates
  the issue and suggests a work-around.
* Add an "Examples" section to the docstring of MaskedArray.ptp
  which includes the new example added to the docstring of numpy.ptp.
* Make the numbers in the basic example more interesting.

1 files changed, 32 insertions, 7 deletions

diff --git a/numpy/core/fromnumeric.py b/numpy/core/fromnumeric.py
index b32ad8d35..285b75314 100644
--- a/numpy/core/fromnumeric.py
+++ b/numpy/core/fromnumeric.py
@@ -2494,6 +2494,14 @@ def ptp(a, axis=None, out=None, keepdims=np._NoValue):
 
     The name of the function comes from the acronym for 'peak to peak'.
 
+    .. warning::
+        `ptp` preserves the data type of the array. This means the
+        return value for an input of signed integers with n bits
+        (e.g. `np.int8`, `np.int16`, etc) is also a signed integer
+        with n bits.  In that case, peak-to-peak values greater than
+        ``2**(n-1)-1`` will be returned as negative values. An example
+        with a work-around is shown below.
+
     Parameters
     ----------
     a : array_like
@@ -2531,16 +2539,33 @@ def ptp(a, axis=None, out=None, keepdims=np._NoValue):
 
     Examples
     --------
-    >>> x = np.arange(4).reshape((2,2))
-    >>> x
-    array([[0, 1],
-           [2, 3]])
+    >>> x = np.array([[4, 9, 2, 10],
+    ...               [6, 9, 7, 12]])
+
+    >>> np.ptp(x, axis=1)
+    array([8, 6])
 
     >>> np.ptp(x, axis=0)
-    array([2, 2])
+    array([2, 0, 5, 2])
 
-    >>> np.ptp(x, axis=1)
-    array([1, 1])
+    >>> np.ptp(x)
+    10
+
+    This example shows that a negative value can be returned when
+    the input is an array of signed integers.
+
+    >>> y = np.array([[1, 127],
+    ...               [0, 127],
+    ...               [-1, 127],
+    ...               [-2, 127]], dtype=np.int8)
+    >>> np.ptp(y, axis=1)
+    array([ 126,  127, -128, -127], dtype=int8)
+
+    A work-around is to use the `view()` method to view the result as
+    unsigned integers with the same bit width:
+
+    >>> np.ptp(y, axis=1).view(np.uint8)
+    array([126, 127, 128, 129], dtype=uint8)
 
     """
     kwargs = {}