Tools
river_route.metrics
river_route.tools
subset_configs_to_river(target_river, params, out_params, weights=None, out_weights=None)
Subset routing parameters and weight tables to the target river and all rivers upstream of it.
The target river becomes the outlet (downstream_river_id set to -1) in the subset. If weight table paths are provided, the weight table is also filtered to only include matching rivers.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target_river
|
int
|
river_id of the river to subset to (becomes the outlet) |
required |
params
|
PathInput
|
path to the full routing parameters parquet file |
required |
out_params
|
PathInput
|
path to write the subsetted parameters parquet file |
required |
weights
|
PathInput | None
|
path to the full grid weights netCDF file (optional) |
None
|
out_weights
|
PathInput | None
|
path to write the subsetted grid weights netCDF file (optional, required if weights is given) |
None
|
connectivity_to_digraph(river_ids, downstream_ids)
Build a NetworkX DiGraph from river connectivity arrays.
Each edge goes from a river to its downstream river (including the -1 sentinel for outlets).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
river_ids
|
ndarray
|
1D array of river ID integers |
required |
downstream_ids
|
ndarray
|
1D array of downstream river ID integers (-1 for outlets) |
required |
Returns:
| Type | Description |
|---|---|
DiGraph
|
Directed graph with edges from each river_id to its downstream_river_id |
adjacency_matrix(river_ids, downstream_ids)
Build a sparse adjacency matrix for the river network.
Entry A[downstream_idx, upstream_idx] = 1 for each river that flows into a downstream river. Outlet rivers (downstream_id < 0) have no outgoing edges. The input arrays must be topologically sorted (upstream before downstream) — a ValueError is raised otherwise.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
river_ids
|
ndarray
|
1D array of river ID integers, topologically sorted upstream to downstream |
required |
downstream_ids
|
ndarray
|
1D array of downstream river ID integers (-1 for outlets) |
required |
Returns:
| Type | Description |
|---|---|
csc_matrix
|
Sparse CSC matrix of shape (n, n) where n = len(river_ids) |
Raises:
| Type | Description |
|---|---|
ValueError
|
if a downstream_id is not found in river_ids, or if the arrays are not topologically sorted |
river_route.runoff
cell_xy_from_regular_grid(dataset, x_var='lon', y_var='lat')
Get cell center x and y coordinates from a regular grid common dataset structure.
voronoi_diagram_from_regular_xy(x, y, crs=4326)
Create a GeoDataFrame of Voronoi polygons around the center of each cell in a grid.
compute_voronoi_catchment_intersects(voronoi_gdf, catchments_gdf, save_path=None, attributes=None, river_id_variable='river_id')
Create a table of intersections between Voronoi polygons and catchments.
grid_weights(grid_path, catchments_path, *, var_x='lon', var_y='lat', var_river_id='river_id', crs=4326, save_voronoi_path=None, save_weights_path=None, routing_params_path=None)
Compute the grid weights for a given grid and catchments.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
grid_path
|
PathInput
|
path to a NetCDF file containing the grid information (must include 'lon' and 'lat' variables) |
required |
catchments_path
|
PathInput
|
path to a GeoParquet file containing the catchment geometries (must include 'river_id' column) |
required |
var_x
|
str
|
x-coordinate variable name in the grid file |
'lon'
|
var_y
|
str
|
y-coordinate variable name in the grid file |
'lat'
|
var_river_id
|
str
|
variable name for river ID in the catchments file |
'river_id'
|
crs
|
int
|
EPSG code for the grid coordinate reference system (default: 4326) |
4326
|
save_voronoi_path
|
PathInput | None
|
optional path to save the Voronoi polygons as a GeoParquet file |
None
|
save_weights_path
|
PathInput | None
|
optional path to save the grid weights as a NetCDF file |
None
|
routing_params_path
|
PathInput | None
|
optional path to a routing params parquet file whose river_id column order is used to topologically sort the weight table rows. When omitted the row order is spatial (not topological). |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: a DataFrame containing the grid weights with columns ['river_id', 'x_index', 'y_index', 'x', 'y', 'area_sqm', 'proportion'] |
runoff_to_qlateral(runoff_data, grid_weights_file, *, var_runoff='ro', var_x='lon', var_y='lat', var_t='time', var_river_id='river_id', runoff_depth_unit=None, cumulative=False, force_positive_runoff=False, force_uniform_timesteps=True, as_volumes=False)
Aggregates gridded runoff depths to catchment level qlateral as depths or volumes. The core computation is an area weighted average of the cell's runoff value.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
runoff_data
|
str | list[str]
|
path(s) to runoff files |
required |
grid_weights_file
|
str
|
path to the weight table netCDF produced by |
required |
var_runoff
|
str
|
runoff variable name in the LSM files |
'ro'
|
var_x
|
str
|
x-coordinate variable name in the LSM files |
'lon'
|
var_y
|
str
|
y-coordinate variable name in the LSM files |
'lat'
|
var_t
|
str
|
time variable name in the LSM files |
'time'
|
var_river_id
|
str
|
river ID variable name in the weight table and parameters file |
'river_id'
|
runoff_depth_unit
|
str
|
unit of the depth values; checked for in file attributes, defaulting to meters |
None
|
cumulative
|
bool
|
whether the runoff data is cumulative; converted to incremental if True |
False
|
force_positive_runoff
|
bool
|
clip negative runoff values to zero |
False
|
force_uniform_timesteps
|
bool
|
resample to a uniform timestep if the input is irregular |
True
|
as_volumes
|
bool
|
if True, return volumes (m³) instead of depths (m) |
False
|
Returns:
| Type | Description |
|---|---|
Dataset
|
xr.Dataset: qlateral with dimensions |