summaryrefslogtreecommitdiff
path: root/numpy/ma
diff options
context:
space:
mode:
authorEric Wieser <wieser.eric@gmail.com>2018-06-25 23:56:16 -0700
committerEric Wieser <wieser.eric@gmail.com>2018-06-29 02:14:48 -0700
commit917b0794e8e68a443f94299a80c51491cdc1c6cb (patch)
tree7ca1c9ad539db1efc350139f6fa375f6e3593f5d /numpy/ma
parent65f15a5e881817d8646571d36ab9a0bc39a6667e (diff)
downloadnumpy-917b0794e8e68a443f94299a80c51491cdc1c6cb.tar.gz
DOC: Clear up confusion between np.where(cond) and np.where(cond, x, y)
Eliminates all mentions of `np.where(cond)`, instead pointing the reader to np.nonzero. Also changes some example numbers to avoid collisions, making them easier to follow. Some minor doc improvements for np.ma.where too.
Diffstat (limited to 'numpy/ma')
-rw-r--r--numpy/ma/core.py25
1 files changed, 11 insertions, 14 deletions
diff --git a/numpy/ma/core.py b/numpy/ma/core.py
index 091ab4e20..5bfa51b12 100644
--- a/numpy/ma/core.py
+++ b/numpy/ma/core.py
@@ -7115,32 +7115,32 @@ size.__doc__ = np.size.__doc__
def where(condition, x=_NoValue, y=_NoValue):
"""
- Return a masked array with elements from x or y, depending on condition.
+ Return a masked array with elements from `x` or `y`, depending on condition.
- Returns a masked array, shaped like condition, where the elements
- are from `x` when `condition` is True, and from `y` otherwise.
- If neither `x` nor `y` are given, the function returns a tuple of
- indices where `condition` is True (the result of
- ``condition.nonzero()``).
+ .. note::
+ When only `condition` is provided, this function is identical to
+ `nonzero`. The rest of this documentation covers only the case where
+ all three arguments are provided.
Parameters
----------
condition : array_like, bool
- The condition to meet. For each True element, yield the corresponding
- element from `x`, otherwise from `y`.
+ Where True, yield `x`, otherwise yield `y`.
x, y : array_like, optional
Values from which to choose. `x`, `y` and `condition` need to be
broadcastable to some shape.
Returns
-------
- out : MaskedArray or tuple of ndarrays
- The resulting masked array if `x` and `y` were given, otherwise
- the result of ``condition.nonzero()``.
+ out : MaskedArray
+ An masked array with `masked` elements where the condition is masked,
+ elements from `x` where `condition` is True, and elements from `y`
+ elsewhere.
See Also
--------
numpy.where : Equivalent function in the top-level NumPy module.
+ nonzero : The function that is called when x and y are omitted
Examples
--------
@@ -7151,9 +7151,6 @@ def where(condition, x=_NoValue, y=_NoValue):
[[0.0 -- 2.0]
[-- 4.0 --]
[6.0 -- 8.0]]
- >>> np.ma.where(x > 5) # return the indices where x > 5
- (array([2, 2]), array([0, 2]))
-
>>> print(np.ma.where(x > 5, x, -3.1416))
[[-3.1416 -- -3.1416]
[-- -3.1416 --]