NumPy Functional programming: vectorize() function

Last update on August 19 2022 21:50:38 (UTC/GMT +8 hours)

numpy.vectorize() function

The vectorize() function is used to generalize function class.

Define a vectorized function which takes a nested sequence of objects or numpy arrays as inputs and returns an single or tuple of numpy array as output.
The vectorized function evaluates pyfunc over successive tuples of the input arrays like the python map function, except it uses the broadcasting rules of NumPy.

Syntax:

class numpy.vectorize(pyfunc, otypes=None, doc=None, excluded=None, cache=False, signature=None)

Version: 1.15.0

Parameter:

Name	Description	Required / Optional
pyfunc	A python function or method. callable	Required
otypes	The output data type. It must be specified as either a string of typecode characters or a list of data type specifiers. There should be one data type specifier for each output. str or list of dtypes	Optional
doc	The docstring for the function. If None, the docstring will be the pyfunc.__doc__. str	Optional
excluded	Set of strings or integers representing the positional or keyword arguments for which the function will not be vectorized. These will be passed directly to pyfunc unmodified. set	Optional
cache	If True, then cache the first function call that determines the number of outputs if otypes is not provided. bool	Optional
signature	Generalized universal function signature, e.g., (m,n),(n)->(m) for vectorized matrix-vector multiplication. If provided, pyfunc will be called with (and expected to return) arrays with shapes given by the size of corresponding core dimensions. By default, pyfunc is assumed to take scalars as input and output. string	Optional

Returns: vectorized : callable

Vectorized function.

Notes:

The vectorize function is provided primarily for convenience, not for performance.
The implementation is essentially a for loop.

If otypes is not specified, then a call to the function with the first argument will be used to determine the number of outputs.
The results of this call will be cached if cache is True to prevent calling the function twice.
However, to implement the cache, the original function must be wrapped which will slow down subsequent calls, so only do this if your function is expensive.

The new keyword argument interface and excluded argument support further degrades performance.

NumPy.vectorize() method Example:

>>> import numpy as np
>>> def my_func(x, y):
	    "Return x-y if x>y, otherwise return x+y"
    	if x > y:
        	return x - y
    	else:
        	return x + y
>>> vec_func = np.vectorize(my_func)
>>> vec_func([2, 4, 6, 8], 4)

Output:

array([6, 8, 2, 4])

The docstring is taken from the input function to vectorize unless it is specified:

>>> import numpy as np
>>> def my_func(x, y):
    vec_func.__doc__
    'Return a-b if x>y, otherwise return x+y'
>>> vec_func = np.vectorize(my_func, doc="w3resource 'tutorial'")
>>> vec_func.__doc__

Output:

"w3resource 'tutorial'"

The output type is determined by evaluating the first element of the input, unless it is specified:

>>> import numpy as np
>>> out = vec_func([2, 4, 6, 8], 4) 
>>> type(out[0])

Output:

numpy.float64

>>> import numpy as np
>>> def my_func(x, y):
    	vec_func = np.vectorize(my_func, otypes=[float])
>>> out = vec_func([2, 4, 6, 8], 4) 
>>> type(out[0])

Output:

numpy.float64

The excluded argument can be used to prevent vectorizing over certain arguments.
This can be useful for array-like arguments of a fixed length such as the coefficients for a polynomial as in polyval:

>>> import numpy as np
>>> def my_polyval(a, b):
 	     _a = list(a)
 	     res = _a.pop(0)
 	     while _a:
 	         res = res*b + _a.pop(0)
 	     return res
>>> vec_polyval = np.vectorize(my_polyval, excluded=['a'])
>>> vec_polyval(a=[1, 3, 5], b=[0, 1])

Output:

array([5, 9])

Positional arguments may also be excluded by specifying their position:

>>> vec_polyval.excluded.add(0)
>>> vec_polyval([1, 3, 5], b=[0, 1])

Output:

array([5, 9])

The signature argument allows for vectorizing functions that act on non-scalar arrays of fixed length.
For example, you can use it for a vectorized calculation of Pearson correlation coefficient and its p-value:

>>> import scipy.stats
>>> pearsonr = np.vectorize(scipy.stats.pearsonr,
	                         signature='(n),(n)->(),()')
>>> pearsonr([[0, 2, 4, 6]], [[1, 2, 4, 6], [6, 4, 2, 1]])

Output:

(array([ 1., -1.]), array([ 0.,  0.]))

Or for a vectorized convolution:

>>> convolve = np.vectorize(np.convolve, signature='(n),(m)->(k)')
>>> convolve(np.eye(6), [1, 3, 5])

Output:

array([[1., 3., 5., 0., 0., 0., 0., 0.],
       [0., 1., 3., 5., 0., 0., 0., 0.],
       [0., 0., 1., 3., 5., 0., 0., 0.],
       [0., 0., 0., 1., 3., 5., 0., 0.],
       [0., 0., 0., 0., 1., 3., 5., 0.],
       [0., 0., 0., 0., 0., 1., 3., 5.]])

Python - NumPy Code Editor:

Previous: apply_over_axes() function
Next: frompyfunc() function