Update documentation's "Quick start" (#473)

Co-authored-by: adehecq <[email protected]>

doc/source/about_xdem.md

@@ -20,7 +20,7 @@ Additionally, xDEM aims to be **efficient**, **scalable** and **state-of-the-art
 :class: margin
 xDEM is in early stages of development and its features might evolve rapidly. Note the version you are working on for
 **reproducibility**!
-We are working on making features fully consistent for the first long-term release ``v0.1`` (likely sometime in 2023).
+We are working on making features fully consistent for the first long-term release ``v0.1`` (planned early 2024).
 ```
 
 In details, those mean:

doc/source/index.md

@@ -74,7 +74,7 @@ Dive into the full documentation.
 :::{important}
 xDEM is in early stages of development and its features might evolve rapidly. Note the version you are
 working on for reproducibility!
-We are working on making features fully consistent for the first long-term release `v0.1` (likely sometime in 2023).
+We are working on making features fully consistent for the first long-term release `v0.1` (planned early 2024).
 :::
 
 ```{toctree}
@@ -90,7 +90,6 @@ quick_start
 :caption: Background
 :maxdepth: 2
 
-intro_dems
 intro_robuststats
 intro_accuracy_precision
 ```
@@ -103,7 +102,6 @@ vertical_ref
 terrain
 coregistration
 biascorr
-filters
 comparison
 spatialstats
 ```

doc/source/quick_start.md

@@ -1,49 +1,112 @@
+---
+file_format: mystnb
+jupytext:
+  formats: md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+kernelspec:
+  display_name: xdem-env
+  language: python
+  name: xdem
+---
 (quick-start)=
 
 # Quick start
 
-## Sample data
+Below is a short example show-casing some of the core functionalities of xDEM.
+To find an example about a specific functionality, jump directly to {ref}`quick-gallery`.
 
-xDEM comes with some sample data that is used throughout this documentation to demonstrate the features. If not done already, the sample data can be downloaded with the command
+## Short example
 
-```python
-xdem.examples.download_longyearbyen_examples()
+```{note}
+:class: margin
+xDEM relies largely on [its sister-package GeoUtils](https://geoutils.readthedocs.io/) for geospatial handling
+(reprojection, cropping, raster-vector interface, point interpolation) as well as numerics
+(NumPy interface). 🙂
 ```
 
-The dataset keys and paths can be found from
+xDEM revolves around the {class}`~xdem.DEM` class (a subclass of {class}`~geoutils.Raster`), from
+which most methods can be called and the {class}`~xdem.coreg.Coreg` classes to build modular coregistration pipelines.
 
-```python
-xdem.examples.available
+Below, in a few lines, we load two DEMs and a vector of glacier outlines, crop them to a common extent,
+align the DEMs using coregistration, estimate the elevation change, estimate elevation change error using stable
+terrain, and finally plot and save the result!
+
+```{code-cell} ipython3
+import xdem
+import geoutils as gu
+
+# Examples files: filenames of two DEMs and some glacier outlines
+fn_dem_ref = xdem.examples.get_path("longyearbyen_ref_dem")
+fn_dem_tba = xdem.examples.get_path("longyearbyen_tba_dem")
+fn_glacier_outlines = xdem.examples.get_path("longyearbyen_glacier_outlines")
+
+# Print filenames
+print(f"DEM 1: {fn_dem_ref}, \nDEM 2: {fn_dem_tba}, \nOutlines: {fn_glacier_outlines}")
 ```
 
-## Load DEMs and calculate elevation difference
+```{code-cell} ipython3
+# Open files by instantiating DEM and Vector
+# (DEMs are loaded lazily = only metadata but not array unless required)
+dem_ref = xdem.DEM(fn_dem_ref)
+dem_tba = xdem.DEM(fn_dem_tba)
+vect_gla = gu.Vector(fn_glacier_outlines)
 
-```python
-import xdem
+# Clip outlines to extent of reference DEM (method from GeoUtils)
+vect_gla = vect_gla.crop(dem_ref, clip=True)
+
+# Create a mask from glacier polygons (method from GeoUtils)
+mask_gla = vect_gla.create_mask(dem_ref)
+
+# We convert the vertical CRS of one DEM to the EGM96 geoid
+dem_ref.to_vcrs("EGM96", force_source_vcrs="Ellipsoid")
+
+# Align the two DEMs with a coregistration: 3D shift + 2nd-order 2D poly
+mycoreg = xdem.coreg.NuthKaab() + xdem.coreg.Deramp(poly_order=2)
+mycoreg.fit(dem_ref, dem_tba, inlier_mask=~mask_gla)
+dem_aligned = mycoreg.apply(dem_tba)
 
-# Load data
-dem_2009 = xdem.DEM(xdem.examples.get_path("longyearbyen_ref_dem"))
-dem_1990 = xdem.DEM(xdem.examples.get_path("longyearbyen_tba_dem_coreg"))
+# Get elevation difference
+dh = dem_ref - dem_aligned
 
-# Calculate the difference
-ddem = dem_2009 - dem_1990
+# Derive slope and curvature attributes
+slope, maximum_curvature = xdem.terrain.get_terrain_attribute(
+    dem_ref, attribute=["slope", "maximum_curvature"]
+)
 
-# Plot
-ddem.show(cmap='coolwarm_r', vmin=-20, vmax=20, cb_title="Elevation change (m)")
+# Estimate elevation change error from stable terrain as a function of slope and curvature
+dh_err = xdem.spatialstats.infer_heteroscedasticity_from_stable(
+    dh, list_var=[slope, maximum_curvature], unstable_mask=mask_gla
+)[0]
+
+# Plot dh, glacier outlines and its error map
+dh.plot(cmap="RdYlBu", cbar_title="Elevation change (m)")
+vect_gla.plot(dh, fc='none', ec='k', lw=0.5)
+
+dh_err.plot(ax="new", vmin=2, vmax=7, cmap="Reds", cbar_title=r"Elevation change error (1$\sigma$, m)")
+vect_gla.plot(dh_err, fc='none', ec='k', lw=0.5)
 
 # Save to file
-ddem.save("temp.tif")
+dh_err.save("dh_error.tif")
+```
+
+```{code-cell} ipython3
+:tags: [remove-cell]
+import os
+os.remove("dh_error.tif")
 ```
 
-A detailed example on how to load raster data, reproject it to a different grid/projection, run simple arithmetic operations such as subtraction, plotting the data and saving to file can be found in the example gallery {ref}`sphx_glr_basic_examples_plot_dem_subtraction.py`.
-
-% .. raw:: html
-%
-%     <div class="sphx-glr-thumbcontainer" tooltip="DEM subtraction">
-%
-% .. only:: html
-%
-%  .. figure:: /auto_examples/images/thumb/sphx_glr_plot_dem_subtraction_thumb.png
-%      :alt: DEM subtraction
-%
-%      :ref:`sphx_glr_auto_examples_plot_dem_subtraction.py`
+(quick-gallery)=
+## More examples
+
+To dive into more illustrated code, explore our gallery of examples that is composed of:
+- An {ref}`examples-basic` section on simpler routines (terrain attributes, pre-defined coregistration and uncertainty pipelines),
+- An {ref}`examples-advanced` section using advanced pipelines (for in-depth coregistration and uncertainty analysis).
+
+See also the concatenated list of examples below.
+
+```{eval-rst}
+.. minigallery:: xdem.DEM
+    :add-heading: Examples using DEMs
+```

environment.yml

@@ -16,5 +16,6 @@ dependencies:
   - geoutils=0.1.*
   - pip
 
-#  - pip:
-#     - git+https://github.com/GlacioHack/geoutils.git
+  # To run CI against latest GeoUtils
+  # - pip:
+  #   - git+https://github.com/GlacioHack/geoutils.git

examples/advanced/README.rst

@@ -1,2 +1,7 @@
+.. _examples-advanced:
+
 Advanced
 ========
+
+Examples for setting up **specific coregistration or bias-correction pipelines**, **comparing terrain methods**,
+or **refining an error model for DEM uncertainty analysis**.

examples/basic/README.rst

@@ -1,2 +1,7 @@
+.. _examples-basic:
+
 Basic
 =====
+
+Examples using **terrain methods** and **DEM differences**, as well as
+pre-defined **coregistration** and **uncertainty analysis** pipelines.