Fix downloading of vertical CRS on Readthedocs and re-order Credits s…

…ection (#666)

doc/source/authors.md

@@ -1,40 +1,27 @@
----
-file_format: mystnb
-jupytext:
-  formats: md:myst
-  text_representation:
-    extension: .md
-    format_name: myst
-kernelspec:
-  display_name: xdem-env
-  language: python
-  name: xdem
----
 (authors)=
-
-# Credits
+## Authors
 
 © 2024 **xDEM developers**.
 
-**xDEM** is licensed under permissive Apache 2 license (See [LICENSE file](license.md)).
+**xDEM** is licensed under permissive Apache 2 license (See [LICENSE file](license.md) or below).
 
 All contributors listed in this document are part of the **xDEM developers**, and their
 contributions are subject to the project's copyright under the terms of the
 [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0).
 
-This file keeps track of authors contributions.
+This section keeps track of authors contributions.
 
 ---
 
-## Development Lead
+### Development lead
 
 - **Romain Hugonnet** [@rhugonnet](https://github.com/rhugonnet) <[email protected]>
 - **Amaury Dehecq** [@adehecq](https://github/adehecq) <[email protected]>
 - **Erik Schytt Mannerfelt** [@erikmannerfelt](https://github/erikmannerfelt)
 
 ---
 
-## Contributors
+### Contributors
 
 
 - **Friedrich Knuth** [@friedrichknuth](https://github/friedrichknuth)
@@ -52,11 +39,9 @@ This file keeps track of authors contributions.
 - **Amelie Froessl** [@ameliefroessl](https://github.com/ameliefroessl)
 - **Simon Gascoin** [@sgascoin](https://github.com/sgascoin)
 
-Update here with new contributors.
-
 ---
 
-## Original Developers/Designers/Supporters
+### Original developers
 
 - **Romain Hugonnet** [@rhugonnet](https://github.com/rhugonnet) <[email protected]>
 - **Amaury Dehecq** [@adehecq](https://github/adehecq) <[email protected]>

doc/source/biascorr.md

@@ -26,6 +26,24 @@ passed any external variables (e.g., land cover type, processing metric) to atte
 Still, many methods rely either on coordinates (e.g., deramping, along-track corrections) or terrain
 (e.g., curvature- or elevation-dependant corrections), derived solely from the elevation data.
 
+```{code-cell} ipython3
+:tags: [remove-cell]
+
+#################################################################################
+# This a temporary trick to allow vertical referencing to work in other notebooks
+#################################################################################
+# Somehow, only on Readthedocs (locally works fine), the first notebook to run (in alphabetical order) fails
+# to download from PROJ... while all other notebook render normally.
+# The first alphabetical notebook is "biascorr", so adding this trick here
+
+import xdem
+dem = xdem.DEM(xdem.examples.get_path("longyearbyen_ref_dem"))
+# Define the vertical CRS as the 3D ellipsoid of the 2D CRS
+dem.set_vcrs("Ellipsoid")
+# Transform to the EGM96 geoid
+dem.to_vcrs("EGM96")
+```
+
 ## Quick use
 
 Bias-correction methods are **used the same way as coregistrations**:

doc/source/cheatsheet.md

@@ -25,7 +25,7 @@ identify on **a map of elevation differences with another elevation dataset (loo
 ## Cheatsheet
 
 The patterns of errors categories listed in this spreadsheet **are linked to visual examples further below** that
-you use to compare to your own elevation differences.
+you can use to compare to your own elevation differences.
 
 ```{list-table}
    :widths: 1 2 2 2
@@ -40,6 +40,10 @@ you use to compare to your own elevation differences.
      - Positive and negative errors that are larger near high slopes and symmetric with opposite slope orientation, 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 can be visually identified! To not confuse with {ref}`peak-cavity`.
+   * - {ref}`peak-cavity`
+     - Positive and negative errors, with one sign located exclusively near peaks and the other exclusively near cavities.
+     - Likely resolution-type errors, use a {ref}`biascorr` such as {class}`~xdem.coreg.TerrainBias`.
+     - Can be over-corrected, sometimes better to simply ignore during analysis. Or avoid by downsampling all elevation data to the lowest resolution, rather than upsampling to the highest.
    * - {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`.
@@ -52,10 +56,6 @@ you use to compare to your own elevation differences.
      - Positive and negative errors undulating patterns at one or several frequencies well larger than pixel size.
      - Likely jitter-type errors, use a {ref}`biascorr` such as {class}`~xdem.coreg.DirectionalBias`.
      - Can sometimes be more rigorously fixed ahead of DEM generation with jitter correction.
-   * - {ref}`peak-cavity`
-     - Positive and negative errors, with one sign located exclusively near peaks and the other exclusively near cavities.
-     - Likely resolution-type errors, use a {ref}`biascorr` such as {class}`~xdem.coreg.TerrainBias`.
-     - Can be over-corrected, sometimes better to simply ignore during analysis. Or avoid by downsampling all elevation data to the lowest resolution, rather than upsampling to the highest.
    * - {ref}`point-alternating`
      - Point data errors that alternate between negative and positive, higher on steeper slopes.
      - 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) such as {func}`~xdem.DEM.interp_points`.
@@ -128,6 +128,27 @@ dh = dem - dem_shift.reproject(dem)
 dh.plot(cmap='RdYlBu', vmin=-3, vmax=3, cbar_title="Elevation differences of\nhorizontal shift (m)")
 ```
 
+(peak-cavity)=
+### Peak cuts and cavity fills
+
+Example of peak cutting and cavity filling errors. We here downsampled our DEM from 20 m to 100 m to simulate a lower
+native resolution, then upsample it again to 20 m, to show the errors affect areas near high curvatures such as
+peaks and cavities.
+
+```{code-cell} ipython3
+:tags: [hide-input]
+:mystnb:
+:  code_prompt_show: "Show code to simulate resolution errors"
+:  code_prompt_hide: "Hide code to simulate resolution errors"
+
+# Downsample DEM (bilinear)
+dem_100m = dem.reproject(res=100)
+
+# Upsample (bilinear again) and compare
+dh = dem - dem_100m.reproject(dem)
+dh.plot(cmap='RdYlBu', vmin=-40, vmax=40, cbar_title="Elevation differences of\nresolution change (m)")
+```
+
 (smooth-large-field)=
 ### Smooth-field offset
 
@@ -141,9 +162,9 @@ geoid added on top of the ellipsoid.
 :  code_prompt_hide: "Hide code to simulate vertical referencing errors"
 
 # Set current vertical CRS as ellipsoid
-dem.set_vcrs("Ellipsoid")
+dem.set_vcrs("EGM96")
 # Transform vertical reference to geoid
-trans_dem = dem.to_vcrs("EGM96")
+trans_dem = dem.to_vcrs("Ellipsoid")
 
 # Plot the elevation differences of the vertical transformation
 dh = dem - trans_dem
@@ -210,27 +231,6 @@ synthetic_bias = dem.copy(new_array=synthetic_bias_arr)
 synthetic_bias.plot(cmap='RdYlBu', vmin=-3, vmax=3, cbar_title="Elevation differences of\nundulations (m)")
 ```
 
-(peak-cavity)=
-### Peak cuts and cavity fills
-
-Example of peak cutting and cavity filling errors. We here downsampled our DEM from 20 m to 100 m to simulate a lower
-native resolution, then upsample it again to 20 m, to show the errors affect areas near high curvatures such as
-peaks and cavities.
-
-```{code-cell} ipython3
-:tags: [hide-input]
-:mystnb:
-:  code_prompt_show: "Show code to simulate resolution errors"
-:  code_prompt_hide: "Hide code to simulate resolution errors"
-
-# Downsample DEM (bilinear)
-dem_100m = dem.reproject(res=100)
-
-# Upsample (bilinear again) and compare
-dh = dem - dem_100m.reproject(dem)
-dh.plot(cmap='RdYlBu', vmin=-40, vmax=40, cbar_title="Elevation differences of\nresolution change (m)")
-```
-
 (point-alternating)=
 ### Point alternating
 

doc/source/conf.py

@@ -27,7 +27,7 @@
 
 project = "xDEM"
 copyright = "2024, xDEM developers"
-author = "Erik Mannerfelt, Romain Hugonnet, Amaury Dehecq and others"
+author = "Romain Hugonnet, Erik Mannerfelt, Amaury Dehecq and others"
 
 # The full version, including alpha/beta/rc tags
 release = xdem.__version__
@@ -177,7 +177,7 @@ 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>. ⚠️'
+        "to update your code see the release notes. ⚠️"
     ),
 }
 

doc/source/credits.md

@@ -0,0 +1,12 @@
+(credits)=
+# Credits and background
+
+```{toctree}
+:maxdepth: 2
+
+history
+mission
+authors
+funding
+license
+```