Add examples for DataArrayRolling.reduce() (#2968)

* Add Examples to DataArrayRolling.reduce

* Adds two examples to DataArrayRolling.reduce(); the second example
  shows the interaction of reduce() and min_periods

* Update Rolling window operations documentation

* Add a longer description and examples for the `center` and
  `min_period` parameters to `DataArray.rolling()`

Author: kmsquire

doc/computation.rst

@@ -149,20 +149,35 @@ name of the dimension as a key (e.g. ``y``) and the window size as the value
 
     arr.rolling(y=3)
 
-The label position and minimum number of periods in the rolling window are
-controlled by the ``center`` and ``min_periods`` arguments:
+Aggregation and summary methods can be applied directly to the ``Rolling``
+object:
 
 .. ipython:: python
 
-    arr.rolling(y=3, min_periods=2, center=True)
+    r = arr.rolling(y=3)
+    r.reduce(np.std)
+    r.mean()
 
-Aggregation and summary methods can be applied directly to the ``Rolling`` object:
+Aggregation results are assigned the coordinate at the end of each window by
+default, but can be centered by passing ``center=True`` when constructing the
+ ``Rolling`` object:
 
 .. ipython:: python
 
-    r = arr.rolling(y=3)
+    r = arr.rolling(y=3, center=True)
+    r.mean()
+
+As can be seen above, aggregations of windows which overlap the border of the
+array produce ``nan``s.  Setting ``min_periods`` in the call to ``rolling``
+changes the minimum number of observations within the window required to have
+a value when aggregating:
+
+.. ipython:: python
+
+    r = arr.rolling(y=3, min_periods=2)
+    r.mean()
+    r = arr.rolling(y=3, center=True, min_periods=2)
     r.mean()
-    r.reduce(np.std)
 
 Note that rolling window aggregations are faster when bottleneck_ is installed.
 

xarray/core/rolling.py

@@ -211,6 +211,29 @@ def reduce(self, func, **kwargs):
         -------
         reduced : DataArray
             Array with summarized data.
+
+        Examples
+        --------
+        >>> da = DataArray(np.arange(8).reshape(2, 4), dims=('a', 'b'))
+        >>>
+        >>> rolling = da.rolling(b=3)
+        >>> rolling.construct('window_dim')
+        <xarray.DataArray (a: 2, b: 4, window_dim: 3)>
+        array([[[np.nan, np.nan, 0], [np.nan, 0, 1], [0, 1, 2], [1, 2, 3]],
+               [[np.nan, np.nan, 4], [np.nan, 4, 5], [4, 5, 6], [5, 6, 7]]])
+        Dimensions without coordinates: a, b, window_dim
+        >>>
+        >>> rolling.reduce(np.sum)
+        <xarray.DataArray (a: 2, b: 4)>
+        array([[nan, nan,  3.,  6.],
+               [nan, nan, 15., 18.]])
+        Dimensions without coordinates: a, b
+        >>>
+        >>> rolling = da.rolling(b=3, min_periods=1)
+        >>> rolling.reduce(np.nansum)
+        <xarray.DataArray (a: 2, b: 4)>
+        array([[ 0.,  1.,  3.,  6.],
+               [ 4.,  9., 15., 18.]])
         """
         rolling_dim = utils.get_temp_dimname(self.obj.dims, '_rolling_dim')
         windows = self.construct(rolling_dim)