numarray Manual

7.2 Which are the Ufuncs?

Table 7.1 lists all the ufuncs. We will first discuss the mathematical ufuncs, which perform operations very similar to the functions in the math and cmath modules, albeit elementwise, on arrays. Originally, numarray ufuncs came in two forms, unary and binary. More recently (1.3) numarray has added support for ufuncs with up to 16 total input or output parameters. These newer ufuncs are called N-ary ufuncs.

7.2.1 Unary Mathematical Ufuncs

Unary ufuncs take only one argument. The following ufuncs apply the predictable functions on their single array arguments, one element at a time: arccos, arccosh, arcsin, arcsinh, arctan, arctanh, cos, cosh, exp, log, log10, sin, sinh, sqrt, tan, tanh, abs, fabs, floor, ceil, conjugate. As an example:

>>> print x
[0 1 2 3 4]
>>> print cos(x)
[ 1.          0.54030231 -0.41614684 -0.9899925  -0.65364362]
>>> print arccos(cos(x))
[ 0.          1.          2.          3.          2.28318531]
# not a bug, but wraparound: 2*pi%4 is 2.28318531

7.2.2 Binary Mathematical Ufuncs

These ufuncs take two arrays as arguments, and perform the specified mathematical operation on them, one pair of elements at a time: add, subtract, multiply, divide, remainder, power, fmod.

7.2.3 Logical and bitwise ufuncs

The ``logical'' ufuncs also perform their operations on arrays or numbers in elementwise fashion, just like the "mathematical" ones. Two are special (maximum and miminum) in that they return arrays with entries taken from their input arrays:

>>> print x
[0 1 2 3 4]
>>> print y
[ 2.   2.5  3.   3.5  4. ]
>>> print maximum(x, y)
[ 2.   2.5  3.   3.5  4. ]
>>> print minimum(x, y)
[ 0.  1.  2.  3.  4.]

The others logical ufuncs return arrays of 0's or 1's and of type Bool: logical_and, logical_or, logical_xor, logical_not, These are fairly self-explanatory, especially with the associated symbols from the standard Python version of the same operations in Table 7.1 above. The bitwise ufuncs, bitwise_and, bitwise_or, bitwise_xor, bitwise_not, lshift, rshift, on the other hand, only work with integer arrays (of any word size), and will return integer arrays of the larger bit size of the two input arrays:

>>> x
array([7, 7, 0], type=Int8)
>>> y
array([4, 5, 6])
>>> x & y          # bitwise_and(x,y)
array([4, 5, 0])
>>> x | y          # bitwise_or(x,y)
array([7, 7, 6])   
>>> x ^ y          # bitwise_xor(x,y)
array([3, 2, 6]) 
>>> ~ x            # bitwise_not(x)
array([-8, -8, -1], type=Int8)

We discussed finding contents of arrays based on arrays' indices by using slice. Often, especially when dealing with the result of computations or data analysis, one needs to ``pick out'' parts of matrices based on the content of those matrices. For example, it might be useful to find out which elements of an array are negative, and which are positive. The comparison ufuncs are designed for such operation. Assume an array with various positive and negative numbers in it (for the sake of the example we'll generate it from scratch):

>>> print a
[[ 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]]
>>> b = sin(a)
>>> print b
[[ 0.          0.84147098  0.90929743  0.14112001 -0.7568025 ]
 [-0.95892427 -0.2794155   0.6569866   0.98935825  0.41211849]
 [-0.54402111 -0.99999021 -0.53657292  0.42016704  0.99060736]
 [ 0.65028784 -0.28790332 -0.96139749 -0.75098725  0.14987721]
 [ 0.91294525  0.83665564 -0.00885131 -0.8462204  -0.90557836]]
>>> print greater(b, .3)
[[0 1 1 0 0]
 [0 0 1 1 1]
 [0 0 0 1 1]
 [1 0 0 0 0]
 [1 1 0 0 0]]

7.2.4 Comparisons

The comparison functions equal, not_equal, greater, greater_equal, less, and less_equal are invoked by the operators ==, !=, >, >=, <, and <= respectively, but they can also be called directly as functions. Continuing with the preceding example,

>>> print less_equal(b, 0)
[[1 0 0 0 1]
 [1 1 0 0 0]
 [1 1 1 0 0]
 [0 1 1 1 0]
 [0 0 1 1 1]]

This last example has 1's where the corresponding elements are less than or equal to 0, and 0's everywhere else.

The operators and the comparison functions are not exactly equivalent. To compare an array a with an object b, if b can be converted to an array, the result of the comparison is returned. Otherwise, zero is returned. This means that comparing a list and comparing an array can return quite different answers. Since the functional forms such as equal will try to make arrays from their arguments, using equal can result in a different result than using ==.

>>> a = array([1, 2, 3])
>>> b = [1, 2, 3]
>>> print a == 2
[0 1 0]
>>> print b == 2  
0          # (False since 2.3)
>>> print equal(a, 2)
[0 1 0]
>>> print equal(b, 2)
[0 1 0]

7.2.5 Ufunc shorthands

Numarray defines a few functions which correspond to popular ufunc methods: for example, add.reduce is synonymous with the sum utility function:

>>> a = arange(5)                       # [0 1 2 3 4]
>>> print sum(a)                        # 0 + 1 + 2 + 3 + 4
10

Similarly, cumsum is equivalent to add.accumulate (for ``cumulative sum''), product to multiply.reduce, and cumproduct to multiply.accumulate. Additional useful ``utility'' functions are all and any:

>>> a = array([0,1,2,3,4])
>>> print greater(a,0)
[0 1 1 1 1]
>>> all(greater(a,0))
0
>>> any(greater(a,0))
1

Send comments to the NumArray community.