# dask.array.apply_along_axis

dask.array.apply_along_axis(func1d, axis, arr, *args, dtype=None, shape=None, **kwargs)

  Apply a function to 1-D slices along the given axis.

  This docstring was copied from numpy.apply_along_axis.

  Some inconsistencies with the Dask version may exist.

  This is a blocked variant of `numpy.apply_along_axis()` implemented via `dask.array.map_blocks()`

  Parameters:
    func1d function (M,) -> (Nj…)

      This function should accept 1-D arrays. It is applied to 1-D slices of arr along the specified axis.

    axis integer

      Axis along which arr is sliced.

    arr ndarray (Ni…, M, Nk…)

      Input array.

    args any

      Additional arguments to func1d.

    kwargs any

      Additional named arguments to func1d.

  Returns:
    out ndarray (Ni…, Nj…, Nk…)

      The output array. The shape of out is identical to the shape of arr, except along the axis dimension. This axis is removed, and replaced with new dimensions equal to the shape of the return value of func1d. So if func1d returns a scalar out will have one fewer dimensions than arr.

  See also

  `apply_over_axes`

    Apply a function repeatedly over multiple axes.

  Notes

  If either of dtype or shape are not provided, Dask attempts to determine them by calling func1d on a dummy array. This may produce incorrect values for dtype or shape, so we recommend providing them.

  Execute func1d(a, *args, **kwargs) where func1d operates on 1-D arrays and a is a 1-D slice of arr along axis.

  This is equivalent to (but faster than) the following use of ndindex and s_, which sets each of `ii`, `jj`, and `kk` to a tuple of indices:

      Ni, Nk = a.shape[:axis], a.shape[axis+1:]
      for ii in ndindex(Ni):
          for kk in ndindex(Nk):
              f = func1d(arr[ii + s_[:,] + kk])
              Nj = f.shape
              for jj in ndindex(Nj):
                  out[ii + jj + kk] = f[jj]

  Equivalently, eliminating the inner loop, this can be expressed as:

      Ni, Nk = a.shape[:axis], a.shape[axis+1:]
      for ii in ndindex(Ni):
          for kk in ndindex(Nk):
              out[ii + s_[...,] + kk] = func1d(arr[ii + s_[:,] + kk])

  Examples

      >>> import numpy as np
      >>> def my_func(a):
      ...     """Average first and last element of a 1-D array"""
      ...     return (a[0] + a[-1]) * 0.5
      >>> b = np.array([[1,2,3], [4,5,6], [7,8,9]])
      >>> np.apply_along_axis(my_func, 0, b)
      array([4., 5., 6.])
      >>> np.apply_along_axis(my_func, 1, b)
      array([2.,  5.,  8.])

  For a function that returns a 1D array, the number of dimensions in outarr is the same as arr.

      >>> b = np.array([[8,1,7], [4,3,9], [5,2,6]])
      >>> np.apply_along_axis(sorted, 1, b)
      array([[1, 7, 8],
             [3, 4, 9],
             [2, 5, 6]])

  For a function that returns a higher dimensional array, those dimensions are inserted in place of the axis dimension.

      >>> b = np.array([[1,2,3], [4,5,6], [7,8,9]])
      >>> np.apply_along_axis(np.diag, -1, b)
      array([[[1, 0, 0],
              [0, 2, 0],
              [0, 0, 3]],
             [[4, 0, 0],
              [0, 5, 0],
              [0, 0, 6]],
             [[7, 0, 0],
              [0, 8, 0],
              [0, 0, 9]]])