DOC: Improved doc for boolean array indexing

1 files changed, 25 insertions, 3 deletions

diff --git a/numpy/doc/indexing.py b/numpy/doc/indexing.py
index 0439a7a76..15383388c 100644
--- a/numpy/doc/indexing.py
+++ b/numpy/doc/indexing.py
@@ -222,7 +222,7 @@ Boolean or "mask" index arrays
 
 Boolean arrays used as indices are treated in a different manner
 entirely than index arrays. Boolean arrays must be of the same shape
-as the array being indexed, or broadcastable to the same shape. In the
+as the initial dimensions of the array being indexed. In the
 most straightforward case, the boolean array has the same shape: ::
 
  >>> b = y>20
@@ -234,8 +234,8 @@ array corresponding to all the true elements in the boolean array. As
 with index arrays, what is returned is a copy of the data, not a view
 as one gets with slices.
 
-With broadcasting, multidimensional arrays may be the result. For
-example: ::
+With a multidimensional index array, multidimensional arrays may be
+the result. For example: ::
 
  >>> b[:,5] # use a 1-D boolean that broadcasts with y
  array([False, False, False,  True,  True], dtype=bool)
@@ -246,6 +246,28 @@ example: ::
 Here the 4th and 5th rows are selected from the indexed array and
 combined to make a 2-D array.
 
+In general, when the boolean array has fewer dimensions than the array
+being indexed, the shape of the result is the number of True elements
+of the boolean array followed by the remaining dimensions of the array
+being indexed. For example, using a 2-D boolean array of shape (2,3)
+with four True elements to select rows from a 3-D array of shape
+(2,3,5) results in a 2-D result of shape (4,5): ::
+
+ >>> x=np.arange(30).reshape(2,3,5)
+ >>> x
+ array([[[ 0,  1,  2,  3,  4],
+         [ 5,  6,  7,  8,  9],
+         [10, 11, 12, 13, 14]],
+        [[15, 16, 17, 18, 19],
+         [20, 21, 22, 23, 24],
+         [25, 26, 27, 28, 29]]])
+ >>> b=np.array([[True, True, False], [False, True, True]])
+ >>> x[b]
+ array([[ 0,  1,  2,  3,  4],
+        [ 5,  6,  7,  8,  9],
+        [20, 21, 22, 23, 24],
+        [25, 26, 27, 28, 29]])
+
 Combining index arrays with slices
 ==================================