[SciPy-dev] Numpy example for arctan2 perhaps wrong/misleading/confusing?

[Robert Kern]

On Mon, Jun 9, 2008 at 09:56, Samuel John <scipy at samueljohn.de> wrote:
> Hi David!
>
> On Mon, Jun 9, 2008 at 3:56 PM, David Huard <david.huard at gmail.com> wrote:
>> One thing that you should know is that all "ufunc" (universal functions) are
>> defined as functions operating on scalars. Numpy then wraps these functions
>> such that they can process ndarrays of any shape element by element. This is
>> what is explained in the help(arctan2) documentation.
>
> I see the point for arctan and other functions with a single argument, but not
> for arctan2, especially. It needs two arguments and if I want to
> compute the result of the vectors a=array([a1,a2]) and b=array([b1,b2]) like
>
> arctan2(a,b)
>
> what I get is are the two results as if I would have written:
>
> array([ artcan2(a1,b1), arctan2(a2,b2) ])  #Note, this is NOT (a1,a2)
> or (b1,b2) !!
>
> If you know this and distribute your vector entries over two arrays, the
> broadcasting may be very useful. (As it is for many other functions!)

This is just something you have to know about ufuncs. Ufuncs simply
don't do (a1,a2). Note also, that this is not actually broadcasting
(which describes what happens when you have arrays that don't have the
same dimensions).

> It would be perhaps nice to call arctan2 with just ONE array argument
> and have a broadcasting like this:
>  arctan2( array([[a1,a2],[b1,b2],[c1,c2]]) )
>  --> array([arctan2(a1,a2), arctan2(b1,b2), arctan2(c1,c2) ] )
>
> and arctan2( array([x,y]) ) --> arctan2(x,y)

No, sorry, that's not going to happen.

>> As for the example, maybe a way to avoid confusion would be to give an
>> example with scalar arguments first to show the basic behavior, and then an
>> example using ndarray broadcasting.
>
> I would argue to show just the scalar version in the example and leave out
> the broadcasting version, because it makes less sense here, doesn't it?

There is no difference between this ufunc and any other.

> Is there any fancy matrix-or-whatever notation, that really makes up a
> good example for broadcasting with arctan2?

I think an array example showing the results for each of the four
quadrants would be ideal in order to show why you would use this over
arctan().

-- 
Robert Kern

"I have come to believe that the whole world is an enigma, a harmless
enigma that is made terrible by our own mad attempt to interpret it as
though it had an underlying truth."
 -- Umberto Eco