Migration from Numeric to numpy
===============================

There are some differences: 

(1) a.typecode() is now a.dtype

(2) arraytype is now numpy.ndarray

(3) numpy doesn't allow 'if a:' or 'b = a or default' type of expressions
    to test for empty arrays

(5) nonzero() now returns a tuple of lists instead of a list only

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

Solutions:
----------

1) a.typecode() is now numpy.ndarray
   
    Numpy doesn't use typecodes any longer but the old Numeric
    typecodes are still supported.

    OLD::
      a.typecode() == 'i'
    
    NEW::
      a.dtype == 'i'

2) arraytype is now numpy.ndarray

    OLD::
      if isinstance( a, Numeric.arraytype ):

    NEW::
      if isinstance( a, N.ndarray ):


3) Boolean evaluation of arrays.
    
    The following did work for Numeric but does not work with numpy
    because numpy 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:
    ValueError: The truth value of an array with more than one element
    is ambiguous. Use a.any() or a.all()

    NEW:

    numpy.any() is tolerant to empty lists and None as input::

      if numpy.any( a ):
          print "a is not None and not empty and not only zeros"

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


    In test cases (a, b are arrays):
    OLD:
      self.assertEqual( a, b )
    ERROR:
      ValueError in unittest

    NEW:
      self.assert_( N.all( a==b ) )

5) Nonzero returns tuple
    
    numpy.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
    
    The == operator in both Numeric and numpy returns again an array.
    So this is already not a good idea in Numeric::

      if Numeric.ones( (10,10) ) == range(10):
    
    and it doesn't work at all in numpy (see point 3).

    NEW: 
    false = Biskit.mathUtils.arrayEqual( N.ones((10,10)), range(10))
