[Resend] A few errors in "Python in a Nutshell" - Numeric related

[Fernando Perez]

This is just a resend since it seems A Martelli is back, and I'm pretty sure
he did a massive delete of c.l.py, considering the volume this group
generates :)  I did drop a note on the O'reilly site about this stuff, so
this is just a heads up.

--------------------------
Hi,

I recently got Python in a Nutshell, and as I expected, I've found it to be
extremely informative and well written.  I haven't read it in detail, but
I'm glad I got it.

However, I'd like to point out a few problems I found in Chapter 15, Numeric
processing.  I did not read it in excruciating detail, so please don't
consider this an exhaustive bug hunt of that chapter.  And by the way, that
chapter is a fabulous reference to NumPy, far better for most things than
the standard manual which is organized in a 'cute' (read random) way and
for some things is nearly useless.  Ch. 15 actually explains many things
which the NumPy docs gloss over, and the function reference is
*alphabetized*!! (how hard would it be to do that in the normal manual??)

Anyway, my few nits for future reference:

1) p 306 - a[i][j] vs a[i,j].  This one isn't so much an error but rather a
possibly misleading subtlety.  In p. 306 it says

"... if a's rank is at least 2, you can write a[i][j] as a[i,j] for any
valid i and j..." 

This is, of course, perfectly true and valid.  However, I've seen many
people bitten by thinking that [foo][bar] == [foo,bar] in all cases, and it
is not.  Here's a simple example:

In [1]: z=zeros((3,4,5))

In [2]: z[:][0].shape
Out[2]: (4, 5)

In [3]: z[:,0].shape
Out[3]: (3, 5)

Obviously, in the first case the [:] simply makes a dummy reference to all
of z and the [0] picks its first element along its first axis, giving an
array of shape (4,5).  In the second case, we get the first element along
the second axis, hence an array of shape (3,5).  It might have been
worthwhile pointing this out, as it's a trap that newcomers fall into
repeatedly, especially those with a C/C++ background (a significant chunk
of NumPy's audience).



2) p 312 - flat

In page 312, it says that

"a.flat is an attribute that contains an array with rank of one less than
a..."

This is actually only true for rank 2 arrays.  In general, a.flat is
always a rank 1 array, as long as a is contiguous:

In [4]: z.flat.shape
Out[4]: (60,)

a.flat is truly a 'flat' view of a's data, not just a 'rank(a)-1' view.


3) p 320 - ravel

In p. 320, it says 

"ravel (a) returns the flat form o f a, just like array(a,copy=False).flat"

This is true only if a is contiguous.  The whole point of using ravel is
that it works even if a is non-contiguous:

In [8]: z1=z[::2,::2,::2]

In [9]: z1.iscontiguous()
Out[9]: 0

In [10]: ravel(z1)
Out[10]: array([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0])

In [11]: array(z1,copy=0).flat
---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)

?

ValueError: flattened indexing only available for contiguous array


So the above would be true if it said "... just like
array(a,copy=True).flat".  In that case it would be correct, as a fresh
copy will always be contiguous, hence with a valid .flat attribute.


Anyway, these are just some small nits which readers which use Numeric may
want to be aware of.  If there is an errata page for the book, it may be
worth adding them to it.

Cheers,

Fernando