issues: 420584430

This is just a suggestion to improve the documentation on apply_ufunc. The way I see it, this is one of the most powerful functions that xarray has to offer but (IMHO) the documentation is really small and with only a few examples.

From personal experience, every time I have to use it I get confused and it takes me a long time to figure out what important keywords like input_core_dims and output_core_dims actually do. After talking to some colleagues of mine I found that they share the same opinion so it appears that I'm not the only one.

PS: I honestly still don't quite understand what most (if not all) of the keywords do, so I'm not the man for the job.

EDIT

An example of something that could be improved upon is this function taken from the documentation:

def mean(obj, dim): # note: apply always moves core dimensions to the end return apply_ufunc(np.mean, obj, input_core_dims=[[dim]], kwargs={'axis': -1})

It's really easy to understand, but if I want to use it with more than one axis it doesn't work:

a=xr.DataArray(np.random.randn(3,3,3), dims=("x", "y", "z")) def mean(obj, dims): # note: apply always moves core dimensions to the end return xr.apply_ufunc(np.mean, obj, input_core_dims=[dims], kwargs={'axis': -1}) mean(a, "x") # works mean(a, ("x", "y")) # returns ValueError: applied function returned data with unexpected number of dimensions: 2 vs 1, for dimensions ('z',)

And I have no idea how to make the second, more general example work.