Add support for cftime.datetime coordinates with coarsen

[spencerkclark]

• Tests added
• Fully documented, including whats-new.rst for all changes and api.rst for new API

For now I've held off on making these changes dask-compatible (I could do it, but I'm not sure it is worth the extra complexity).

[jbusecke]

Oh sweet, I just encountered this problem. Would this work on a large dask array with a non-dask time dimension?

[spencerkclark]

Oh, I should have been a little clearer!

For now I've held off on making these changes dask-compatible (I could do it, but I'm not sure it is worth the extra complexity)

This comment only applies to the changes regarding duck_array_ops.mean, which is used by default on the coordinates involved in coarsen. Since indexes are always loaded into memory, i.e. backed by NumPy arrays, we don't really need to worry about dask-compatibility there. In other words with this PR a DataArray can hold dask array data indexed by a cftime time coordinate, and coarsen will work just fine:

In [1]: import xarray as xr

In [2]: import numpy as np

In [3]: data = np.random.random((10, 5))

In [4]: times = xr.cftime_range('2000', periods=10)

In [5]: da = xr.DataArray(data, coords={'time': times}, dims=['time', 'x'])

In [6]: da = da.chunk({'time': 1, 'x': 1})

In [7]: da
Out[7]:
<xarray.DataArray (time: 10, x: 5)>
dask.array<shape=(10, 5), dtype=float64, chunksize=(1, 1)>
Coordinates:
  * time     (time) object 2000-01-01 00:00:00 ... 2000-01-10 00:00:00
Dimensions without coordinates: x

In [8]: da.coarsen(time=2).mean()
Out[8]:
<xarray.DataArray (time: 5, x: 5)>
dask.array<shape=(5, 5), dtype=float64, chunksize=(1, 1)>
Coordinates:
  * time     (time) object 2000-01-01 12:00:00 ... 2000-01-09 12:00:00
Dimensions without coordinates: x

This would only come up as a possible issue if you tried to lazily take the mean of a DataArray of cftime objects, e.g.:

In [9]: da = xr.DataArray(times, dims=['t']).chunk()

In [10]: da
Out[10]:
<xarray.DataArray (t: 10)>
dask.array<shape=(10,), dtype=object, chunksize=(10,)>
Coordinates:
  * t        (t) object 2000-01-01 00:00:00 ... 2000-01-10 00:00:00

In [11]: da.mean()
---------------------------------------------------------------------------
NotImplementedError                       Traceback (most recent call last)
<ipython-input-19-c02402258881> in <module>
----> 1 da.mean()

~/xarray-dev/xarray/xarray/core/common.py in wrapped_func(self, dim, axis, skipna, **kwargs)
     23                              **kwargs):
     24                 return self.reduce(func, dim, axis,
---> 25                                    skipna=skipna, allow_lazy=True, **kwargs)
     26         else:
     27             def wrapped_func(self, dim=None, axis=None,  # type: ignore

~/xarray-dev/xarray/xarray/core/dataarray.py in reduce(self, func, dim, axis, keep_attrs, **kwargs)
   1603         """
   1604
-> 1605         var = self.variable.reduce(func, dim, axis, keep_attrs, **kwargs)
   1606         return self._replace_maybe_drop_dims(var)
   1607

~/xarray-dev/xarray/xarray/core/variable.py in reduce(self, func, dim, axis, keep_attrs, allow_lazy, **kwargs)
   1366             data = func(input_data, axis=axis, **kwargs)
   1367         else:
-> 1368             data = func(input_data, **kwargs)
   1369
   1370         if getattr(data, 'shape', ()) == self.shape:

~/xarray-dev/xarray/xarray/core/duck_array_ops.py in mean(array, axis, skipna, **kwargs)
    348         if isinstance(array, dask_array_type):
    349             raise NotImplementedError(
--> 350                 'Computing the mean of an array containing '
    351                 'cftime.datetime objects is not yet implemented on '
    352                 'dask arrays.')

NotImplementedError: Computing the mean of an array containing cftime.datetime objects is not yet implemented on dask arrays.

but I think that's a pretty rare use case, hence why I've held off on adding that support for now.

[jbusecke]

Oh yeah, that seems totally fair to me. Thanks for clarifying. Cant wait to have this functionality!
Thanks @spencerkclark

[fujiisoup]

Thanks for the follow up pr. Merging.