Site Selection Workflow#

site_selection prepares a reviewed catalog of candidate catchments before regional-lab or simulation work. It selects or rejects basins, writes auditable criteria, and produces a static HTML review report. It does not expand sites into model recipes and it does not run groundwater solvers. Run it, like any other workflow mode, with hmp run.

Use it when the question is still upstream of modeling:

  • which gauged catchments should enter a regional campaign;

  • whether candidate outlets delineate plausible basins from the DEM;

  • which candidates fail blocking criteria such as station distance, record length, known influence, or area rules;

  • which selected sites should be exported into regional_lab_sites.csv.

Minimal structure#

[workflow]
mode = "site_selection"

[site_selection]
selection_id = "bretagne_hydrometry_50_500_small_v1"
output_root = "../outputs/bretagne_hydrometry_50_500_small_v1"

[site_selection.input]
mode = "hydrometry"
region_id = "Bretagne"

[site_selection.strategy]
principle = "observation_led"
profile = "gauged_downstream_station"
primary_observation_type = "flow_station"
candidate_mode = "station_outlets"

[site_selection.territory]
mode = "admin_regions"
country = "FR"
regions = ["Bretagne"]

[site_selection.dem]
source = "data"
request_extent = "outlets"
map_background_extent = "territory"

[hydrometry]
date_start = "2015-01-01"
date_end = "2025-01-01"

[[hydrometry.sources]]
source = "hubeau"
product = "QmnJ"
extent = "study_area"
require_observations = true
max_stations = 7

[data]
types = ["dem"]

[[data.dem.sources]]
source = "ign_geoplateforme_dem"
dataset = "bd-alti"
resolution_m = 25.0
file_format = "ASC"
regions = ["Bretagne"]

The DEM is deliberately declared under [data.dem] (see [data] DataManagersConfig), and stations under [hydrometry] (see [hydrometry] HydrometryConfig); the [site_selection] section itself is documented in [site_selection] SiteSelectionConfig. In hydrometry mode, the workflow loads the stations first. With site_selection.dem.request_extent = "outlets", it uses those projected station outlets to bound the DEM request before building flow products, delineating catchments, and handing the spatial artifacts to the selection/reporting layer.

Short-term profiles#

Two profiles are considered operational for the current site-selection work. They keep the configuration readable while leaving room for later multi-criteria extensions.

Profile

Use when

Required shape

area_only

The goal is to find DEM-delineated catchments around a target drainage area, without using observations as selection evidence.

principle = "criteria_crossing", primary_axes = ["area"], and a DEM-driven input such as site_selection.input.mode = "dem_area_light".

gauged_downstream_station

The goal is to select gauged catchments whose outlet is represented by a downstream flow station.

principle = "observation_led", primary_observation_type = "flow_station", and candidate_mode = "station_outlets".

Provider status#

The workflow separates provider loading from site-selection criteria. This is intentional: provider code lives under hydromodpy.data; the site_selection package consumes normalized layers, stations, outlets, and basins.

Theme

Available in site_selection now

Natural next providers

Dams and human influences

No direct ROE or BNPE provider is wired into site_selection yet. The current criterion consumes user-declared vector layers through [[site_selection.criteria.influence.layers]] and can mark major_dam_upstream, major_withdrawal_upstream, or major_regulated_reach. For gauged catchments, Hub’Eau hydrometry station metadata can also be used through the station_influence observation criterion; this is a station-quality filter, not a spatial proof that no upstream dam exists.

ROE for obstacles such as dams and weirs; BNPE or Hub’Eau withdrawals for water-abstraction pressure; local DREAL, DDT, SAGE, EPTB, or operator inventories when they are more complete locally.

Geology

site_selection can intersect configured geology polygon layers and report geology evidence. It does not yet automatically transform [data.geology] provider outputs into a site-selection criterion.

BRGM brgm_1m and brgm_50k already exist in the data package; BDLISA is a relevant later source when the question is hydrogeological units rather than geological formations.

DEM candidate generation

The dem_area_light mode generates area-driven candidate outlets and caps the number of DEM delineations before final selection.

A future network-aware generator could favor hydrologically meaningful outlets, reduce nested or near-duplicate basins, improve coastal behavior, and make large territories faster to review.

For hydrometry-led selections, station influence metadata can be made active without adding a separate dam layer:

[site_selection.criteria.observations.station_influence]
mode = "warning"
source = "hubeau_station_metadata"
unknown_policy = "neutral"

Use mode = "hard_reject" only when the campaign should exclude stations whose hydrometric metadata explicitly reports a local or general hydrologic influence through influence_locale_station or influence_generale_site. Unknown influence metadata is not rejected by default. Comment keyword matches are shown as warnings for review; they are not treated as hard-reject evidence.

Input modes#

site_selection has five explicit input modes. The first three are the stable day-to-day modes; the generated DEM modes are useful for area-driven or network-driven candidate discovery.

Mode

Use when

Main inputs

plan_only

The team needs to review strategy, territory, data needs, and outputs before loading observations or delineating basins.

[site_selection] only.

delineated_catchments

Candidate outlets or pre-normalized catchments already exist as a CSV, often from a fixture, frozen inventory, or previous provider query.

catchments_csv and optionally delineate_from_outlets = true.

hydrometry

Stations should be loaded directly through HydroModPy data managers, usually Hub’Eau hydrometry over a territory or explicit station list.

[hydrometry] plus [data.dem].

dem_area_light

The campaign should discover DEM-derived outlets around a target basin area, with a bounded number of delineations for fast review.

strategy.profile = "area_only", primary_axes = ["area"], [site_selection.dem_area_light] and [data.dem].

generated_candidates

The campaign should sample high-accumulation DEM/network cells before normal delineation and selection. This mode is experimental compared with the two short-term supported profiles.

outlets.candidate_mode = "network_sampling" plus [data.dem] or a custom DEM.

DEM and observations#

The workflow keeps data-provider access outside the spatial selection package:

  • DEM loading goes through hydromodpy.data.variables.dem and should be configured in [data.dem].

  • Hub’Eau station loading goes through the hydrometry data manager.

  • In hydrometry mode, request_extent = "outlets" limits the calculation DEM to the station envelope plus margin_km; the map background can still use a broader territory DEM.

  • French administrative regions are resolved to departments by the data layer.

  • Hub’Eau station coordinates are requested in WGS84 for provider queries, then projected to Lambert-93 for DEM delineation. When Hub’Eau exposes official Lambert-93 station coordinates, those are preferred.

For French regional examples, source = "ign_geoplateforme_dem" with dataset = "bd-alti" and resolution_m = 25 is the current operational default.

Outlet snapping#

Two snapping strategies are available:

Strategy

Behavior

dem_accumulation

Snap the candidate outlet directly to the DEM-derived accumulation raster within snap_dist_m.

bdtopage_then_dem

First project the outlet to BD Topage or a custom reference network, reject it if that reference line is too far, then apply the local DEM snap.

BD Topage is a technical reference for constraining outlet locations. It should not be displayed by default in the site-selection map: on regional DEM backgrounds it can be mistaken for the validated hydrographic network of the selected basins. The report should show the DEM, selected/rejected basins, station points, final outlets, and station-to-outlet displacement links.

Outputs#

Every executed selection run writes the audit core:

  • criteria_components.jsonl;

  • site_selection_decisions.csv;

  • site_selection_decisions.jsonl;

  • site_selection_evidence.jsonl when normalized evidence exists;

  • site_selection_manifest.json.

Additional outputs follow the configured switches:

  • selected_sites.csv when write_csv and write_selected are true;

  • rejected_sites.csv when write_csv and write_rejected are true;

  • regional_lab_sites.csv when write_regional_lab_csv is true;

  • selected/rejected outlet and basin GeoJSON files when write_geojson is true;

  • GeoPackage and GeoParquet layers when their corresponding switches are true.

Generated DEM modes also write candidate_generation.jsonl. When write_geojson is true, they write candidate_outlets.geojson and generated_dem_network.geojson as review artifacts.

When HTML reporting is enabled, the run also writes:

  • review/index.html as the main review entry point, with a per-block detail selector;

  • review/compact/index.html;

  • review/standard/index.html;

  • review/audit/index.html;

  • review/site_selection_map.png.

The manifest is the hand-off contract. The HTML report is derived from the manifest and its declared artifacts, so validation should target the manifest first. compact is a fast plausibility read, standard is the default scientific review, and audit exposes provenance, detailed criteria tables, and artifact links. The main review/index.html page lets each block choose its own level.

Examples#

The example project contains short cases for the two supported short-term profiles, plus broader regional previews:

hmp run examples/projects/17_site_selection_workflow/configs/calvados_dem_area_light_100km2_fast.toml
hmp run examples/projects/17_site_selection_workflow/configs/bretagne_hydrometry_50_500_small.toml
hmp run examples/projects/17_site_selection_workflow/configs/bretagne_hydrometry_50_500_small_bdtopage.toml
hmp run examples/projects/17_site_selection_workflow/configs/auvergne_rhone_alpes_hydrometry_preview.toml
hmp run examples/projects/17_site_selection_workflow/configs/corse_hydrometry_preview.toml

Use the direct DEM snap example to check the normal map layout. Use the BD Topage variant only to inspect outlet-location sensitivity; the reference network remains an internal snapping support.

The two closure examples for the stabilized contract are:

Config

Effective profile

Expected result

Review HTML

calvados_dem_area_light_100km2_fast.toml

area_only

26 candidates, 10 selected, 16 rejected

outputs/calvados_dem_area_light_100km2_fast_v1/review/index.html

bretagne_hydrometry_50_500_small_bdtopage.toml

gauged_downstream_station

6 candidates, 6 selected, 0 rejected

outputs/bretagne_hydrometry_50_500_small_bdtopage_v1/review/index.html

Both paths above are relative to examples/projects/17_site_selection_workflow/. The associated map file is review/site_selection_map.png in each output directory.

Troubleshooting#

  • If selected sites appear on a regular grid, check whether the input is a synthetic area_only fixture rather than real hydrometry stations.

  • If the DEM is absent from the map, verify [data.dem] and site_selection.dem.map_background_extent.

  • If station points and basins are offset, inspect CRS metadata and prefer provider Lambert-93 coordinates when available.

  • If hmp run fails while opening an old cache.duckdb, open the cache with a recent HydroModPy build once; old V1 data-cache tables are adopted into the current schema_migrations ledger.