Example using Coarsen.construct to split map into regions (#7192)

* example using coarsen.construct to split map into regions

* whatsnew

* moved to reshape page

* PR number

* fix internal links

* Update doc/whats-new.rst

Co-authored-by: Deepak Cherian <[email protected]>

Co-authored-by: Deepak Cherian <[email protected]>

Author: TomNicholas

doc/user-guide/computation.rst

@@ -360,14 +360,14 @@ and ``mean``, ``std`` and ``var`` return ``NaN``:
   ``weights`` must be a :py:class:`DataArray` and cannot contain missing values.
   Missing values can be replaced manually by ``weights.fillna(0)``.
 
-.. _comput.coarsen:
+.. _compute.coarsen:
 
 Coarsen large arrays
 ====================
 
 :py:class:`DataArray` and :py:class:`Dataset` objects include a
 :py:meth:`~xarray.DataArray.coarsen` and :py:meth:`~xarray.Dataset.coarsen`
-methods. This supports the block aggregation along multiple dimensions,
+methods. This supports block aggregation along multiple dimensions,
 
 .. ipython:: python
 
@@ -403,6 +403,7 @@ function or method name to ``coord_func`` option,
 
     da.coarsen(time=7, x=2, coord_func={"time": "min"}).mean()
 
+You can also :ref:`use coarsen to reshape<reshape.coarsen>` without applying a computation.
 
 .. _compute.using_coordinates:
 

doc/user-guide/reshaping.rst

@@ -4,7 +4,7 @@
 Reshaping and reorganizing data
 ###############################
 
-These methods allow you to reorganize
+These methods allow you to reorganize your data by changing dimensions, array shape, order of values, or indexes.
 
 .. ipython:: python
     :suppress:
@@ -292,3 +292,54 @@ As a shortcut, you can refer to existing coordinates by name:
     ds.sortby("x")
     ds.sortby(["y", "x"])
     ds.sortby(["y", "x"], ascending=False)
+
+.. _reshape.coarsen:
+
+Reshaping via coarsen
+---------------------
+
+Whilst :py:class:`~xarray.DataArray.coarsen` is normally used for reducing your data's resolution by applying a reduction function
+(see the :ref:`page on computation<compute.coarsen>`),
+it can also be used to reorganise your data without applying a computation via :py:meth:`~xarray.core.rolling.DataArrayCoarsen.construct`.
+
+Taking our example tutorial air temperature dataset over the Northern US
+
+.. ipython:: python
+    :suppress:
+
+    # Use defaults so we don't get gridlines in generated docs
+    import matplotlib as mpl
+
+    mpl.rcdefaults()
+
+.. ipython:: python
+
+    air = xr.tutorial.open_dataset("air_temperature")["air"]
+
+    @savefig pre_coarsening.png
+    air.isel(time=0).plot(x="lon", y="lat")
+
+we can split this up into sub-regions of size ``(9, 18)`` points using :py:meth:`~xarray.core.rolling.DataArrayCoarsen.construct`:
+
+.. ipython:: python
+
+    regions = air.coarsen(lat=9, lon=18, boundary="pad").construct(
+        lon=("x_coarse", "x_fine"), lat=("y_coarse", "y_fine")
+    )
+    regions
+
+9 new regions have been created, each of size 9 by 18 points.
+The ``boundary="pad"`` kwarg ensured that all regions are the same size even though the data does not evenly divide into these sizes.
+
+By plotting these 9 regions together via :ref:`faceting<plotting.faceting>` we can see how they relate to the original data.
+
+.. ipython:: python
+
+    @savefig post_coarsening.png
+    regions.isel(time=0).plot(
+        x="x_fine", y="y_fine", col="x_coarse", row="y_coarse", yincrease=False
+    )
+
+We are now free to easily apply any custom computation to each coarsened region of our new dataarray.
+This would involve specifying that applied functions should act over the ``"x_fine"`` and ``"y_fine"`` dimensions,
+but broadcast over the ``"x_coarse"`` and ``"y_coarse"`` dimensions.

doc/whats-new.rst

@@ -58,6 +58,8 @@ Documentation
   Add :py:meth:`__str__` to surface the new :py:class:`BackendEntrypoint` ``description``
   and ``url`` attributes. (:issue:`6577`, :pull:`7000`)
   By `Jessica Scheick <https://github.com/jessicas11>`_.
+- Add example of using :py:meth:`DataArray.coarsen.construct` to User Guide. (:pull:`7192`)
+  By `Tom Nicholas <https://github.com/TomNicholas>`_.
 
 
 Internal Changes
@@ -2995,7 +2997,7 @@ Highlights include:
 - Removed support for Python 2. This is the first version of xarray that is
   Python 3 only!
 - New :py:meth:`~xarray.DataArray.coarsen` and
-  :py:meth:`~xarray.DataArray.integrate` methods. See :ref:`comput.coarsen`
+  :py:meth:`~xarray.DataArray.integrate` methods. See :ref:`compute.coarsen`
   and :ref:`compute.using_coordinates` for details.
 - Many improvements to cftime support. See below for details.
 
@@ -3051,7 +3053,7 @@ Other enhancements
   By `Ryan Abernathey <https://github.com/rabernat>`_
 - :py:meth:`DataArray.coarsen` and
   :py:meth:`Dataset.coarsen` are newly added.
-  See :ref:`comput.coarsen` for details.
+  See :ref:`compute.coarsen` for details.
   (:issue:`2525`)
   By `Keisuke Fujii <https://github.com/fujiisoup>`_.
 - Upsampling an array via interpolation with resample is now dask-compatible,