Handling a ROI when loading dem, add stats documentation

[vschaffn]

Resolves #602.
Completes GlacioHack/geoutils#642.
Completes GlacioHack/geoutils#638.

Description

This PR introduces the ability to use a Region of Interest (ROI) when working with xdem.DEM, which is a subclass of geoutils.Raster. This functionality allows users to focus on specific regions within the raster data without having to load or process the entire dataset. The ROI can be specified during the instantiation of a DEM object, or used during array creation. This enhancement builds on the existing ROI functionality in the Raster class and integrates it seamlessly into DEM workflows.

Changes

1. DEM class Enhancement:

• The DEM constructor now accepts an optional roi parameter. This allows users to define a specific region within the DEM to work on, reducing memory usage and improving performance when processing large datasets.
• If a roi is specified, the constructor will crop the loaded DEM to the defined region, using the same approach as geoutils.Raster.

2. Modifications in from_array():

• The from_array() method has been updated to include the optional roi parameter, which can be passed to crop the data array to a specific region before instantiating the raster object.

Documentation

• A section about statistics has been added to the DEM class documentation.
• A section about the ROI has been added to the DEM class documentation.

Example

1. Statistics:

• Get all statistics in a dict:

dem.get_stats()

• Get a single statistic (e.g., 'mean') as a float:

dem.get_stats("mean")

• Get multiple statistics in a dict:

dem.get_stats(["mean", "max", "rmse"])

• Using a custom callable statistic:

def custom_stat(data):
    return np.nansum(data > 100)  # Count the number of pixels above 100
dem.get_stats(custom_stat)

Note: as get_stats() is a raster method, it can also be used for terrain attributes:

dem.slope().get_stats()

2. ROI:

# Initialize a DEM with a pixel-based ROI
dem = xdem.DEM(filename_dem, roi={'x': 50, 'y': 100, 'w': 400, 'h': 300})
# Initialize a DEM with a georeferenced ROI
dem = xdem.DEM(filename_dem, roi={'left': 503810, 'bottom': 8666030, 'top': 8672030, 'right': 511810, 'crs': 'EPSG:25833'})

Note

• This PR has to be merged after the next release of geoutils containing Handling a ROI when loading raster data geoutils#642, Adding statistics to Raster geoutils#638.
• The geoutils version in the virtual environment configuration files (environment.yml, dev-environment.yml, ...) would have to be updated.

[vschaffn]

Tests with the correct geoutils version with ROI: