Coastal

Coastal Boundary Data

BMI Compatible Coastal Data Assembly

Import from Values Dictionary

Provisions are made for future coastal data import through BMI in the troute_model class, whereas the formalism is similar to the one used, e.g., for Gage Data. Coastal boundary data are assembled from the following input ndarrays in the member function run, from the values dictionary passed to run (all ndarrays):

• depthArray_coastal: flattened depth array
• timeArray_coastal: number of seconds relative to coastal_timeRef
• nTimes_coastal: number of time stamps for coastal data
• stationArray_coastal: coastal array (integers)
• nStations_coastal: number of coastal reference stations
• coastal_timeRef: time reference to simplify timestamps

Assembly of Dataframe

The function uses _unflatten_array() from the bmi_array2df library (a2df) to transform the depthArray_coastal from its flattened format back into a 2D array, organized by the number of times (nTimes_coastal) and stations (nStations_coastal). Time information is added to the array by decoding timeArray_coastal relative to the reference time (coastal_timeRef) using _time_retrieve_from_arrays() (also from a2df), where the output is a dataframe. The station IDs (stationArray_coastal) are added next and used to index the dataframe. The result is a dataframe where each row corresponds to a station and each column corresponds to the time reference. The resulting dataframe, df_withTimes_coastal, is then stored as self._network._coastal_boundary_depth_df, which represents the coastal boundary conditions over time at each station.

Direct import of Dflow and SCHISM data

The _coastal_boundary_depth_df is imported in assemble_forcings which is a member function of AbstractNetwork, by calling the helper function read_coastal_output. At this stage, the coastal datafile is imported using the xarray library, and the type of coastal model is identified through the imported dataset's attributes: if the 'institution' is 'Deltares', the file is identified as a Dflow model, otherwise as a SCHISM model. The routine corresponding to the file type is then called. Two different SCHISM formats are accommodated in read_coastal_output: (1) the SCHISM dataset is already subset correctly, and the timestamp is given relative to a reference time (base_date in time attributes), or (2) the SCHISM dataset still needs to be subset to a list of nodes, and the timestamp is absolute.

Import of Dflow data

The helper function read_DFlow_output creates a coastal dataframe as follows, starting by extracting the variables 'waterlevel' and 'bedlevel' from the input xarray dataset ds and converting them into a pandas DataFrame using to_dataframe(). Then, the water depth is calculated by subtracting the 'bedlevel' from the 'waterlevel', which gives the water depth at each station for each time step. The station names are then decoded from UTF-8 format and processed to extract numeric station identifiers using a regular expression. This numeric value is cast to a float and then to an integer, simplifying the station names to a usable format. The dataframe is reformatted by resetting the index to include 'time' and 'station_name' columns and rearranged to have station_name as the index and time as the column headers. Each cell in the resulting dataframe contains the corresponding depth value for the respective station and time.

Import of SCHISM data - already subset and relative time

• Base Date Extraction: The base_date is extracted from the dataset's time attribute for later correction of the time column in the dataframe, converting it into a datetime object.
• Elevation Data Retrieval: Elevation data are extracted from the dataset (ds['elevation']) for the nodes specified in the coastal_hy_crosswalk, and converted into a dataframe (elevation_df).
• Check for empty dataframe: If no valid nodes are found in the crosswalk, an empty dataframe is returned.
• Node Replacement: The SCHISM node IDs are replaced with HYFeatures segment IDs from the crosswalk by repeating the list of segment IDs to match the length of the dataframe.
• Depth Data Retrieval: Depth data are extracted from the dataset (ds['depth']) for the same nodes and converted into another dataframe (depth_df), and the node IDs are replaced with the corresponding HYFeatures segment IDs.
• Merge and Calculate Water Depth: The elevation and depth dataframes are merged on the link (HYFeatures segment ID), whereas the water depth is calculated by summing the elevation and depth columns. The elevation and depth columns are dropped, leaving only the waterdepth column.
• Time Adjustment: The function adjusts the time column by converting the time values (in seconds) into timedelta objects and adding them to the base date.
• Final Formatting: The dataframe is restructured so that the rows represent locations (link), and the columns represent timestamps. Missing values are filled with NaN. The base_date column is dropped as it is no longer needed.

Import of SCHISM data - non-subset model and absolute time

• Dataset Cleanup: Unnecessary variables are removed (SCHISM_hgrid_node_x and SCHISM_hgrid_node_y) from the dataset (ds).
• Node ID Crosswalk Mapping: The node IDs (nodeID) are mapped to the corresponding indices in the dataset using a dictionary (idmap).
• Node Selection: The function iterates over the keys from coastal_hy_crosswalk (SCHISM node IDs) and checks if they exist in the dataset's nodeID list. If a match is found, it appends the dataset’s corresponding node index (idSelect) and the HYFeatures segment ID (idHySelect).
• Empty dataframe Check: If no valid nodes from the crosswalk are present, the function returns an empty dataframe.
• Elevation Data Retrieval: If valid nodes are found, the elevation data are retrieved for the selected node indices (idSelect) from the dataset (d**s2['elevation']). This data is converted into a dataframe (elevation_df**).
• Replace SCHISM Nodes with HYFeatures IDs: The function replaces SCHISM node indices in the elevation dataframe with the corresponding HYFeatures segment IDs from idHySelect. It repeats the list of HYFeatures IDs to match the length of the dataframe.
• Depth Data Retrieval: Depth data are retrieved for the same node indices, converted into the depth dataframe depth_df, and the SCHISM node indices are replaced with HYFeatures segment IDs (idSelect).
• Combine Elevation and Depth Data: The elevation- and depth- dataframes are merged on the link (HYFeatures segment ID), and the water depth is calculated by summing the elevation and depth columns. Afterward, the elevation, depth, node_x, and node_y columns are dropped, leaving only the waterdepth column.
• Reformat dataframe: The dataframe is restructured so that rows represent locations (link, corresponding to HYFeatures segments), and columns represent timestamps. Missing values are filled with NaN.