From 71c4214b24ec82a4ca82cb8b84a05f585b65c649 Mon Sep 17 00:00:00 2001
From: Romain Hugonnet <romain.hugonnet@gmail.com>
Date: Thu, 5 Dec 2024 15:27:37 -0900
Subject: [PATCH] Incremental commit

---
 doc/source/conf.py           |  3 +--
 doc/source/coregistration.md | 36 ++++++++++++++++++++++++++++++++++++
 2 files changed, 37 insertions(+), 2 deletions(-)

diff --git a/doc/source/conf.py b/doc/source/conf.py
index c8d5dd7a..f37be141 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -66,8 +66,7 @@
 nb_execution_raise_on_error = True  # To fail documentation build on notebook execution error
 nb_execution_show_tb = True  # To show full traceback on notebook execution error
 nb_output_stderr = "warn"  # To warn if an error is raised in a notebook cell (if intended, override to "show" in cell)
-
-# autosummary_generate = True
+nb_execution_mode = "cache"
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/", None),
diff --git a/doc/source/coregistration.md b/doc/source/coregistration.md
index d0b6119c..bd7fc5a7 100644
--- a/doc/source/coregistration.md
+++ b/doc/source/coregistration.md
@@ -493,3 +493,39 @@ These metadata are only inputs specific to a given method, outlined in the metho
 
 For instance, for {class}`xdem.coreg.Deramp`, an input `poly_order` to define the polynomial order used for the fit, and
 for {class}`xdem.coreg.DirectionalBias`, an input `angle` to define the angle at which to do the directional correction.
+
+## Dividing coregistration in blocks
+ 
+### The {class}`~xdem.coreg.BlockwiseCoreg` object
+ 
+Sometimes, we want to split a coregistration across different spatial subsets of an elevation dataset, running that 
+method independently in each subset. A {class}`~xdem.coreg.BlockwiseCoreg` can be constructed for this:
+
+```{code-cell} ipython3
+blockwise = xdem.coreg.BlockwiseCoreg(xdem.coreg.NuthKaab(), subdivision=16)
+```
+
+The subdivision corresponds to an equal-length block division across the extent of the elevation dataset. It needs 
+to be a number of the form 2{sup}`n` (such as 4 or 256).
+
+It is run the same way as other coregistrations:
+
+```{code-cell} ipython3
+# Run 16 block coregistrations
+aligned_dem = blockwise.fit_and_apply(ref_dem, tba_dem_shifted)
+```
+
+```{code-cell} ipython3
+:tags: [hide-input]
+:mystnb:
+:  code_prompt_show: "Show plotting code"
+:  code_prompt_hide: "Hide plotting code"
+
+# Plot before and after
+f, ax = plt.subplots(1, 2)
+ax[0].set_title("Before block NK")
+(tba_dem_shifted - ref_dem).plot(cmap='RdYlBu', vmin=-30, vmax=30, ax=ax[0])
+ax[1].set_title("After block NK")
+(aligned_dem - ref_dem).plot(cmap='RdYlBu', vmin=-30, vmax=30, ax=ax[1], cbar_title="Elevation differences (m)")
+_ = ax[1].set_yticklabels([])
+```
\ No newline at end of file