A basin network can be seen as a graph, specifically as a directed acyclic tree. In GEOframe, the topology of the basins, which describes the direction of the flow and the interconnections of the basins, is usually saved in a text file with two columns: the first column represents the origin basin, and the second column represents the target basin. The 0 is used to mark the outlet of the network. For example:
8 7 7 4 6 5 5 4 4 3 3 2 2 1 1 0
The 0 mark the outlet.
In my work, I've encountered the need to manipulate basin networks so verifying the topological correctness of these new graphs is crucial. To accomplish this task, I chose the NetworkX Python library. This library facilitates a variety of tasks—such as cutting the network, iterating through the network, and comparing two or more networks within the same watershed—thanks to its class structure, specifically the Graph class. As a result, I've developed some functions for basic operations on the network and shared them in my fork of GEOframe on GitHub.
I've added two packages to this library. The first one, named network, includes functions to manipulate the network and check its integrity. In the subbasin_check, I've placed a function to check if the centroid of a basin is within the corresponding polygon.
The output of my functions is typically a Graph object, which enables the application of all functions available in NetworkX. Note that a node is defined by its ID as a string.
A NetworkX graph can be created from a GEOFrame topology file using two options: get_raw_network and get_network. In common scenarios, I recommend the use of get_network because this function includes several checks on the topology, such as verifying if the graph is acyclic or directed. However, in certain cases where these checks are unnecessary or fail (for example, with dams that pump water upstream), get_raw_network should be used instead.
Here, I've listed the implemented functions and provided some examples:
check_network(net): Checks the topology of the graph.get_upstream_network(net, node): Returns the upstream network from the provided node.get_subgraph(net, gauge, gauge_id, is_calibration): Builds a network for a provided basin. I use it to extract the sub-network in the case of sequential calibration of the GEOFrame rainfall-runoff model and build sim files. If is_calibration is set to true then the nodes upstream to other gauge are deleted.write_network(net, topology_path): Writes the network as a GEOFrame topology file.sort_node(net, nodes): Retrieves the node with a topological order. Provide a list of nodes and the function return the it in the topological order.