Add match_station_basin function to identify unique basins for GloFAS stations

[jmargutt]

AB#41554

WIP: will be picked up again later.

Describe your changes

Adds match_station_basin() to data/shared/ to map each GloFAS station to the coarsest HydroBASINS level where it is the only station from its country. Intended for use by flood-hazard-logic to determine exposed administrative divisions.

Key implementation details:

• Iterates HydroBASINS levels 4–12; for each level, spatial-joins stations to basins and counts co-located same-country stations
• Selects the coarsest (largest) basin where a station is alone (n_same_country == 1) and basin area ≤ max_basin_area_km2
• Returns a GeoDataFrame keyed by stationCode with basin geometry, HYBAS_ID, and basin_level

CRS safety (addressed in review):

• Raises ValueError early if stations_gdf.crs is None — prevents silent failure when reprojecting basins to match station CRS
• Raises ValueError per basin level if a loaded shapefile has no CRS metadata, including the matched filename for easy diagnosis

# stations_gdf must have a CRS set
if stations_crs is None:
    raise ValueError(
        "stations_gdf must have a CRS set. "
        "Assign a CRS with stations_gdf.set_crs(...) before calling this function."
    )
# each basin shapefile must also carry CRS metadata
if gdf.crs is None:
    raise ValueError(
        f"Basin shapefile for level {level} is missing CRS metadata: {filenames}"
    )

Checklist before requesting a code review

• I have performed a self-review of my code
• I have addressed all Copilot comments
• I have asked the design team to review these changes, or: The changes do not touch the UI/UX
• I have added tests for my changes, or: Adding tests is unnecessary/irrelevant
• I have made sure that all automated checks pass before requesting a review
• I have updated all documentation where necessary
• I do not need any deviation from our PR guidelines

Portal preview-deployment

This PR does not have any preview deployments yet.

[Copilot]

Pull request overview

Adds a new shared geospatial utility to map each GloFAS station to a “unique” HydroBASINS basin (coarsest level where the station is the only one from that country), intended to support flood hazard exposure/admin-division selection logic.

Changes:

• Introduces match_station_basin() to compute per-station basin assignment across HydroBASINS levels (4–12).
• Adds helpers to load basin shapefiles from disk and compute “coarsest unique basin” via spatial joins + per-basin station counts.
• Returns a GeoDataFrame keyed by stationCode with basin geometry, HYBAS_ID, and selected basin_level.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 7 comments.

[Copilot]

If stations_gdf has no CRS set (stations_gdf.crs is None), the basin reprojection step will call GeoDataFrame.to_crs(None) and raise. Add an explicit validation/exception for missing station CRS (or require an explicit CRS parameter) before reprojecting basins.

[jmargutt]

@copilot apply changes based on this feedback

[Copilot]

Done in commit 2647331. Added:

• An explicit check that raises ValueError when stations_gdf.crs is None, before the reprojection loop.
• Per-level basin CRS validation inside the reprojection loop: if a loaded basin GeoDataFrame has no CRS, a ValueError is raised with the matching filename(s) to make the failure easy to diagnose.

[Copilot]

_load_basins_from_path() uses glob and silently picks matches[0]. If basins_dir contains multiple HydroBASINS files per level (e.g., multiple regions/continents), this becomes non-deterministic and can select the wrong shapefile. Consider sorting matches and either (a) erroring when len(matches)!=1 or (b) reading all matches and concatenating into one GeoDataFrame for that level.

[jmargutt]

@copilot apply changes based on this feedback