Add possibility to have a raster path_to_mask in Workflows config file

[marinebcht]

Resolves #954

Workflow accuracy and topo now accept raster path_to_mask, no matter its projection/footprint :

inputs:
  reference_elev:
    path_to_elev: "longyearbyen_ref_dem"
    path_to_mask: "path/mask.tif"
  to_be_aligned_elev:
    path_to_elev: "longyearbyen_tba_dem"
  sampling_grid: reference_elev

inputs:
  - path_to_elev: "longyearbyen_ref_dem"
    path_to_mask: "path/mask.tif"

Nan values in the mask

Nan value are translated by False : see here. For example, in the glacier mask case: NaN (no data before or after reprojection) values are not conidarated as Glacier.

Operation

This mask is :

1. read as Raster
2. translated as boolean (0 is False, !=0 is True)
3. filled with False
4. reprojected in the corresponding dem projection

[marinebcht]

@belletva raster path_to_mask must it necessarily be a boolean or are int+ rasters accepted?

[marinebcht]

Some thoughts :

• A) shapefile -> create_mask(dem) -> raster with true : pink, false: black

• B) from this raster, inlier mask used mask in terrain/coreg become true : black, pink: white -> black is the values needed to be masked

To use raster as mask we need to provide a tiff as the input of (A) :

• True = glacier = to be masked
• False = to keep, whitch is prettry logical

Is the case where we have a mask smaller than the dem : the projection need to fit it gives nan values.
Nan values need to be considerate as values to keep (false) = there is no glaciers in it.

---

If mask not boolean => mask.astype(bool) (0 values = True, != 0 set False
If mask with nan => mask.data.filled(False)

[marinebcht]

Hi @rhugonnet, can you confirm the process presented above to translate a raster in a actual mask ? :) Thanks

[rhugonnet]

@marinebcht Seems good to me.
@adehecq Do you see other cases?

The only thing that comes to mind right now is that the reprojection step should probably be done BEFORE masking if the mask is derived from a continuous-value raster, such as elevation (e.g., elevation > 500 m and < 1000 m), but I don't think this applies to a user input for Workflows (where the mask is a file already on disk).
If the user wants a different resampling of their raster being used as mask, they need to do this themselves beforehand anyway.

Another question for the API and to facilitate workflow input is: Do we only accept a single type of mask file from users (0 + NaN = False, other = True), or do we also allow a tag "invert_mask" to use the binary opposite of the mask (whether it is from a raster or vector)?

[marinebcht]

@belletva @rhugonnet ready to review so :)

[rhugonnet]

We should be more specific on the error message, and maybe collect original errors to return them through this one, something like:

# Treat the mask according to its type (Vector or Raster)
try:
    mask = gu.Vector(mask_path)
    inlier_mask = ~mask.create_mask(dem)

except pyogrio.errors.DataSourceError as vector_error:
    try:
        inlier_mask = gu.Raster(mask_path).astype(bool)
        inlier_mask.data = inlier_mask.data.filled(False)
        inlier_mask = inlier_mask.reproject(dem, silent=True)

    except rasterio.errors.RasterioIOError as raster_error:
        errors = ExceptionGroup(
            f"Could not read {mask_path!r} as either a vector or raster mask.",
            [vector_error, raster_error],
        )
        raise ValueError(
            "You provided a 'path_to_mask' value that is not recognised as a mask."
        ) from errors

[marinebcht]

Thanks for introducing me to ExceptionGroup; I’ve just discovered it.
But what is the added value, as it is not the dependancies ?
PS1: Non-existent files also first raise an error during the schema validation step.
PS2: rasterio gives the reason above our "ValueError"

[rhugonnet]

The added value is that the errors are traced all the way back, instead of being interrupted by our own ValueError in xDEM.

Concretely: In case of an error, instead of just printing "ValueError in xdem.xxx: You provided a .... that is not recognized as a mask" and stopping there, it also prints "from RasterioIOError in rasterio.xxx: message". Most often, the "message" from Rasterio will be "GDAL could not recognize filename path_to_mask as a valid input...".
So the user knows all the underlying causes, and it's easier to debug.

Not sure I understood your point about "not in the dependencies": if related to ExceptionGroup, it is available in base Python! 😄

[rhugonnet]

Perfect, a few comments above.
I wondered: do we also need to update the documentation to specify how this behaves?

[marinebcht]

Thanks for introducing me to ExceptionGroup; I’ve just discovered it.
But what is the added value, as it is not the dependancies ?
PS1: Non-existent files also first raise an error during the schema validation step.
PS2: rasterio gives the reason above our "ValueError"

[marinebcht]

remove empty line

[marinebcht]

The renduring