Add map_blocks example to docs. (#3667)

Author: bradyrx

xarray/core/parallel.py

@@ -154,6 +154,48 @@ def map_blocks(
     --------
     dask.array.map_blocks, xarray.apply_ufunc, xarray.Dataset.map_blocks,
     xarray.DataArray.map_blocks
+
+    Examples
+    --------
+
+    Calculate an anomaly from climatology using ``.groupby()``. Using
+    ``xr.map_blocks()`` allows for parallel operations with knowledge of ``xarray``,
+    its indices, and its methods like ``.groupby()``.
+
+    >>> def calculate_anomaly(da, groupby_type='time.month'):
+    ...     # Necessary workaround to xarray's check with zero dimensions
+    ...     # https://github.com/pydata/xarray/issues/3575
+    ...     if sum(da.shape) == 0:
+    ...         return da
+    ...     gb = da.groupby(groupby_type)
+    ...     clim = gb.mean(dim='time')
+    ...     return gb - clim
+    >>> time = xr.cftime_range('1990-01', '1992-01', freq='M')
+    >>> np.random.seed(123)
+    >>> array = xr.DataArray(np.random.rand(len(time)),
+    ...                      dims="time", coords=[time]).chunk()
+    >>> xr.map_blocks(calculate_anomaly, array).compute()
+    <xarray.DataArray (time: 24)>
+    array([ 0.12894847,  0.11323072, -0.0855964 , -0.09334032,  0.26848862,
+            0.12382735,  0.22460641,  0.07650108, -0.07673453, -0.22865714,
+           -0.19063865,  0.0590131 , -0.12894847, -0.11323072,  0.0855964 ,
+            0.09334032, -0.26848862, -0.12382735, -0.22460641, -0.07650108,
+            0.07673453,  0.22865714,  0.19063865, -0.0590131 ])
+    Coordinates:
+      * time     (time) object 1990-01-31 00:00:00 ... 1991-12-31 00:00:00
+
+    Note that one must explicitly use ``args=[]`` and ``kwargs={}`` to pass arguments
+    to the function being applied in ``xr.map_blocks()``:
+
+    >>> xr.map_blocks(calculate_anomaly, array, kwargs={'groupby_type': 'time.year'})
+    <xarray.DataArray (time: 24)>
+    array([ 0.15361741, -0.25671244, -0.31600032,  0.008463  ,  0.1766172 ,
+           -0.11974531,  0.43791243,  0.14197797, -0.06191987, -0.15073425,
+           -0.19967375,  0.18619794, -0.05100474, -0.42989909, -0.09153273,
+            0.24841842, -0.30708526, -0.31412523,  0.04197439,  0.0422506 ,
+            0.14482397,  0.35985481,  0.23487834,  0.12144652])
+    Coordinates:
+        * time     (time) object 1990-01-31 00:00:00 ... 1991-12-31 00:00:00
     """
 
     def _wrapper(func, obj, to_array, args, kwargs):