Add unique method

[ahuang11]

• Closes Add "unique()" method, mimicking pandas #2795
• Tests added
• Passes pre-commit run --all-files
• User visible changes (including notable bug fixes) are documented in whats-new.rst
• New functions/methods are listed in api.rst

[max-sixty]

Thank you for the PR @ahuang11 !

What are people's thoughts?

We don't have precedent for methods that return a numpy array. But it's unclear what xarray object this would return.

[rhkleijn]

We don't have precedent for methods that return a numpy array. But it's unclear what xarray object this would return.

There is a precedent in xarray (it might be the only one):

In [2]: xr.DataArray([1,2,3,4,5]).searchsorted([-10, 10, 2, 3])
Out[2]: array([0, 5, 1, 2])

[shoyer]

We don't have precedent for methods that return a numpy array. But it's unclear what xarray object this would return.

There is a precedent in xarray (it might be the only one):

In [2]: xr.DataArray([1,2,3,4,5]).searchsorted([-10, 10, 2, 3])
Out[2]: array([0, 5, 1, 2])

I think searchsorted was probably a mistake from the very early days of Xarray.

I would lean against adding unique. These functions are very short to write (and thus easy to reproduce in user code), so it's not clear that the cost/benefit is worth it.

[ahuang11]

What if we added coordinates/dims to it and it returns a stacked dimension if multiple dims?

def unique(da):
    da_stack = da.stack({'tmp_dim': da.dims})
    _, index = np.unique(da_stack.values, return_index=True)
    return da_stack.isel({'tmp_dim': index})

da = xr.DataArray([[[0, 1, 1], [2, 3, 4], [4, 5, 6]], [[7, 8, 9], [10, 11, 12], [13, 14, 15]]],
                  coords={'lat': [0, 1, 2], 'lon': [4, 5, 6], 'time': [7, 8]}, dims=['time', 'lat', 'lon'])
unique(da)  # would be da.unique()

Then users can use da.unique().unstack() if they like.

[shoyer]

Let's sort out drop_duplicates (#5089) first. I imagine unique() could be a special case of the exact same logic.