From 5e05d782b0eadb8ace78b4a34680167e1965a867 Mon Sep 17 00:00:00 2001 From: Romain Hugonnet Date: Fri, 23 Feb 2024 15:17:48 -0900 Subject: [PATCH] Update documentation's "Quick start" (#473) Co-authored-by: adehecq <3285905+adehecq@users.noreply.github.com> --- doc/source/about_xdem.md | 2 +- doc/source/filters.md | 5 -- doc/source/index.md | 4 +- doc/source/intro_dems.md | 5 -- doc/source/quick_start.md | 123 ++++++++++++++++++++++++++--------- environment.yml | 5 +- examples/advanced/README.rst | 5 ++ examples/basic/README.rst | 5 ++ 8 files changed, 108 insertions(+), 46 deletions(-) delete mode 100644 doc/source/filters.md delete mode 100644 doc/source/intro_dems.md diff --git a/doc/source/about_xdem.md b/doc/source/about_xdem.md index ff016ab4..c5cb1d8d 100644 --- a/doc/source/about_xdem.md +++ b/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: diff --git a/doc/source/filters.md b/doc/source/filters.md deleted file mode 100644 index 6a4d914a..00000000 --- a/doc/source/filters.md +++ /dev/null @@ -1,5 +0,0 @@ -(filters)= - -# Filtering - -TODO: In construction diff --git a/doc/source/index.md b/doc/source/index.md index 19d1ce5d..0c4c0a83 100644 --- a/doc/source/index.md +++ b/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 ``` diff --git a/doc/source/intro_dems.md b/doc/source/intro_dems.md deleted file mode 100644 index db1024f4..00000000 --- a/doc/source/intro_dems.md +++ /dev/null @@ -1,5 +0,0 @@ -(intro-dems)= - -# Digital elevation models - -TODO: In construction diff --git a/doc/source/quick_start.md b/doc/source/quick_start.md index 04a64671..f7e67751 100644 --- a/doc/source/quick_start.md +++ b/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 -% -%
-% -% .. 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 +``` diff --git a/environment.yml b/environment.yml index f74242b2..67bf6db1 100644 --- a/environment.yml +++ b/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 diff --git a/examples/advanced/README.rst b/examples/advanced/README.rst index 16e8d5a9..c1f5471f 100644 --- a/examples/advanced/README.rst +++ b/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**. diff --git a/examples/basic/README.rst b/examples/basic/README.rst index a9d0b02c..169a2e7a 100644 --- a/examples/basic/README.rst +++ b/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.