Numeric.transpose (incorrect documentation)

[Tim Hochberg]

"Curtis Jensen" <cjensen at bioeng.ucsd.edu> wrote in message
news:3B6076D4.68B6840C at bioeng.ucsd.edu...
> the documenation for the "transpose" function for the "Numeric" module
> seems to be incoorect, or at least missleading.

The correct place for this is probably the numpy-discussion list, so I'm
cc'ing it there. Perhaps the Paul Dubois will see it and have some ideas for
clearing of the docs.

> It says that transpose is suppose to return a "new" array.  In fact it
> does not.  It returns a pointer to the same array, only with transposed
> indicies.

It's been a while since I looked at the NumPy docs, so I don't recall what
conventions they use here. However, transpose does return a new array, it
just points to the same data as the original. If a=transpose(b), "a is b" is
false and "a.shape == b.shape" is false, so clearly they are different
objects (i.e., different arrays). You know most of this,
as you demonstrate down below, I just wanted to make the point that there is
a difference between a new array and new data.

Note that nearly every operation that can return a reference rather than a
copy does so. Even slicing, if b=a[3:5], then 'b' holds a reference to the
same data as 'a'. Some functions go so far to return a reference when they
can, but otherwise copy. See ravel for example -- it copies the data if its
argument is not contiguous, otherwise it uses a reference. Now _that_ can be
confusing! Useful though.

-tim

> consider the example:
>
> Python 1.5.2 (#4, Sep  5 2000, 10:29:12) [C] on irix646
> Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
> >>> from Numeric import *
> >>> foo = zeros([5,10])
> >>> bar = transpose( foo )
> >>> foo
> array([[0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
>        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
>        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
>        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
>        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0]])
> >>> bar
> array([[0, 0, 0, 0, 0],
>        [0, 0, 0, 0, 0],
>        [0, 0, 0, 0, 0],
>        [0, 0, 0, 0, 0],
>        [0, 0, 0, 0, 0],
>        [0, 0, 0, 0, 0],
>        [0, 0, 0, 0, 0],
>        [0, 0, 0, 0, 0],
>        [0, 0, 0, 0, 0],
>        [0, 0, 0, 0, 0]])
> >>> foo[0,2] = 1
> >>> foo
> array([[0, 0, 1, 0, 0, 0, 0, 0, 0, 0],
>        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
>        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
>        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
>        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0]])
> >>> bar
> array([[0, 0, 0, 0, 0],
>        [0, 0, 0, 0, 0],
>        [1, 0, 0, 0, 0],
>        [0, 0, 0, 0, 0],
>        [0, 0, 0, 0, 0],
>        [0, 0, 0, 0, 0],
>        [0, 0, 0, 0, 0],
>        [0, 0, 0, 0, 0],
>        [0, 0, 0, 0, 0],
>        [0, 0, 0, 0, 0]])
> >>>
>
>
> if bar was truely a new array, then changes to foo would not affect
> bar.  In the example above, it does.  This way actualy works better for
> my purposes, however, the documentation is missleading.
>
> --
> Curtis Jensen
> cjensen at bioeng.ucsd.edu
> http://www-bioeng.ucsd.edu/~cjensen/
> FAX (425) 740-1451