diff options
author | Matti Picus <matti.picus@gmail.com> | 2020-05-15 09:59:09 +0300 |
---|---|---|
committer | GitHub <noreply@github.com> | 2020-05-15 09:59:09 +0300 |
commit | bb63a1a49bf1fe766ceab3237e0003aef5f19854 (patch) | |
tree | 0404c865acae32a6e30a76a206cfeb1fa7818a60 /numpy/ma | |
parent | 8b81727c50fd7dcb99e4644e8d76f2eaedc4d066 (diff) | |
parent | 533eb93aed5e42b29041bbbfadc5cd57745757fc (diff) | |
download | numpy-bb63a1a49bf1fe766ceab3237e0003aef5f19854.tar.gz |
Merge pull request #16240 from WarrenWeckesser/ptp-warning
DOC: Warn about behavior of ptp with signed integers.
Diffstat (limited to 'numpy/ma')
-rw-r--r-- | numpy/ma/core.py | 47 |
1 files changed, 47 insertions, 0 deletions
diff --git a/numpy/ma/core.py b/numpy/ma/core.py index 705d36c28..8d612b8ed 100644 --- a/numpy/ma/core.py +++ b/numpy/ma/core.py @@ -5863,6 +5863,14 @@ class MaskedArray(ndarray): Return (maximum - minimum) along the given dimension (i.e. peak-to-peak value). + .. 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 ---------- axis : {None, int}, optional @@ -5885,6 +5893,45 @@ class MaskedArray(ndarray): A new array holding the result, unless ``out`` was specified, in which case a reference to ``out`` is returned. + Examples + -------- + >>> x = np.ma.MaskedArray([[4, 9, 2, 10], + ... [6, 9, 7, 12]]) + + >>> x.ptp(axis=1) + masked_array(data=[8, 6], + mask=False, + fill_value=999999) + + >>> x.ptp(axis=0) + masked_array(data=[2, 0, 5, 2], + mask=False, + fill_value=999999) + + >>> x.ptp() + 10 + + This example shows that a negative value can be returned when + the input is an array of signed integers. + + >>> y = np.ma.MaskedArray([[1, 127], + ... [0, 127], + ... [-1, 127], + ... [-2, 127]], dtype=np.int8) + >>> y.ptp(axis=1) + masked_array(data=[ 126, 127, -128, -127], + mask=False, + fill_value=999999, + dtype=int8) + + A work-around is to use the `view()` method to view the result as + unsigned integers with the same bit width: + + >>> y.ptp(axis=1).view(np.uint8) + masked_array(data=[126, 127, 128, 129], + mask=False, + fill_value=999999, + dtype=uint8) """ if out is None: result = self.max(axis=axis, fill_value=fill_value, |