Subsections

 
4.3 Creating arrays with values specified ``on-the-fly''

zeros( shape, type)
ones( shape, type)
Often, one needs to manipulate arrays filled with numbers which aren't available beforehand. The numarray module provides a few functions which create arrays from scratch: zeros and ones simply create arrays of a given shape filled with zeros and ones respectively:
>>> z = zeros((3,3))
>>> print z
[[0 0 0]
 [0 0 0]
 [0 0 0]]
>>> o = ones([2,3])
>>> print o
[[1 1 1]
 [1 1 1]]
Note that the first argument is a shape -- it needs to be a list or a tuple of integers. Also note that the default type for the returned arrays is Int, which you can feel free to override using something like:
>>> o = ones((2,3), Float32)
>>> print o
[[ 1.  1.  1.]
 [ 1.  1.  1.]]

arrayrange( first, limit=None, stride=1, type=None, shape=None)
arange( first, limit=None, stride=1, type=None, shape=None)
The arange function is similar to the range function in Python, except that it returns an array as opposed to a list. arange and arrayrange are equivalent.
>>> r = arange(10)
>>> print r
[0 1 2 3 4 5 6 7 8 9]
Combining the arange with the reshape function, we can get:
>>> big = reshape(arange(100),(10,10))
>>> print big
[[ 0  1  2  3  4  5  6  7  8  9]
 [10 11 12 13 14 15 16 17 18 19]
 [20 21 22 23 24 25 26 27 28 29]
 [30 31 32 33 34 35 36 37 38 39]
 [40 41 42 43 44 45 46 47 48 49]
 [50 51 52 53 54 55 56 57 58 59]
 [60 61 62 63 64 65 66 67 68 69]
 [70 71 72 73 74 75 76 77 78 79]
 [80 81 82 83 84 85 86 87 88 89]
 [90 91 92 93 94 95 96 97 98 99]]
One can set the start, stop and step arguments, which allows for more varied ranges:
>>> print arange(10,-10,-2)
[10  8  6  4  2  0  -2  -4  -6  -8]
An important feature of arange is that it can be used with non-integer starting points and strides:
>>> print arange(5.0)
[ 0. 1. 2. 3. 4.]
>>> print arange(0, 1, .2)
[ 0.   0.2  0.4  0.6  0.8]
If you want to create an array with just one value, repeated over and over, you can use the * operator applied to lists
>>> a = array([[3]*5]*5)
>>> print a
[[3 3 3 3 3]
 [3 3 3 3 3]
 [3 3 3 3 3]
 [3 3 3 3 3]
 [3 3 3 3 3]]
but that is relatively slow, since the duplication is done on Python lists. A quicker way would be to start with 0's and add 3:
         >>> a = zeros([5,5]) + 3
         >>> print a
         [[3 3 3 3 3]
          [3 3 3 3 3]
          [3 3 3 3 3]
          [3 3 3 3 3]
          [3 3 3 3 3]]
The optional type argument can force the type of the resulting array, which is otherwise the ``highest'' of the starting and stopping arguments. The starting argument defaults to 0 if not specified. Note that if a type is specified which is ``lower'' than that which arange would normally use, the array is the result of a precision-losing cast (a round-down, as that used in the astype method for arrays.)

 
4.3.1 Creating an array from a function

fromfunction( object, shape)
Finally, one may want to create an array with contents which are the result of a function evaluation. This is done using the fromfunction function, which takes two arguments, a shape and a callable object (usually a function). For example:
>>> def dist(x,y):
...   return (x-5)**2+(y-5)**2          # distance from (5,5) squared
...
>>> m = fromfunction(dist, (10,10))
>>> print m
[[50 41 34 29 26 25 26 29 34 41]
 [41 32 25 20 17 16 17 20 25 32]
 [34 25 18 13 10  9 10 13 18 25]
 [29 20 13  8  5  4  5  8 13 20]
 [26 17 10  5  2  1  2  5 10 17]
 [25 16  9  4  1  0  1  4  9 16]
 [26 17 10  5  2  1  2  5 10 17]
 [29 20 13  8  5  4  5  8 13 20]
 [34 25 18 13 10  9 10 13 18 25]
 [41 32 25 20 17 16 17 20 25 32]]
>>> m = fromfunction(lambda i,j,k: 100*(i+1)+10*(j+1)+(k+1), (4,2,3))
>>> print m
[[[111 112 113]
  [121 122 123]]
 [[211 212 213]
  [221 222 223]]
 [[311 312 313]
  [321 322 323]]
 [[411 412 413]
  [421 422 423]]]
By examining the above examples, one can see that fromfunction creates an array of the shape specified by its second argument, and with the contents corresponding to the value of the function argument (the first argument) evaluated at the indices of the array. Thus the value of m[3, 4] in the first example above is the value of dist when x=3 and y=4. Similarly for the lambda function in the second example, but with a rank-3 array. The implementation of fromfunction consists of:
def fromfunction(function, dimensions):
    return apply(function, tuple(indices(dimensions)))
which means that the function function is called with arguments given by the sequence indices(dimensions). As described in the definition of indices, this consists of arrays of indices which will be of rank one less than that specified by dimensions. This means that the function argument must accept the same number of arguments as there are dimensions in dimensions, and that each argument will be an array of the same shape as that specified by dimensions. Furthermore, the array which is passed as the first argument corresponds to the indices of each element in the resulting array along the first axis, that which is passed as the second argument corresponds to the indices of each element in the resulting array along the second axis, etc. A consequence of this is that the function which is used with fromfunction will work as expected only if it performs a separable computation on its arguments, and expects its arguments to be indices along each axis. Thus, no logical operation on the arguments can be performed, or any non-shape preserving operation. Thus, the following will not work as expected:
>>> def buggy(test):
...     if test > 4: return 1
...     else: return 0
...
>>> print fromfunction(buggy,(10,))
1
Here is how to do it properly. We add a print statement to the function for clarity:
>>> def notbuggy(test):                 # only works in Python 2.1 & later
...     print test
...     return where(test>4,1,0)
...
>>> fromfunction(notbuggy,(10,))
[0 1 2 3 4 5 6 7 8 9]
array([0, 0, 0, 0, 0, 1, 1, 1, 1, 1])
We leave it as an excercise for the reader to figure out why the ``buggy'' example gave the result 1.

identity( size)
The identity function takes a single integer argument and returns a square identity array (in the ``matrix'' sense) of that size of integers:
      >>> print identity(5)
      [[1 0 0 0 0]
       [0 1 0 0 0]
       [0 0 1 0 0]
       [0 0 0 1 0]
       [0 0 0 0 1]]

Send comments to the NumArray community.