easy_vic_build.tools.routing_func.river_network

Module easy_vic_build.tools.routing_func.river_network.

Functions

`build_node_features`(G, matrix_features)	Sample raster features to graph nodes by `matrix_pos`.
`build_upstream_subgraph_for_node`(G, target_node)	Build upstream subgraph for a target node with optional k-hop limit.
`cal_threshold`(flow_acc)	Calculate default river threshold from flow accumulation.
`create_river_network_graph`(flow_direction, ...)	Create directed river-network graph from D8 flow direction and accumulation.
`extract_connected_river_network`(G[, ...])	Extract largest weakly connected river subnetwork.
`find_path_to_sink`(G, start_node, sinks, ...)	Find one downstream river path from a start node to a sink.
`find_river_paths`(G[, min_in_degree])	Extract unique downstream paths across river nodes.
`get_display_positions`(G)	Build plotting positions from node matrix coordinates.
`sort_river_paths_by_lengths`(river_paths[, ...])	Sort river paths by path length and return ranking metadata.

easy_vic_build.tools.routing_func.river_network.cal_threshold(flow_acc)[source]

Calculate default river threshold from flow accumulation.

Parameters:: flow_acc (numpy.ndarray) – Flow-accumulation raster.
Returns:: 80th percentile value of flow_acc.
Return type:: float

easy_vic_build.tools.routing_func.river_network.get_display_positions(G)[source]

Build plotting positions from node matrix coordinates.

Parameters:: G (networkx.Graph) – Graph whose nodes contain matrix_pos=(row, col) attributes.
Returns:: Mapping node -> (x, y) where x=col and y=-row for display.
Return type:: dict

easy_vic_build.tools.routing_func.river_network.create_river_network_graph(flow_direction, flow_acc, threshold=None, mask=None)[source]

Create directed river-network graph from D8 flow direction and accumulation.

Parameters:

flow_direction (numpy.ndarray) – 2D D8 flow-direction raster using codes in direction_mapping_num.
flow_acc (numpy.ndarray) – 2D flow-accumulation raster with the same shape as flow_direction.
threshold (float, optional) – River-definition threshold on flow_acc. If None, 80th percentile is used via cal_threshold().
mask (numpy.ndarray, optional) – 2D mask raster with the same shape as flow_direction.

Returns:

(G, position_to_node, threshold) where:

G is a networkx.DiGraph with node attributes: matrix_pos, direction_value, flow_acc, node_type, is_river and optional mask.
position_to_node maps (row, col) -> node_name.
threshold is the effective threshold used.

Return type:

tuple

Notes

Node type rules:

river: flow_acc >= threshold
sink: direction is invalid (0/-1/255/None)
hillslope: otherwise

Examples

>>> flow_direction = np.array([[1, 4], [64, 0]])
>>> flow_acc = np.array([[10.0, 20.0], [5.0, 1.0]])
>>> G, pos2node, thr = create_river_network_graph(flow_direction, flow_acc, threshold=8)
>>> isinstance(G, nx.DiGraph), isinstance(pos2node, dict)
(True, True)

easy_vic_build.tools.routing_func.river_network.find_path_to_sink(G, start_node, sinks, visited_edges)[source]

Find one downstream river path from a start node to a sink.

Parameters:

G (networkx.DiGraph) – River graph with node attribute is_river.
start_node (str) – Starting node name.
sinks (sequence) – Candidate sink nodes.
visited_edges (set) – Mutable edge set used to reduce duplicate traversals across calls.

Returns:

Node sequence of one path. May contain only start_node when no downstream river successor exists.

Return type:

list

easy_vic_build.tools.routing_func.river_network.find_river_paths(G, min_in_degree=None)[source]

Extract unique downstream paths across river nodes.

Parameters:

G (networkx.DiGraph) – River graph.
min_in_degree (int, optional) – Source-node criterion. If None, the minimum in-degree among river nodes is used.

Returns:

Unique river paths, each represented by a node-name sequence.

Return type:

list of list

Notes

If no sink node (out-degree=0) is found, the river node with maximum flow_acc is used as fallback sink.

easy_vic_build.tools.routing_func.river_network.sort_river_paths_by_lengths(river_paths, descending=True)[source]

Sort river paths by path length and return ranking metadata.

Parameters:

river_paths (list of list) – Input river paths.
descending (bool, optional) – If True, longest-first ordering; otherwise shortest-first.

Returns:

(sorted_river_paths, length_info) where length_info is a list of dictionaries with rank, length, start/end nodes, and original path.

Return type:

tuple

easy_vic_build.tools.routing_func.river_network.extract_connected_river_network(G, min_size=10, mask=False)[source]

Extract largest weakly connected river subnetwork.

Parameters:

G (networkx.DiGraph) – Full river graph.
min_size (int, optional) – Minimum component size to keep before selecting largest component.
mask (bool, optional) – If True, only keep river nodes with node attribute mask truthy.

Returns:

Largest qualified weakly connected river subgraph. Returns an empty DiGraph when no component passes min_size.

Return type:

networkx.DiGraph

easy_vic_build.tools.routing_func.river_network.build_node_features(G, matrix_features)[source]

Sample raster features to graph nodes by matrix_pos.

Parameters:

G (networkx.Graph) – Graph with node attribute matrix_pos=(row, col).
matrix_features (list of numpy.ndarray) –
Feature rasters to sample. Supported shapes:
- 2D: (row, col) -> scalar sampled per node.
- 3D: (time, row, col) -> 1D time series sampled per node.

Returns:

Node-aligned features for each input matrix, preserving input order.

Return type:

list of numpy.ndarray

easy_vic_build.tools.routing_func.river_network.build_upstream_subgraph_for_node(G, target_node, khop=None, cutoff_node=None)[source]

Build upstream subgraph for a target node with optional k-hop limit.

Parameters:

G (networkx.DiGraph) – Directed river graph.
target_node (str) – Node for which upstream contributors are traced.
khop (int, optional) – Maximum upstream hop distance. If None, traverse until exhaustion.
cutoff_node (str, optional) – Upstream node at which traversal stops (node itself is still connected to its downstream edge in the returned subgraph).

Returns:

(new_G, new_edges) where new_G is the upstream subgraph and new_edges is the collected upstream edge list.

Return type:

tuple