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

[srean]

Hi All,

 my question might have got lost due to the intense activity around
the 1.7 release. Now that it has quietened down, would appreciate any
help regarding my confusion about how index arrays work
(especially when broadcasted).

-- srean


On Mon, Jun 25, 2012 at 5:29 PM, srean <srean.list at gmail.com> wrote:
> 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.
>
>There is no explanation about
> 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
> is 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