[Numpy-discussion] Semantics of index arrays and a request to fix the user guide

[srean]

>From the user guide:
-----------------------------

> Boolean arrays must be of the same shape as the array being indexed,
> or broadcastable to the same shape. In the most straightforward case,
>  the boolean array has the same shape.

Comment: So far so good, but the doc has not told me yet what is the
shape or the output.
--------------

user guide continues with an example:
------------------------------------------------------

> The result is a 1-D array containing all the elements in the indexed array corresponding to all the true elements in the boolean array.


Comment:
--------------

Now it is not clear from that line whether the shape of the result is
generally true or is it specific to the example. So the reader (me) is
still confused.


User Guide continues:
--------------------------------

> With broadcasting, multidimensional arrays may be the result. For example...

Comment:
--------------

I will get to the example in a minute, but there is no explanation of
the mechanism used to arrive at the output shape, is it the shape of
what the index array was broadcasted to ? or is it something else, if
it is the latter, what is it.

Example
------------

The example indexes a (5,7) array with a (5,) index array. Now this
very confusing because it seems to contradict the original
documentation because
(5,) is neither the same shape as (5,7) nor is it broadcastable to it.

The steps of the conventional broaddcasting would yield

(5,7)
(5,)

then

(5,7)
(1,5)

then an error because 7 and 5 dont match.



User guide continues:
------------------------------

> Combining index arrays with slices.

> In effect, the slice is converted to an index array
> np.array([[1,2]]) (shape (1,2)) that is broadcast with
>  the index array to produce a resultant array of shape (3,2).

comment:
-------------

Here the two arrays have shape

(3,) and (1,2) so how does broadcasting yield the shape 3,2.
Broadcasting is supposed to proceed trailing dimension first but it
seems in these examples it is doing the opposite.

=====

So could someone explain the semantics and make the user guide more precise.

Assuming the user guide will be the first document the new user will
read it is surprisingly difficult to read, primarily because it gets
into advanced topics to soon and partially because of ambiguous
language. The numpy reference on the other hand is very clear as is
Travis's book which I am glad to say I actually bought a long time
ago.

Thanks,
  srean