Add Overlapping trick to docs. (#130)

Author: dcherian

docs/source/user-stories.md

@@ -4,6 +4,7 @@
 .. toctree::
    :maxdepth: 1
 
+   user-stories/overlaps.md
    user-stories/climatology.ipynb
    user-stories/climatology-hourly.ipynb
    user-stories/custom-aggregations.ipynb

docs/source/user-stories/overlaps.md

@@ -0,0 +1,61 @@
+---
+jupytext:
+  text_representation:
+    format_name: myst
+kernelspec:
+  display_name: Python 3
+  name: python3
+---
+
+```{eval-rst}
+.. currentmodule:: flox
+```
+
+# Overlapping Groups
+
+Generally group-by problems involve non-overlapping groups. Consider the following group of labels:
+
+```{code-cell}
+import numpy as np
+import xarray as xr
+
+from flox.xarray import xarray_reduce
+
+labels = xr.DataArray(
+    [1, 2, 3, 1, 2, 3, 0, 0, 0],
+    dims="x",
+    name="label",
+)
+labels
+```
+
+These labels are non-overlapping. So when we reduce this data array over those labels along `x`
+```{code-cell}
+da = xr.ones_like(labels)
+da
+```
+we get (note the reduction over `x` is implicit here):
+
+```{code-cell}
+xarray_reduce(da, labels, func="sum")
+```
+
+Now let's calculate the `sum` where `labels` is either `1` or `2`. The trick is to add a new dimension to `labels` of size `2` and assign a new label `4` in the appropriate locations.
+```{code-cell}
+# assign expanded=4 where label == 1 or 2, and -1 otherwise
+newlabels = xr.where(labels.isin([1, 2]), 4, -1)
+
+# alternative:
+expanded = xr.concat([labels, newlabels], dim="y")
+expanded
+```
+
+Now we reduce over `x` _and_ `y` (again implicitly) to get the appropriate sum under `label=4` (and `label=-1`). We can discard the value accumulated under `label=-1` later.
+```{code-cell}
+xarray_reduce(da, expanded, func="sum")
+```
+
+This technique generalizes to more complicated aggregations. The trick is to
+- generate appropriate labels
+- concatenate these new labels along a new dimension (`y`) absent on the object being reduced (`da`), and
+- reduce over that new dimension in addition to any others.