Migration from Numeric to numarray
==================================

There are some minor differences: 

(3) it doesn't allow 'if a:' or 'b = a or default' type of expressions
    to test for empty arrays
(4) take(), compress(), etc. insist on arrays of numbers (no 'O' arrays)
(5) nonzero() now returns a tuple of lists instead of a list only
(6) numbers returned from numpy arrays are not standard python types

All examples assume that numarray was imported as N (import numarray
as N) and Numeric as Numeric.

1) Creating a NumArray from a Numeric.array

    if type( a ) is multiarray.arraytype:
       a = N.array( a )

    This replaces the numeric array by a NumArray. It is also possible
    to make a copy that operates on the same memory:
       b = N.array( N.memory.writeable_buffer(a),
		    typecode=a.typecode(), shape=a.shape )


2) Numeric.average()

    numarray doesn't have an average() function but one of its
    sub-modules has. Biskit.mathUtils.avg() replaces the old
    Numeric.average()

    OLD:
    av = Numeric.average( a, axis=1 ) 
    NEW:
    av = Biskit.mathUtils.avg( a, axis=1 )
    
    
3) Boolean evaluation of arrays.
    
    The following did work for Numeric but does not work with numarray
    because numarray doesn't support boolean evaluation of arrays.
    OLD:
    a = None
    b = a or Numeric.ones( 10 )
    
    This doesn't work any longer either:
    if a:
       print "a is not None"
    
    ERROR:
    RuntimeError: An array doesn't make sense as a truth value.  
    Use sometrue(a) or alltrue(a).

    NEW:
    Biskit.tools.aBool() allows boolean evaluation of NumArrays and
    defaults to the normal bool() for everything else. 
    Biskit.tools.either() replaces the or statement and uses aBool():
    
    b = Biskit.tools.either( a, N.ones( 10 ) )

    if Biskit.tools.aBool( a ):
       print "a is not None"
    

4) Object arrays and take() or compress()

    numarray.take does only support arrays of numbers. Numeric.take
    also supported lists and arrays of objects.  
    ERROR:
    TypeError: Expecting a python numeric type, got something else.    
    NEW:
    Biskit.tools.ltake( a, indices ) implements a take for lists.


5) Nonzero returns tuple
    
    numarray.nonzero() supports multi-dimensional arrays and always
    returns a tuple of index arrays, even if the given array is 1-D.
    OLD:
    i = Numeric.nonzero( mask )
    NEW:
    i = N.nonzero( mask )[0]
    or NEW:
    i = Biskit.mathUtils.nonzero( mask )

6) Comparing arrays

    numarrays cannot be compared to anything of different shape.  
    OLD:
    false = Numeric.ones( (10,10) ) == range(10) 
    ERROR: 
    ValueError: Arrays have incompatible shapes 
    NEW: 
    false = Biskit.mathUtils.arrayEqual( N.ones((10,10)), range(10))

7) numbers returned from numpy arrays are not standard python types

   OLD::
   a = zeros( 10, 'i' )
   if type( a[0] ) is int:
   if type( a[0] ) == int:
   ERROR::
   no error, type( a[0] ) is <type 'numpy.int32'> and the expression evalutes
   to FALSE
   NEW::
   if isinstance( a[0], int ):
