Incremental commit on doc

doc/source/api.md

@@ -231,17 +231,19 @@ To build and pass your coregistration pipeline to {func}`~xdem.DEM.coregister_3d
 .. autosummary::
     :toctree: gen_modules/
 
+    xdem.coreg.Coreg.fit_and_apply
     xdem.coreg.Coreg.fit
     xdem.coreg.Coreg.apply
 ```
 
-#### Other functionalities
+#### Extracting metadata
 
 ```{eval-rst}
 .. autosummary::
     :toctree: gen_modules/
 
-    xdem.coreg.Coreg.residuals
+    xdem.coreg.Coreg.info
+    xdem.coreg.Coreg.meta
 ```
 
 ### Affine coregistration
@@ -274,6 +276,11 @@ To build and pass your coregistration pipeline to {func}`~xdem.DEM.coregister_3d
 
     xdem.coreg.AffineCoreg.from_matrix
     xdem.coreg.AffineCoreg.to_matrix
+    xdem.coreg.AffineCoreg.from_translations
+    xdem.coreg.AffineCoreg.to_translations
+    xdem.coreg.AffineCoreg.from_rotations
+    xdem.coreg.AffineCoreg.to_rotations
+
     xdem.coreg.apply_matrix
     xdem.coreg.invert_matrix
 ```

doc/source/biascorr.md

@@ -76,8 +76,7 @@ Once defined, they can be applied the same two ways as for coregistration (using
 # Coregister with bias correction by calling the DEM method
 corrected_dem = tba_dem.coregister_3d(ref_dem, biascorr)
 # (Equivalent) Or by calling the fit and apply steps
-biascorr.fit(ref_dem, tba_dem)
-corrected_dem = biascorr.apply(tba_dem)
+corrected_dem = biascorr.fit_and_apply(ref_dem, tba_dem)
 ```
 
 Additionally, **bias corrections can be customized to use any number of variables to correct simultaneously**,
@@ -188,8 +187,7 @@ tbc_dem_ramp = ref_dem + synthetic_bias
 # Instantiate a 2nd order 2D deramping
 deramp = xdem.coreg.Deramp(poly_order=2)
 # Fit and apply
-deramp.fit(ref_dem, tbc_dem_ramp)
-corrected_dem = deramp.apply(tbc_dem_ramp)
+corrected_dem = deramp.fit_and_apply(ref_dem, tbc_dem_ramp)
 ```
 
 ```{code-cell} ipython3
@@ -243,8 +241,7 @@ tbc_dem_sumsin = ref_dem + synthetic_bias
 # Define a directional bias correction at a certain angle (degrees), defaults to "bin_and_fit" for a sum of sinusoids
 dirbias = xdem.coreg.DirectionalBias(angle=20)
 # Fit and apply
-dirbias.fit(ref_dem, tbc_dem_sumsin, random_state=42)
-corrected_dem = dirbias.apply(tbc_dem_sumsin)
+corrected_dem = dirbias.fit_and_apply(ref_dem, tbc_dem_sumsin, random_state=42)
 ```
 
 ```{code-cell} ipython3
@@ -290,8 +287,7 @@ tbc_dem_strip = ref_dem + synthetic_bias
 # Define a directional bias correction at a certain angle (degrees), for a binning of 1000 bins
 dirbias = xdem.coreg.DirectionalBias(angle=60, fit_or_bin="bin", bin_sizes=1000)
 # Fit and apply
-dirbias.fit(ref_dem, tbc_dem_strip)
-corrected_dem = dirbias.apply(tbc_dem_strip)
+corrected_dem = dirbias.fit_and_apply(ref_dem, tbc_dem_strip)
 ```
 
 ```{code-cell} ipython3
@@ -346,10 +342,9 @@ tbc_dem_curv = ref_dem + synthetic_bias
 terbias = xdem.coreg.TerrainBias(terrain_attribute="maximum_curvature",
                                  bin_sizes={"maximum_curvature": np.linspace(-5, 5, 1000)},
                                  bin_apply_method="per_bin")
-# Fit and apply to the data
-terbias.fit(ref_dem, tbc_dem_curv)
+
 # We have to pass the original curvature here
-corrected_dem = terbias.apply(tbc_dem_curv, bias_vars={"maximum_curvature": maxc})
+corrected_dem = terbias.fit_and_apply(ref_dem, tbc_dem_curv, bias_vars={"maximum_curvature": maxc})
 ```
 
 ```{code-cell} ipython3
@@ -408,9 +403,13 @@ biascorr = xdem.coreg.BiasCorr(bias_var_names=["aspect", "slope", "elevation"],
 # Derive curvature and slope
 aspect, slope = ref_dem.get_terrain_attribute(["aspect", "slope"])
 
-# Pass the variables to the fit function, matching the names declared above, and same for apply
-biascorr.fit(ref_dem, tba_dem_nk, inlier_mask=inlier_mask, bias_vars={"aspect": aspect, "slope": slope, "elevation": ref_dem})
-corrected_dem = biascorr.apply(tba_dem_nk, bias_vars={"aspect": aspect, "slope": slope, "elevation": ref_dem})
+# Pass the variables to the fit_and_apply function matching the names declared above
+corrected_dem = biascorr.fit_and_apply(
+    ref_dem, 
+    tba_dem_nk, 
+    inlier_mask=inlier_mask, 
+    bias_vars={"aspect": aspect, "slope": slope, "elevation": ref_dem}
+)
 ```
 
 ```{warning}

doc/source/cheatsheet.md

@@ -1,3 +1,74 @@
 (cheatsheet)=
 
 # Cheatsheet: How to correct... ?
+
+In elevation data analysis, the problem generally starts with identifying what correction method to apply when 
+observing a specific pattern of error in your own data.
+
+Below, we summarize a cheatsheet that links what method is likely to correct a pattern of error you can visually 
+identify on **static surfaces of a map of elevation differences with another elevation dataset**!
+
+## Cheatsheet
+
+The patterns of errors categories listed in this spreadsheet **are linked to visual example further below**, so that 
+you can use them as a reference to compare to your own elevation differences.
+
+```{list-table}
+   :widths: 1 2 2 2
+   :header-rows: 1
+   :stub-columns: 1
+
+   * - Pattern
+     - Description
+     - Cause and correction
+     - Notes
+   * - {ref}`sharp-landforms`
+     - Positive and negative errors that are larger near high slopes, making landforms appear visually. 
+     - Likely horizontal shift due to geopositioning errors, use a {ref}`coregistration` such as {class}`~xdem.coreg.NuthKaab`.
+     - Even a tiny horizontal misalignment (1/10th of a pixel) can be visually identified!
+   * - {ref}`smooth-large-field`
+     - Smooth offsets varying at scale of 10 km+, often same sign (either positive or negative).
+     - Likely wrong {ref}`vertical-ref`, can set and transform with {func}`~xdem.DEM.set_vcrs` and {func}`~xdem.DEM.to_vcrs`.
+     - Vertical references often only exists in a user guide, they are not coded in the raster CRS and need to be set manually.
+   * - {ref}`ramp-or-dome`
+     - Ramping errors, often near the edge of the data extent, sometimes with a center dome.
+     - Likely ramp/rotations due to camera errors, use either a {ref}`coregistration` such as {class}`~xdem.coreg.ICP` or a {ref}`bias-correction` such as {class}`~xdem.coreg.Deramp`.
+     - Can sometimes be more rigorously fixed ahead of DEM generation with bundle adjustment.
+   * - {ref}`undulations`
+     - Positive and negative errors undulating patterns at one or several frequencies well larger than pixel size.
+     - Likely jitter-type errors, use a {ref}`bias-correction` such as {class}`~xdem.coreg.DirectionalBias`.
+     - Can sometimes be more rigorously fixed ahead of DEM generation with jitter correction.
+   * - {ref}`point-oscillation`
+     - Point data errors that oscillate between negative and positive.
+     - Likely wrong point-raster comparison, use [point interpolation or reduction on the raster instead](https://geoutils.readthedocs.io/en/stable/raster_vector_point.html#rasterpoint-operations).
+     - Rasterizing point data introduces spatially correlated random errors, instead it is recommended to interpolate raster data at the point coordinates.
+```
+
+## Visual patterns of errors
+
+(sharp-landforms)=
+### Sharp landforms
+
+```{code-cell} ipython3
+# Simulate a translation
+x_shift = 5
+y_shift = 5
+dem_shift = dem.translate(x_shift, y_shift)
+
+# Resample and plot
+dh = dem - dem_shift.reproject(dem)
+dh.plot(cmap='RdYlBu', vmin=-5, vmax=5, ax=ax[1], cbar_title="Elevation differences (m)")
+```
+
+(smooth-large-field)=
+### Smooth large-scale offset field
+
+(ramp-or-dome)=
+### Ramp or dome
+
+(undulations)=
+### Undulations
+
+(point-oscillation)=
+### Point oscillation
+

doc/source/conf.py

@@ -64,6 +64,7 @@
 nb_kernel_rgx_aliases = {".*xdem.*": "python3"}
 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
 
@@ -173,7 +174,6 @@ def setup(app):
     "announcement": (
         "⚠️ Our 0.1 release refactored several early-development functions for long-term stability, "
         'to update your code see <a href="https://github.com/GlacioHack/xdem/releases/tag/v0.1.0">here</a>. ⚠️'
-        "<br>Future changes will come with deprecation warnings! 🙂"
     ),
 }