Added Coarsen

xarray/core/common.py

@@ -591,6 +591,55 @@ def rolling(self, dim=None, min_periods=None, center=False, **dim_kwargs):
         return self._rolling_cls(self, dim, min_periods=min_periods,
                                  center=center)
 
+    def coarsen(self, dim=None, side='left', trim_excess=False,
+                coordinate_func=None, **dim_kwargs):
+        """
+        Coarsen object.
+
+        Parameters
+        ----------
+        dim: dict, optional
+            Mapping from the dimension name to the window size.
+        side : 'left' or 'right', or dict
+            If left, coarsening windows start from 0th index. The excessed
+            entries in the most right will be removed (if trim_excess is True).
+            If right, coarsen windows ends at the most right entry, while
+            excessed entries in the most left will be removed.
+        trim_excess : boolean, default False
+            If true, the excessed entries are trimed. If False, np.nan will be
+            filled.
+        **dim_kwargs : optional
+            The keyword arguments form of ``dim``.
+            One of dim or dim_kwargs must be provided.
+
+        Returns
+        -------
+        Coarsen object (core.rolling.DataArrayCoarsen for DataArray,
+        core.rolling.DatasetCoarsen for Dataset.)
+
+
+        Examples
+        --------
+        Coarsen the long time series by averaging for every seven data.
+
+        >>> da = xr.DataArray(np.linspace(0, 365, num=365),
+        ...                   dims='time',
+        ...                   coords={'time': pd.date_range(
+        ...                       '15/12/1999', periods=365)})
+        >>> da
+        # TODO add example
+
+        See Also
+        --------
+        core.rolling.DataArrayCoarsen
+        core.rolling.DatasetCoarsen
+        """
+        dim = either_dict_or_kwargs(dim, dim_kwargs, 'coarsen')
+        return self._coarsen_cls(
+            self, dim, side=side, trim_excess=trim_excess,
+            coordinate_func=coordinate_func)
+
+
     def resample(self, indexer=None, skipna=None, closed=None, label=None,
                  base=0, keep_attrs=None, **indexer_kwargs):
         """Returns a Resample object for performing resampling operations.
@@ -673,7 +722,7 @@ def resample(self, indexer=None, skipna=None, closed=None, label=None,
             raise TypeError('resample() no longer supports the `how` or '
                             '`dim` arguments. Instead call methods on resample '
                             "objects, e.g., data.resample(time='1D').mean()")
- 
+
         indexer = either_dict_or_kwargs(indexer, indexer_kwargs, 'resample')
 
         if len(indexer) != 1:

xarray/core/dataarray.py

@@ -159,6 +159,7 @@ class DataArray(AbstractArray, DataWithCoords):
     """
     _groupby_cls = groupby.DataArrayGroupBy
     _rolling_cls = rolling.DataArrayRolling
+    _coarsen_cls = rolling.DataArrayCoarsen
     _resample_cls = resample.DataArrayResample
 
     dt = property(DatetimeAccessor)

xarray/core/dataset.py

@@ -318,6 +318,7 @@ class Dataset(Mapping, ImplementsDatasetReduce, DataWithCoords,
     """
     _groupby_cls = groupby.DatasetGroupBy
     _rolling_cls = rolling.DatasetRolling
+    _coarsen_cls = rolling.DatasetCoarsen
     _resample_cls = resample.DatasetResample
 
     def __init__(self, data_vars=None, coords=None, attrs=None,

xarray/core/ops.py

@@ -122,6 +122,20 @@
     New {da_or_ds} object with `{name}` applied along its rolling dimnension.
 """
 
+_COARSEN_REDUCE_DOCSTRING_TEMPLATE = """\
+Coarsen this object by applying `{name}` along its dimensions.
+
+Parameters
+----------
+**kwargs : dict
+    Additional keyword arguments passed on to `{name}`.
+
+Returns
+-------
+reduced : DataArray or Dataset
+    New object with `{name}` applied along its coasen dimnensions.
+"""
+
 
 def fillna(data, other, join="left", dataset_join="left"):
     """Fill missing values in this object with data from the other object.
@@ -378,3 +392,15 @@ def inject_datasetrolling_methods(cls):
     func.__doc__ = _ROLLING_REDUCE_DOCSTRING_TEMPLATE.format(
         name=func.__name__, da_or_ds='Dataset')
     setattr(cls, 'count', func)
+
+
+def inject_coarsen_methods(cls):
+    # standard numpy reduce methods
+    methods = [(name, getattr(duck_array_ops, name))
+               for name in NAN_REDUCE_METHODS]
+    for name, f in methods:
+        func = cls._reduce_method(f)
+        func.__name__ = name
+        func.__doc__ = _COARSEN_REDUCE_DOCSTRING_TEMPLATE.format(
+            name=func.__name__)
+        setattr(cls, name, func)

xarray/core/rolling.py

@@ -5,32 +5,14 @@
 
 import numpy as np
 
-from . import dtypes
+from . import dtypes, utils
 from .dask_array_ops import dask_rolling_wrapper
 from .ops import (
-    bn, has_bottleneck, inject_bottleneck_rolling_methods,
-    inject_datasetrolling_methods)
+    bn, has_bottleneck, inject_coarsen_methods,
+    inject_bottleneck_rolling_methods, inject_datasetrolling_methods)
 from .pycompat import OrderedDict, dask_array_type, zip
 
 
-def _get_new_dimname(dims, new_dim):
-    """ Get an new dimension name based on new_dim, that is not used in dims.
-    If the same name exists, we add an underscore(s) in the head.
-
-    Example1:
-        dims: ['a', 'b', 'c']
-        new_dim: ['_rolling']
-        -> ['_rolling']
-    Example2:
-        dims: ['a', 'b', 'c', '_rolling']
-        new_dim: ['_rolling']
-        -> ['__rolling']
-    """
-    while new_dim in dims:
-        new_dim = '_' + new_dim
-    return new_dim
-
-
 class Rolling(object):
     """A object that implements the moving window pattern.
 
@@ -231,7 +213,7 @@ def reduce(self, func, **kwargs):
         reduced : DataArray
             Array with summarized data.
         """
-        rolling_dim = _get_new_dimname(self.obj.dims, '_rolling_dim')
+        rolling_dim = utils.get_temp_dimname(self.obj.dims, '_rolling_dim')
         windows = self.construct(rolling_dim)
         result = windows.reduce(func, dim=rolling_dim, **kwargs)
 
@@ -242,7 +224,7 @@ def reduce(self, func, **kwargs):
     def _counts(self):
         """ Number of non-nan entries in each rolling window. """
 
-        rolling_dim = _get_new_dimname(self.obj.dims, '_rolling_dim')
+        rolling_dim = utils.get_temp_dimname(self.obj.dims, '_rolling_dim')
         # We use False as the fill_value instead of np.nan, since boolean
         # array is faster to be reduced than object array.
         # The use of skipna==False is also faster since it does not need to
@@ -454,5 +436,121 @@ def construct(self, window_dim, stride=1, fill_value=dtypes.NA):
             **{self.dim: slice(None, None, stride)})
 
 
+class Coarsen(object):
+    """A object that implements the coarsen.
+
+    See Also
+    --------
+    Dataset.coarsen
+    DataArray.coarsen
+    """
+
+    _attributes = ['windows', 'side', 'trim_excess']
+
+    def __init__(self, obj, windows, side, trim_excess, coordinate_func):
+        """
+        Moving window object.
+
+        Parameters
+        ----------
+        obj : Dataset or DataArray
+            Object to window.
+        windows : A mapping from a dimension name to window size
+            dim : str
+                Name of the dimension to create the rolling iterator
+                along (e.g., `time`).
+            window : int
+                Size of the moving window.
+        side : 'left' or 'right' or mapping from dimension to 'left' or 'right'
+        coordinate_func: mapping from coordinate name to func.
+
+        trim_excess : boolean, or dict of boolean default False
+            Set the labels at the center of the window.
+
+        Returns
+        -------
+        coarsen
+        """
+        self.obj = obj
+        self.windows = windows
+        self.side = side
+        self.trim_excess = trim_excess
+
+        if coordinate_func is None:
+            coordinate_func = {}
+        for c in self.obj.coords:
+            if c not in coordinate_func:
+                coordinate_func[c] = np.mean
+        self.coordinate_func = coordinate_func
+
+    def __repr__(self):
+        """provide a nice str repr of our rolling object"""
+
+        attrs = ["{k}->{v}".format(k=k, v=getattr(self, k))
+                 for k in self._attributes
+                 if getattr(self, k, None) is not None]
+        return "{klass} [{attrs}]".format(klass=self.__class__.__name__,
+                                          attrs=','.join(attrs))
+
+
+class DataArrayCoarsen(Coarsen):
+    @classmethod
+    def _reduce_method(cls, func):
+        """
+        Return a wrapped function for injecting numpy and bottoleneck methods.
+        see ops.inject_coarsen_methods
+        """
+        def wrapped_func(self, **kwargs):
+            from .dataarray import DataArray
+
+            reduced = self.obj.variable.coarsen(
+                self.windows, func, self.side, self.trim_excess)
+            coords = {}
+            for c, v in self.obj.coords.items():
+                if c == self.obj.name:
+                    coords[c] = reduced
+                else:
+                    if any(d in self.windows for d in v.dims):
+                        coords[c] = v.variable.coarsen(
+                            self.windows, self.coordinate_func[c], self.side,
+                            self.trim_excess)
+                    else:
+                        coords[c] = v
+            return DataArray(reduced, dims=self.obj.dims, coords=coords)
+
+        return wrapped_func
+
+
+class DatasetCoarsen(Coarsen):
+    @classmethod
+    def _reduce_method(cls, func):
+        """
+        Return a wrapped function for injecting numpy and bottoleneck methods.
+        see ops.inject_coarsen_methods
+        """
+        def wrapped_func(self, **kwargs):
+            from .dataset import Dataset
+
+            reduced = OrderedDict()
+            for key, da in self.obj.data_vars.items():
+                reduced[key] = da.variable.coarsen(
+                    self.windows, func, self.side, self.trim_excess)
+
+            coords = {}
+            for c, v in self.obj.coords.items():
+                if any(d in self.windows for d in v.dims):
+                    coords[c] = v.variable.coarsen(
+                        self.windows, self.coordinate_func[c], self.side,
+                        self.trim_excess)
+                else:
+                    coords[c] = v.variable
+            return Dataset(reduced, coords=coords)
+
+        return wrapped_func
+
+
+
 inject_bottleneck_rolling_methods(DataArrayRolling)
 inject_datasetrolling_methods(DatasetRolling)
+inject_coarsen_methods(DataArrayCoarsen)
+inject_coarsen_methods(DatasetCoarsen)

xarray/core/utils.py

@@ -629,3 +629,21 @@ def datetime_to_numeric(array, offset=None, datetime_unit=None, dtype=float):
     if datetime_unit:
         return (array / np.timedelta64(1, datetime_unit)).astype(dtype)
     return array.astype(dtype)
+
+
+def get_temp_dimname(dims, new_dim):
+    """ Get an new dimension name based on new_dim, that is not used in dims.
+    If the same name exists, we add an underscore(s) in the head.
+
+    Example1:
+        dims: ['a', 'b', 'c']
+        new_dim: ['_rolling']
+        -> ['_rolling']
+    Example2:
+        dims: ['a', 'b', 'c', '_rolling']
+        new_dim: ['_rolling']
+        -> ['__rolling']
+    """
+    while new_dim in dims:
+        new_dim = '_' + new_dim
+    return new_dim

xarray/core/variable.py

@@ -1632,6 +1632,73 @@ def rolling_window(self, dim, window, window_dim, center=False,
             array, axis=self.get_axis_num(dim), window=window,
             center=center, fill_value=fill_value))
 
+    def coarsen(self, windows, func, side='left', trim_excess=False):
+        windows = {k: v for k, v in windows.items() if k in self.dims}
+        new_dimensions = {k: utils.get_temp_dimname(self.dims, k)
+                          for k in windows}
+        reshaped = self._coarsen_reshape(windows, side, trim_excess,
+                                         new_dimensions)
+
+        axis = tuple([reshaped.get_axis_num(d) for d
+                      in new_dimensions.values()])
+        return type(self)(self.dims, func(reshaped, axis=axis), self._attrs)
+
+    def _coarsen_reshape(self, windows, side, trim_excess, coarsen_dimensions):
+        """
+        Construct a reshaped-variable for corsen
+        """
+        if not utils.is_dict_like(side):
+            side = {d: side for d in windows.keys()}
+
+        if not utils.is_dict_like(trim_excess):
+            trim_excess = {d: trim_excess for d in windows.keys()}
+
+        # remove unrelated dimensions
+        side = {k: v for k, v in side.items() if k in self.dims}
+        trim_excess = {k: v for k, v in trim_excess.items() if k in self.dims}
+
+        if windows == {}:
+            return type(self)(self.dims, self.data, self._attrs)
+
+        for d, window in windows.items():
+            if window <= 0:
+                raise ValueError('window must be > 0')
+
+        variable = self
+        for d, window in windows.items():
+            # trim or pad the object
+            size = variable.shape[self._get_axis_num(d)]
+            n = int(size / window)
+            if trim_excess[d]:
+                if side[d] == 'left':
+                    variable = variable.isel({d: slice(window * int(n))})
+                else:
+                    excess = size - window * n
+                    variable = variable.isel({d: slice(excess, None)})
+            else:  # pad
+                pad = window * (n + 1) - size
+                if side[d] == 'left':
+                    pad_widths = {d: (0, pad)}
+                else:
+                    pad_widths = {d: (pad, 0)}
+                variable = variable.pad_with_fill_value(pad_widths)
+
+        shape = []
+        axes = []
+        dims = []
+        for i, d in enumerate(variable.dims):
+            if d in windows:
+                size = variable.shape[i]
+                shape.append(int(size / windows[d]))
+                shape.append(windows[d])
+                dims.append(d)
+                dims.append(coarsen_dimensions[d])
+            else:
+                shape.append(variable.shape[i])
+                dims.append(d)
+
+        return Variable(dims, variable.data.reshape(shape), self._attrs)
+
     @property
     def real(self):
         return type(self)(self.dims, self.data.real, self._attrs)