Topobathy_nc

Topobathy Files (.netcdf)

The topobathy files provide natural cross-section data for river segments, which is used in hybrid simulations to enhance the accuracy of diffusive wave routing. The data is read from netCDF files and stored in dataframes for both the original and refactored hydrofabric, depending on the configuration.

Topobathy Files - V3

[Warning: Development of this version of the topobathy data has been discontinued, and it is no longer recommended for use in new project]

In version V3, the netCDF topobathy files are imported in nwm_network_preprocess during the processing of hybrid simulations, which involve both MC and diffusive wave routing. The processing follows:

• Topobathy File Identification:

The code checks whether the simulation is set up to run as a hybrid using run_hybrid flag in compute_parameters["hybrid_parameters"]. If hybrid routing is enabled and use_topobathy is set to True, it means natural cross-section data (topobathy data) will be utilized during the simulation. The topobathy_file and refactored_topobathy_file parameters specify the file paths for the topobathy data. These files contain natural cross-section information for river segments. If the simulation uses the original (non-refactored) hydrofabric, the topobathy_file is read. If a refactored network is used, the refactored_topobathy_file will be read.

• Reading Topobathy Data:

If hybrid routing with topobathy is enabled, the topobathy NetCDF file is read using the function nhd_io.read_netcdf(topobathy_file). The data is then set to use the link (or comid) column as its index, which represents the river segment IDs. The data read from the file is stored in the dataframe topobathy_df. If the simulation also involves a refactored hydrofabric (using run_refactored), a separate unrefactored topobathy file is also loaded into a dataframe, called unrefactored_topobathy_df.

If no topobathy file is provided, a default trapezoidal geometry will be used for routing, in which case the topobathy_df is initialized as an empty dataframe.

At the end, the topobathy_df (containing the natural cross-section data) and unrefactored_topobathy_df are returned along with other network and hydraulic data. These data are utilized in further network processing for hybrid simulations.

Topobathy Files - V4

For both HYFeatures- and NHD networks, topobathy is set in initialize_routing_scheme in the class AbstractNetwork. The routing type map is defined as follows: routing_type = [run_hybrid, use_topobathy, run_refactored], and topobathy is only imported if the second entry in routing_type is True.

A routing scheme map dictionary is defined as _routing_scheme_map, where only two dictionary keys result in importing topobathy files:

• MCwithDiffusiveNatlXSectionNonRefactored: routing_type = [True, True, False]
• MCwithDiffusiveNatlXSectionRefactored: routing_type = [True, True, True]

MCwithDiffusiveNatlXSectionNonRefactored

Initial setup:

The latter keys, in turn, refer to classes that are invoked as child classes of MCwithDiffusive, which is, in turn, a child class of AbstractRouting. The two child classes for which use_topobathy is set to True are structured as follows:

• If _topobathy_df is empty, it loads the data from a file specified by hybrid_params under "topobathy_domain".
• If the file is a netCDF file, it reads the data using the read_netcdf helper function (using the xarray library) and sets the index to 'link'.
• If it's a .parquet file, it reads the data using the read_parquet helper function that is based on pandas, with specific segment IDs (seg_ids) and sets the index to 'hy_id'.
• The segment IDs for which topobathy cannot be obtained are determined next, and the resulting ids are filled in using the function _fill_in_missing_topo_data

Fill in missing topopathy data

The _fill_in_missing_topo_data function is designed to fill in missing topography and bathymetry (topobathy) data for one of a set of specific segments (referred to as original_key) by searching upstream along the mainstem. First, it creates a filtered dataframe (mainstem_df) that contains all segments along the same mainstem. Starting with original_key, the function iteratively searches for segments upstream (i.e., the ones whose downstream link is key) and adds them to a connections list rconn_list. This is done as long as there are upstream segments.

The function then looks for the first upstream segment in rconn_list that exists in the topobathy_df (i.e., the one that has topobathy data). This segment is stored as new_key. If an upstream segment (new_key) is found, the function retrieves its topobathy data from topobathy_df. It selects the topobathy data at the most downstream cross-section (cs_id), which is identified by the maximum cs_id value. The selected topobathy data is modified: its cs_id is reset to 1 (indicating it now represents the missing data for the original_key), and the hy_id is set to original_key to associate the data with the missing segment, before the modified data with the filled-in version for the missing segment is returned.

Completion

After filling in the missing data, it identifies "bad" links (those for which topo data can't be obtained), and concatenates the topobathy dataframe with the filled data. For each segment, it selects the topobathy data with the minimum cs_id value to avoid duplicates and assigns this as the final _topobathy_df.

MCwithDiffusiveNatlXSectionRefactored

• Topobathy Data (topobathy_df property):

This property checks if the private variable _topobathy_df is empty. If it is, it retrieves the file path for the refactored topobathy data from hybrid_params and reads the data from a netCDF file using the read_netcdf function and sets the index of the resulting dataframe to the 'link' column, where it is stored in _topobathy_df for future access.

• Refactored Diffusive Domain (refactored_diffusive_domain property):

The property checks if _refactored_diffusive_domain is empty. If it is, it retrieves the path for the refactored domain data and reads it using the read_diffusive_domain helper function. The resulting data is stored in _refactored_diffusive_domain, which represents the connections and characteristics of the diffusive network.

• Refactored Reaches (refactored_reaches property):

If _refactored_reaches is empty, a process to build the network is initiated. It first retrieves the refactored topobathy file and builds connections using build_refac_connections. For each time window (tw), it extracts stream segments and connections, constructing a dictionary that contains tributary segments and their connections. The organize_independent_networks function is then used to identify independent reaches within the tributaries, ultimately storing the organized reaches in _refactored_reaches. The property returns _refactored_reaches, which now holds the structured network data.

• Unrefactored Topobathy Data (unrefactored_topobathy_df property):

Unrefactored topobathy data are retrieved. If the corresponding _unrefactored_topobathy_df is empty, it retrieves the file path from hybrid_params, reads the data, sets the index to the 'link' column, and converts the index to integers to ensure access to both refactored and unrefactored topobathy datasets.

• The build_refac_connections function:

The function constructs a dictionary of connections for a refactored network dataset, enabling the management of stream segment connectivity. It accepts the dictionary diff_network_parameters, which contains settings and file paths required for constructing the network. It establishes a mapping between expected variable names in the input dataset and those recognized by the network processing modules. Default column names are specified if not provided in diff_network_parameters.

The function reads the network parameter data into a dataframe, which includes the stream links and their downstream relationships. It then identifies terminal segments that do not have downstream connections by comparing unique values in the 'to' column with those in the 'link' column. The relevant columns are selected, renamed, indexed by segment ID, and sorted. Connections are then extracted from the processed datadrame, creating a dictionary where each stream segment key maps to its downstream connections. The constructed connections dictionary is returned.