what does numpy.apply_along_axis perform exactly?

Question

I have come across the numpy.apply_along_axis function in some code. And I don't understand the documentation about it.

This is an example of the documentation:

>>> def new_func(a): ...     """Divide elements of a by 2.""" ...     return a * 0.5 >>> b = np.array([[1,2,3], [4,5,6], [7,8,9]]) >>> np.apply_along_axis(new_func, 0, b) array([[ 0.5,  1. ,  1.5],        [ 2. ,  2.5,  3. ],        [ 3.5,  4. ,  4.5]]) 

As far I as thought I understood the documentation, I would have expected:

array([[ 0.5,  1. ,  1.5],        [ 4  ,  5  ,  6  ],        [ 7  ,  8  ,  9  ]]) 

i.e. having applied the function along the axis [1,2,3] which is axis 0 in [[1,2,3], [4,5,6], [7,8,9]]

Obviously I am wrong. Could you correct me ?

Answer 1

apply_along_axis applies the supplied function along 1D slices of the input array, with the slices taken along the axis you specify. So in your example, new_func is applied over each slice of the array along the first axis. It becomes clearer if you use a vector valued function, rather than a scalar, like this:

In [20]: b = np.array([[1,2,3], [4,5,6], [7,8,9]])  In [21]: np.apply_along_axis(np.diff,0,b) Out[21]:  array([[3, 3, 3],        [3, 3, 3]])  In [22]: np.apply_along_axis(np.diff,1,b) Out[22]:  array([[1, 1],        [1, 1],        [1, 1]]) 

Here, numpy.diff (i.e. the arithmetic difference of adjacent array elements) is applied along each slice of either the first or second axis (dimension) of the input array.

Answer 2

The function is performed on 1-d arrays along axis=0. You can specify another axis using the "axis" argument. A usage of this paradigm is:

np.apply_along_axis(np.cumsum, 0, b) 

The function was performed on each subarray along dimension 0. So, it is meant for 1-D functions and returns a 1D array for each 1-D input.

Another example is :

np.apply_along_axis(np.sum, 0, b) 

Provides a scalar output for a 1-D array. Of course you could just set the axis parameter in cumsum or sum to do the above, but the point here is that it can be used for any 1-D function you write.