Last changes

doc/source/background.md

@@ -2,7 +2,29 @@
 
 # Background
 
-Below, some more information on xDEM's mission and the people behind the package.
+Below, some more information on the people behind the package, and its mission.
+
+## The people behind xDEM
+
+```{margin}
+<sup>2</sup>More on our GlacioHack founder at [adehecq.github.io](https://adehecq.github.io/)!
+```
+
+xDEM was created during the **[GlacioHack](https://github.com/GlacioHack) hackathon**, that was initiated by
+Amaury Dehecq<sup>2</sup> and took place online on November 8, 2020.
+
+```{margin}
+<sup>3</sup>Check-out [glaciology.ch](https://glaciology.ch) on our founding group of VAW glaciology!
+```
+
+The initial core development of xDEM was performed by members of the Glaciology group of the Laboratory of Hydraulics, Hydrology and
+Glaciology (VAW) at ETH Zürich<sup>3</sup>, with contributions by members of the University of Oslo, the University of Washington, and University
+Grenoble Alpes.
+
+We are not software developers but geoscientists, and we try our best to offer tools that can be useful to a larger group,
+documented, reliable and maintained. All development and maintenance is made on a voluntary basis and we welcome
+any new contributors! See some information on how to contribute in the dedicated page of our
+[GitHub repository](https://github.com/GlacioHack/xdem/blob/main/CONTRIBUTING.md).
 
 ## Mission
 
@@ -42,25 +64,3 @@ And finally:
 
 - **Open-source:** all code should be accessible and re-usable to anyone in the community, for transparency and open governance.
 
-
-## The people behind xDEM
-
-```{margin}
-<sup>2</sup>More on our GlacioHack founder at [adehecq.github.io](https://adehecq.github.io/)!
-```
-
-xDEM was created during the **[GlacioHack](https://github.com/GlacioHack) hackathon**, that was initiated by
-Amaury Dehecq<sup>2</sup> and took place online on November 8, 2020.
-
-```{margin}
-<sup>3</sup>Check-out [glaciology.ch](https://glaciology.ch) on our founding group of VAW glaciology!
-```
-
-The initial core development of xDEM was performed by members of the Glaciology group of the Laboratory of Hydraulics, Hydrology and
-Glaciology (VAW) at ETH Zürich<sup>3</sup>, with contributions by members of the University of Oslo, the University of Washington, and University
-Grenoble Alpes.
-
-We are not software developers but geoscientists, and we try our best to offer tools that can be useful to a larger group,
-documented, reliable and maintained. All development and maintenance is made on a voluntary basis and we welcome
-any new contributors! See some information on how to contribute in the dedicated page of our
-[GitHub repository](https://github.com/GlacioHack/xdem/blob/main/CONTRIBUTING.md).

doc/source/biascorr.md

@@ -212,55 +212,10 @@ _ = ax[1].set_yticklabels([])
 - **Performs:** Correct biases along a direction.
 - **Supports weights:** Yes.
 - **Pros:** Correcting undulations or jitter, common in both stereo and radar DEMs, or strips common in scanned imagery.
-- **Cons:** Long optimization for a sum of sinusoids.
-
-The default optimizer for directional biases fits a sum of sinusoids using 1 to 3 different frequencies and
-keeps the best performing fit, which is useful for periodic along-track errors common to DEMs.
-
-```{code-cell} ipython3
-:tags: [hide-cell]
-:mystnb:
-:  code_prompt_show: "Show the code for adding a sum of sinusoids bias"
-:  code_prompt_hide: "Hide the code for adding a sum of sinusoids bias"
-
-# Get rotated coordinates along an angle
-angle = 20
-xx = gu.raster.get_xy_rotated(ref_dem, along_track_angle=angle)[0]
-
-# One sinusoid: amplitude, phases and frequencies
-params = np.array([(15, 10000, np.pi)]).flatten()
-
-# Create a sinusoidal bias and add to the DEM
-from xdem.fit import sumsin_1d
-synthetic_bias = sumsin_1d(xx.flatten(), *params).reshape(np.shape(ref_dem.data))
-tbc_dem_sumsin = ref_dem + synthetic_bias
-```
-
-
-```{code-cell} ipython3
-# 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
-corrected_dem = dirbias.fit_and_apply(ref_dem, tbc_dem_sumsin, random_state=42)
-```
-
-```{code-cell} ipython3
-:tags: [hide-input]
-:mystnb:
-:  code_prompt_show: "Show plotting code"
-:  code_prompt_hide: "Hide plotting code"
-
-# Plot before and after
-f, ax = plt.subplots(1, 2)
-ax[0].set_title("Before directional\nde-biasing")
-(tbc_dem_sumsin - ref_dem).plot(cmap='RdYlBu', vmin=-30, vmax=30, ax=ax[0])
-ax[1].set_title("After directional\nde-biasing")
-(corrected_dem - ref_dem).plot(cmap='RdYlBu', vmin=-30, vmax=30, ax=ax[1], cbar_title="Elevation differences (m)")
-_ = ax[1].set_yticklabels([])
-```
+- **Cons:** Long optimization when fitting a sum of sinusoids.
 
 For strip-like errors, performing an empirical correction using only a binning with `fit_or_bin="bin"` allows more
-flexibility, but requires a larger amount of static surfaces.
+flexibility than a parametric form, but requires a large amount of static surfaces.
 
 ```{code-cell} ipython3
 :tags: [hide-cell]

doc/source/index.md

@@ -135,6 +135,7 @@ advanced_examples/index.rst
 
 api
 config
+release_notes
 publis
 background
 ```

doc/source/release_notes.md

@@ -0,0 +1,74 @@
+# Release notes
+
+Below, the release notes for all minor versions and our roadmap to a first major version.
+
+## 0.1.0
+
+xDEM 0.1.0 is the **first minor release** since the creation of the project in 2020. It is the result of years of work 
+to consolidate and re-structure features into a mature and stable API to minimize future breaking changes. 
+
+**All the core features drafted at the start of the project are now supported**, and there is a **clear roadmap 
+towards a first major release 1.0**. This minor release also adds many tests and improves significantly the documentation 
+from the early-development state of the package. 
+
+The re-structuring created some breaking changes, though minor.
+
+See details below, including **a guide to help migrate code from early-development versions**.
+
+### Features
+
+xDEM now gathers the following core features:
+- **Elevation data objects** core to quantatiative analysis, which are DEMs and elevation point clouds,
+- **Vertical referencing** including automatic 3D CRS fetching, 
+- **Terrain analysis** for many attributes, 
+- **Coregistration** with the choice of several methods, including modular pipeline building, 
+- **Bias corrections** for any variable, also modular and supported by pipelines, 
+- **Uncertainty analysis** based on several robust methods.
+
+Recent additions include in particular **point-raster support for coregistration**, and the **expansion of 
+`DEM` class methods** to cover all features of the package, with for instance `DEM.coregister_3d()` or `DEM.slope()`.
+
+### Guides and other resources
+
+xDEM integrates **background material on quantitative analysis of elevation data** to help users use the various methods 
+of the package. This material includes **several illustrated guide pages**, **a cheatsheet** on how to recognize and correct 
+typical elevation errors, and more.
+
+### Future deprecations
+
+We have added warnings throughout the documentation and API related to planned deprecations:
+- **Gap-filling features specific to glacier-applications** will be moved to a separate package,
+- **Uncertainty analysis tools related to variography** will change API to rely on SciKit-GStat variogram objects,
+- The **dDEM** and **DEMCollection** classes will likely be refactored or removed.
+
+Changes related to **gap-filling** and **uncertainty analysis** will have deprecation warnings, while the function 
+remain available during a few more releases.
+
+### Migrate from early versions
+
+The following changes **might be required to solve breaking changes**, depending on your early-development version:
+- Rename `.show()` to `.plot()` for all data objects,
+- Rename `.dtypes` to `dtype` for `DEM` objects,
+- Operations `.crop()`, `shift()` and `to_vcrs()` are not done in-place by default anymore, replace by `dem = dem.crop()` or `dem.crop(..., inplace=True)` to mirror the old default behaviour, 
+- Rename `.shift()` to `.translate()` for `DEM` objects,
+- Several function arguments are renamed, in particular `dst_xxx` arguments of `.reproject()` are all renamed to `xxx` e.g. `dst_crs` to `crs`, as well as the arguments of `Coreg.fit()` renamed from `xxx_dem` to `xxx_elev` to be generic to any elevation data,
+- All `BiasCorr1D`, `BiasCorr2D` and `BiasCorrND` classes are removed in favor of a single `BiasCorr` class that implicitly understands the number of dimensions from the length of input `bias_vars`,
+- New user warnings are sometimes raised, in particular if some metadata is not properly defined such as `.nodata`. Those should give an indication as how to silence them.
+
+Additionally, **some important yet non-breaking changes**:
+- The sequential use of `Coreg.fit()` and `Coreg.apply()` to the same `tba_elev` is now discouraged and updated everywhere in the documentation, use `Coreg.fit_and_apply()` or `DEM.coregister_3d()` instead,
+- The use of a separate module for terrain attributes such as `xdem.terrain.slope()` is now discouraged, use `DEM.slope()` instead.
+
+## Roadmap to 1.0
+
+Based on recent and ongoing progress, we envision the following roadmap.
+
+**Releases of 0.2, 0.3, 0.4, etc**, for the following planned (ongoing) additions:
+- The **addition of an elevation point cloud `EPC` data object**, inherited from the ongoing `PointCloud` object of GeoUtils alongside many features at the interface of point and raster,
+- The **addition of an Xarray accessor `dem`** mirroring the `DEM` object, to work natively with Xarray objects and add support on out-of-memory Dask operations for most of xDEM's features,
+- The **addition of an GeoPandas accessor `epc`** mirroring the `EPC` object, to work natively with GeoPandas objects,
+- The **re-structuration of uncertainty analysis features** to rely directly on SciKit-GStat's `Variogram` object.
+
+**Release of 1.0** once all these additions are fully implemented, and after feedback from the community.
+
+

doc/source/terrain.md

@@ -23,9 +23,7 @@ and tested for consistency against [gdaldem](https://gdal.org/programs/gdaldem.h
 
 ## Quick use
 
-Terrain attribute methods can either be called directly from a {class}`~xdem.DEM` (e.g., {func}`xdem.DEM.slope`) or
-through the {class}`~xdem.terrain` module (e.g., {func}`xdem.terrain.slope`) which allows a NumPy array input but
-requires additional metadata.
+Terrain attribute methods can be derived directly from a {class}`~xdem.DEM`, using for instance {func}`xdem.DEM.slope`.
 
 ```{code-cell} ipython3
 :tags: [remove-cell]

xdem/coreg/affine.py

@@ -770,7 +770,7 @@ def to_matrix(self) -> NDArrayf:
 
     def to_translations(self) -> tuple[float, float, float]:
         """
-        Convert the affine transformation matrix to only its X/Y/Z translations.
+        Extract X/Y/Z translations from the affine transformation matrix.
 
         :return: Easting, northing and vertical translations (in georeferenced unit).
         """
@@ -784,7 +784,9 @@ def to_translations(self) -> tuple[float, float, float]:
 
     def to_rotations(self) -> tuple[float, float, float]:
         """
-        Convert the affine transformation to its X/Y/Z euler rotations, extrinsic convention.
+        Extract X/Y/Z euler rotations (extrinsic convention) from the affine transformation matrix.
+
+        Warning: This function only works for a rigid transformation (rotation and translation).
 
         :return: Extrinsinc Euler rotations along easting, northing and vertical directions (degrees).
         """