Split sphinx gallery into two subsections

.gitignore

@@ -139,8 +139,11 @@ dmypy.json
 # version file
 xdem/version.py
 
-examples/*/data/
-auto_examples/
-gen_modules/
-examples/*/processed
-examples/temp.tif
+# Example data downloaded/produced during tests
+examples/data/Longyearbyen/data/
+examples/data/Longyearbyen/processed/
+
+docs/source/basic_examples/
+docs/source/advanced_examples/
+docs/source/gen_modules/
+examples/basic/temp.tif

docs/source/conf.py

@@ -18,6 +18,7 @@
 sys.path.append(os.path.abspath("../../xdem/"))
 sys.path.append(os.path.abspath(".."))
 
+from sphinx_gallery.sorting import ExplicitOrder
 import xdem.version
 
 # -- Project information -----------------------------------------------------
@@ -61,16 +62,19 @@
 }
 
 sphinx_gallery_conf = {
-     "examples_dirs": os.path.join(os.path.dirname(__file__), "../", "../", "examples"),   # path to your example scripts
-     "gallery_dirs": "auto_examples",  # path to where to save gallery generated output
+     "examples_dirs": [os.path.join(os.path.dirname(__file__), "../", "../", "examples/basic"),
+                       os.path.join(os.path.dirname(__file__), "../", "../", "examples/advanced")],   # path to your example scripts
+     "gallery_dirs": ["basic_examples", "advanced_examples"],  # path to where to save gallery generated output
      "inspect_global_variables": True,  # Make links to the class/function definitions.
      "reference_url": {
          # The module you locally document uses None
         "xdem": None,
     },
      # directory where function/class granular galleries are stored
     "backreferences_dir"  : "gen_modules/backreferences",
-    "doc_module": ("xdem", "geoutils")  # which function/class levels are used to create galleries
+    "doc_module": ("xdem", "geoutils"),  # which function/class levels are used to create galleries
+    # 'subsection_order': ExplicitOrder([os.path.join(os.path.dirname(__file__), "../", "../", "examples", "basic"),
+    #                                    os.path.join(os.path.dirname(__file__), "../", "../", "examples", "advanced")])
 }
 
 # Add any paths that contain templates here, relative to this directory.

docs/source/index.rst

@@ -40,7 +40,8 @@ xDEM aims at simplifying the analysis of digital elevation models (DEMs). This m
    :maxdepth: 2
    :caption: Gallery of examples
 
-   auto_examples/index.rst
+   basic_examples/index.rst
+   advanced_examples/index.rst
 
 .. toctree::
    :maxdepth: 2

docs/source/quick_start.rst

@@ -38,7 +38,7 @@ Load DEMs and calculate elevation difference
   # Save to file
   ddem.save("temp.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_auto_examples_plot_dem_subtraction.py`.
+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

docs/source/terrain.rst

@@ -21,10 +21,10 @@ The slope can be computed either by the method of `Horn (1981) <http://dx.doi.or
 based on a refined gradient formulation on a 3x3 pixel window, or by the method of `Zevenbergen and Thorne (1987)
 <http://dx.doi.org/10.1002/esp.3290120107>`_ based on a plane fit on a 3x3 pixel window.
 
-The differences between methods are illustrated in the :ref:`sphx_glr_auto_examples_plot_terrain_attributes.py`
+The differences between methods are illustrated in the :ref:`sphx_glr_basic_examples_plot_terrain_attributes.py`
 example.
 
-.. image:: auto_examples/images/sphx_glr_plot_terrain_attributes_001.png
+.. image:: basic_examples/images/sphx_glr_plot_terrain_attributes_001.png
   :width: 600
 
 .. minigallery:: xdem.terrain.slope
@@ -41,7 +41,7 @@ aspect is 90°, south is 180° and west is 270°. By default, a flat slope is gi
 As the aspect is directly based on the slope, it varies between the method of `Horn (1981) <http://dx.doi.org/10.
 1109/PROC.1981.11918>`_ (default) and that of `Zevenbergen and Thorne (1987) <http://dx.doi.org/10.1002/esp.3290120107>`_.
 
-.. image:: auto_examples/images/sphx_glr_plot_terrain_attributes_002.png
+.. image:: basic_examples/images/sphx_glr_plot_terrain_attributes_002.png
   :width: 600
 
 .. minigallery:: xdem.terrain.aspect
@@ -66,7 +66,7 @@ As the hillshade is directly based on the slope and aspect, it varies between th
 Note, however, that the hillshade is not a shadow map; no occlusion is taken into account so it does not represent "true" shading.
 It therefore has little analytic purpose, but it still constitutes a great visualization tool.
 
-.. image:: auto_examples/images/sphx_glr_plot_terrain_attributes_003.png
+.. image:: basic_examples/images/sphx_glr_plot_terrain_attributes_003.png
   :width: 600
 
 .. minigallery:: xdem.terrain.hillshade
@@ -83,7 +83,7 @@ The curvature values in units of m\ :sup:`-1` are quite small, so they are by co
 
 The curvature is based on the method of `Zevenbergen and Thorne (1987) <http://dx.doi.org/10.1002/esp.3290120107>`_.
 
-.. image:: auto_examples/images/sphx_glr_plot_terrain_attributes_004.png
+.. image:: basic_examples/images/sphx_glr_plot_terrain_attributes_004.png
   :width: 600
 
 .. minigallery:: xdem.terrain.curvature
@@ -97,7 +97,7 @@ The planform curvature is the curvature perpendicular to the direction of slope,
 
 It is based on the method of `Zevenbergen and Thorne (1987) <http://dx.doi.org/10.1002/esp.3290120107>`_.
 
-.. image:: auto_examples/images/sphx_glr_plot_terrain_attributes_005.png
+.. image:: basic_examples/images/sphx_glr_plot_terrain_attributes_005.png
   :width: 600
 
 .. minigallery:: xdem.terrain.planform_curvature
@@ -111,7 +111,7 @@ The profile curvature is the curvature parallel to the direction of slope, repor
 
 It is based on the method of `Zevenbergen and Thorne (1987) <http://dx.doi.org/10.1002/esp.3290120107>`_.
 
-.. image:: auto_examples/images/sphx_glr_plot_terrain_attributes_006.png
+.. image:: basic_examples/images/sphx_glr_plot_terrain_attributes_006.png
   :width: 600
 
 .. minigallery:: xdem.terrain.profile_curvature
@@ -126,7 +126,7 @@ The Topographic Position Index (TPI) is a metric of slope position, based on the
 pixel with the average of that of neighbouring pixels. Its unit is that of the DEM (typically meters) and it can be
 computed for any window size (default 3x3 pixels).
 
-.. image:: auto_examples/images/sphx_glr_plot_terrain_attributes_007.png
+.. image:: basic_examples/images/sphx_glr_plot_terrain_attributes_007.png
   :width: 600
 
 .. minigallery:: xdem.terrain.topographic_position_index
@@ -147,7 +147,7 @@ neighbouring pixels.
 For bathymetry, the method of `Wilson et al. (2007) <http://dx.doi.org/10.1080/01490410701295962>`_ is generally used,
 where the TRI is defined by the mean absolute difference with neighbouring pixels
 
-.. image:: auto_examples/images/sphx_glr_plot_terrain_attributes_008.png
+.. image:: basic_examples/images/sphx_glr_plot_terrain_attributes_008.png
   :width: 600
 
 .. minigallery:: xdem.terrain.terrain_ruggedness_index
@@ -161,7 +161,7 @@ The roughness is a metric of terrain ruggedness, based on the maximum difference
 The roughness is based on the method of `Dartnell (2000) <http://dx.doi.org/10.14358/PERS.70.9.
 1081>`_. Its unit is that of the DEM (typically meters) and it can be computed for any window size (default 3x3 pixels).
 
-.. image:: auto_examples/images/sphx_glr_plot_terrain_attributes_009.png
+.. image:: basic_examples/images/sphx_glr_plot_terrain_attributes_009.png
   :width: 600
 
 .. minigallery:: xdem.terrain.roughness
@@ -175,7 +175,7 @@ The rugosity is a metric of terrain ruggedness, based on the ratio between plani
 rugosity is based on the method of `Jenness (2004) <https://doi.org/10.2193/0091-7648(2004)032[0829:CLSAFD]2.0.CO;2>`_.
 It is unitless, and is only supported for a 3x3 window size.
 
-.. image:: auto_examples/images/sphx_glr_plot_terrain_attributes_010.png
+.. image:: basic_examples/images/sphx_glr_plot_terrain_attributes_010.png
   :width: 600
 
 .. minigallery:: xdem.terrain.rugosity
@@ -191,7 +191,7 @@ The fractal roughness is computed by estimating the fractal dimension in 3D spac
 DEM pixels. Its unit is that of a dimension, and is always between 1 (dimension of a line in 3D space) and 3
 (dimension of a cube in 3D space). It can only be computed on window sizes larger than 5x5 pixels, and defaults to 13x13.
 
-.. image:: auto_examples/images/sphx_glr_plot_terrain_attributes_011.png
+.. image:: basic_examples/images/sphx_glr_plot_terrain_attributes_011.png
   :width: 600
 
 .. minigallery:: xdem.terrain.fractal_roughness

examples/advanced/README.rst

@@ -0,0 +1,2 @@
+Advanced
+========

examples/plot_blockwise_coreg.py → examples/advanced/plot_blockwise_coreg.py

@@ -3,7 +3,7 @@
 ========================
 
 Often, biases are spatially variable, and a "global" shift may not be enough to coregister a DEM properly.
-In the :ref:`sphx_glr_auto_examples_plot_nuth_kaab.py` example, we saw that the method improved the alignment significantly, but there were still possibly nonlinear artefacts in the result.
+In the :ref:`sphx_glr_basic_examples_plot_nuth_kaab.py` example, we saw that the method improved the alignment significantly, but there were still possibly nonlinear artefacts in the result.
 Clearly, nonlinear coregistration approaches are needed.
 One solution is :class:`xdem.coreg.BlockwiseCoreg`, a helper to run any ``Coreg`` class over an arbitrarily small grid, and then "puppet warp" the DEM to fit the reference best.
 

examples/plot_heterosc_estimation_modelling.py → examples/advanced/plot_heterosc_estimation_modelling.py

@@ -26,15 +26,15 @@
 
 # %%
 # Here, we detail the steps used by ``xdem.spatialstats.infer_heteroscedasticity_from_stable`` exemplified in
-# :ref:`sphx_glr_auto_examples_plot_infer_heterosc.py`. First, we load example files and create a glacier mask.
+# :ref:`sphx_glr_basic_examples_plot_infer_heterosc.py`. First, we load example files and create a glacier mask.
 
 ref_dem = xdem.DEM(xdem.examples.get_path("longyearbyen_ref_dem"))
 dh = xdem.DEM(xdem.examples.get_path("longyearbyen_ddem"))
 glacier_outlines = gu.Vector(xdem.examples.get_path("longyearbyen_glacier_outlines"))
 mask_glacier = glacier_outlines.create_mask(dh).squeeze()
 
 # %%
-# We derive terrain attributes from the reference DEM (see :ref:`sphx_glr_auto_examples_plot_terrain_attributes.py`),
+# We derive terrain attributes from the reference DEM (see :ref:`sphx_glr_basic_examples_plot_terrain_attributes.py`),
 # which we will use to explore the variability in elevation error.
 slope, aspect, planc, profc = \
     xdem.terrain.get_terrain_attribute(dem=ref_dem,

examples/plot_slope_methods.py → examples/advanced/plot_slope_methods.py

@@ -6,7 +6,7 @@
 Here is an example of how to generate the two with each method, and understand their differences.
 
 For more information, see the :ref:`terrain_attributes` chapter and the
-:ref:`sphx_glr_auto_examples_plot_terrain_attributes.py` example.
+:ref:`sphx_glr_basic_examples_plot_terrain_attributes.py` example.
 """
 import matplotlib.pyplot as plt
 import numpy as np

examples/plot_standardization.py → examples/advanced/plot_standardization.py

@@ -8,8 +8,8 @@
 precision on other types of terrain and reliably use spatial statistics (see :ref:`spatialstats`).
 
 Here, we show an example of standardization of the data based on terrain-dependent explanatory variables
-(see :ref:`sphx_glr_auto_examples_plot_infer_heterosc.py`) and combine it with an analysis of spatial correlation
-(see :ref:`sphx_glr_auto_examples_plot_infer_spatial_correlation.py`) .
+(see :ref:`sphx_glr_basic_examples_plot_infer_heterosc.py`) and combine it with an analysis of spatial correlation
+(see :ref:`sphx_glr_basic_examples_plot_infer_spatial_correlation.py`) .
 
 **Reference**: `Hugonnet et al. (2022) <https://doi.org/10.1109/jstars.2022.3188922>`_, Equation 12.
 """
@@ -22,7 +22,7 @@
 
 # %%
 # We start by estimating the elevation heteroscedasticity and deriving a terrain-dependent measurement error as a function of both
-# slope and maximum curvature, as shown in the :ref:`sphx_glr_auto_examples_plot_infer_heterosc.py` example.
+# slope and maximum curvature, as shown in the :ref:`sphx_glr_basic_examples_plot_infer_heterosc.py` example.
 
 # Load the data
 ref_dem = xdem.DEM(xdem.examples.get_path("longyearbyen_ref_dem"))
@@ -102,7 +102,7 @@
 plt.show()
 
 # %%
-# Now, we can perform an analysis of spatial correlation as shown in the :ref:`sphx_glr_auto_examples_plot_variogram_estimation_modelling.py`
+# Now, we can perform an analysis of spatial correlation as shown in the :ref:`sphx_glr_advanced_examples_plot_variogram_estimation_modelling.py`
 # example, by estimating a variogram and fitting a sum of two models.
 df_vgm = xdem.spatialstats.sample_empirical_variogram(values=z_dh.data.squeeze(), gsd=dh.res[0], subsample=300,
                                                       n_variograms=10, random_state=42)

examples/basic/README.rst

@@ -0,0 +1,2 @@
+Basic
+=====

examples/plot_infer_heterosc.py → examples/basic/plot_infer_heterosc.py

@@ -16,7 +16,7 @@
 
 # %%
 # We load a difference of DEMs at Longyearbyen, already coregistered using :ref:`coregistration_nuthkaab` as shown in
-# the :ref:`sphx_glr_auto_examples_plot_nuth_kaab.py` example. We also load the reference DEM to derive terrain
+# the :ref:`sphx_glr_basic_examples_plot_nuth_kaab.py` example. We also load the reference DEM to derive terrain
 # attributes and the glacier outlines here corresponding to moving terrain.
 dh = xdem.DEM(xdem.examples.get_path("longyearbyen_ddem"))
 ref_dem = xdem.DEM(xdem.examples.get_path("longyearbyen_ref_dem"))
@@ -52,4 +52,4 @@
 # This pipeline will not always work optimally with default parameters: spread estimates can be affected by skewed
 # distributions, the binning by extreme range of values, some DEMs do not have any error variability with terrain (e.g.,
 # terrestrial photogrammetry). **To learn how to tune more parameters and use the subfunctions, see the gallery example:**
-# :ref:`sphx_glr_auto_examples_plot_heterosc_estimation_modelling.py`!
+# :ref:`sphx_glr_advanced_examples_plot_heterosc_estimation_modelling.py`!

examples/plot_infer_spatial_correlation.py → examples/basic/plot_infer_spatial_correlation.py

@@ -14,7 +14,7 @@
 
 # %%
 # We load a difference of DEMs at Longyearbyen, already coregistered using :ref:`coregistration_nuthkaab` as shown in
-# the :ref:`sphx_glr_auto_examples_plot_nuth_kaab.py` example. We also load the glacier outlines here corresponding to
+# the :ref:`sphx_glr_basic_examples_plot_nuth_kaab.py` example. We also load the glacier outlines here corresponding to
 # moving terrain.
 dh = xdem.DEM(xdem.examples.get_path("longyearbyen_ddem"))
 glacier_outlines = gu.Vector(xdem.examples.get_path("longyearbyen_glacier_outlines"))
@@ -59,4 +59,4 @@
 # This pipeline will not always work optimally with default parameters: variogram sampling is more robust with a lot of
 # samples but takes long computing times, and the fitting might require multiple tries for forms and possibly bounds
 # and first guesses to help the least-squares optimization. **To learn how to tune more parameters and use the
-# subfunctions, see the gallery example:** :ref:`sphx_glr_auto_examples_plot_variogram_estimation_modelling.py`!
+# subfunctions, see the gallery example:** :ref:`sphx_glr_advanced_examples_plot_variogram_estimation_modelling.py`!

examples/plot_nuth_kaab.py → examples/basic/plot_nuth_kaab.py

@@ -60,4 +60,4 @@
 # %%
 # In the plot above, one may notice a positive (blue) tendency toward the east.
 # The 1990 DEM is a mosaic, and likely has a "seam" near there.
-# :ref:`sphx_glr_auto_examples_plot_blockwise_coreg.py` tackles this issue, using a nonlinear coregistration approach.
+# :ref:`sphx_glr_advanced_examples_plot_blockwise_coreg.py` tackles this issue, using a nonlinear coregistration approach.

examples/plot_spatial_error_propagation.py → examples/basic/plot_spatial_error_propagation.py

@@ -18,7 +18,7 @@
 
 # %%
 # We load the same data, and perform the same calculations on heteroscedasticity and spatial correlations of errors as
-# in the :ref:`sphx_glr_auto_examples_plot_infer_heterosc.py` and :ref:`sphx_glr_auto_examples_plot_infer_spatial_correlation.py`
+# in the :ref:`sphx_glr_basic_examples_plot_infer_heterosc.py` and :ref:`sphx_glr_basic_examples_plot_infer_spatial_correlation.py`
 # examples.
 
 dh = xdem.DEM(xdem.examples.get_path("longyearbyen_ddem"))

examples/plot_terrain_attributes.py → examples/basic/plot_terrain_attributes.py

@@ -6,7 +6,7 @@
 Here is an example of how to generate these products.
 
 For more information, see the :ref:`terrain_attributes` chapter and the
-:ref:`sphx_glr_auto_examples_plot_slope_methods.py` example.
+:ref:`sphx_glr_advanced_examples_plot_slope_methods.py` example.
 """
 # sphinx_gallery_thumbnail_number = 12
 import matplotlib.pyplot as plt

xdem/examples.py

@@ -12,7 +12,7 @@
 import geoutils as gu
 import xdem
 
-EXAMPLES_DIRECTORY = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "examples"))
+EXAMPLES_DIRECTORY = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "examples/data"))
 # Absolute filepaths to the example files.
 FILEPATHS_DATA = {
     "longyearbyen_ref_dem": os.path.join(EXAMPLES_DIRECTORY, "Longyearbyen","data","DEM_2009_ref.tif"),