ripple1d.ops package#

Submodules#

ripple1d.ops.endpoints module#

ripple1d.ops.fim_lib module#

Create FIM library.

ripple1d.ops.fim_lib.create_fim_lib(submodel_directory, plans, library_directory, cleanup, ras_version='631', cog=False, resolution=3, resolution_units='Meters', dest_crs=5070)#

Create a new FIM library for a NWM id.

Export depth rasters and stage-discharge rating curves from HEC-RAS to rasters and a sqlite database.

Parameters:

  • submodel_directory (str) – The path to the directory containing a sub model geopackage

  • plans (list) – suffixes of plans to create fim library for.

  • library_directory (str) – No function

  • cleanup (bool) – whether to delete the source depth grids once they’ve been processed

  • ras_version (str, optional) – which version of HEC-RAS to use, by default “631”

  • cog (bool, optional) – whether to generate COGs for output rasters (overviews at levels [4, 8, 16]), by default False

  • resolution (float, optional) – horizontal resolution to resample output raster to, by default 3

  • resolution_units (str, optional) – unit for resolution, by default “Meters”

  • dest_crs (str, optional) – Destination crs.

Returns:

dictionary with paths to output rasters and rating curve database

Return type:

dict

ripple1d.ops.fim_lib.create_rating_curves_db(submodel_directory, plans, ras_version='631', table_name='rating_curves')#

Create a new rating curve database for a NWM id.

Export stage-discharge rating curves from HEC-RAS to rasters and a sqlite database.

Parameters:

  • submodel_directory (str) – The path to the directory containing a sub model geopackage

  • plans (list) – suffixes of plans to create fim library for.

  • ras_version (str, optional) – which version of HEC-RAS to use, by default “631”

  • table_name (str, optional) – name for the table holding stage-discharge rating curves in the output database, by default “rating_curves”

Returns:

dictionary with paths to output rating curve database

Return type:

dict

ripple1d.ops.fim_lib.find_missing_grids(rm, plan_name)#

Find missing depth grids.

ripple1d.ops.fim_lib.post_process_depth_grids(rm, plan_name, dest_directory, accept_missing_grid=False, cog=False, dest_crs=5070, resolution=3, resolution_units='Meters')#

Clip depth grids based on their associated NWM branch and respective cross sections.

Return type:

tuple[list[str]]

ripple1d.ops.metrics module#

Conflation Metrics.

class ripple1d.ops.metrics.ConflationMetrics(xs_gdf, river_gdf, hull_gdf, network_reach, network_reach_plus_ds_reach, network_id)#

Bases: object

Calculate metrics for a cross section.

clean_length(length, meters_to_feet=True)#

Clean the length.

compute_coverage_metrics(xs_gdf)#

Calculate the coverage metrics for a set of cross sections.

Return type:

dict

compute_station(river, xs)#

Compute the station for a river reach.

eclipsed_reaches(network_reaches)#

Calculate the overlap between the network reach and the cross sections.

Return type:

dict

length_metrics(xs_gdf)#

Calculate the reach length between cross sections along the ras river line and the network reach.

Return type:

dict

overlapped_reaches(to_reaches)#

Calculate the overlap between the network reach and the cross sections.

Return type:

dict

populate_station_elevation(row)#

Populate the station elevation for a cross section.

Return type:

dict

populate_thalweg_station(row)#

Populate the thalweg station for a cross section.

Return type:

str

property river_line#

Get the geomtry for the river centerline.

thalweg_metrics(xs_gdf)#

Calculate the distance between the thalweg point and the network intersection point.

Return type:

dict

us_ds_xs(xs_gdf)#

Get the most upstream and downstream cross sections.

ripple1d.ops.metrics.combine_reaches(network_reaches, network_id)#

Combine network reaches.

Return type:

LineString

ripple1d.ops.metrics.compute_conflation_metrics(source_model_directory, model_name, source_network)#

Compute metrics for a network reach.

Parameters:

  • source_model_directory (str) – The path to the directory containing HEC-RAS project, plan, geometry, and flow files.

  • model_name (str) – The name of the source HEC-RAS model.

  • source_network (dict) –

    Information on the network to conflate

    • file_name (str):

      path/to/nwm_network.parquet (required)

    • type (str):

      must be ‘nwm_hydrofabric’ (required)

    • version (str):

      optional version number to log

  • task_id (str, optional) – Task ID to use for logging, by default “”

Returns:

Dictionary containing metrics describing model network match

Return type:

dict

Notes

The compute_conflation_metrics endpoint uses the information gathered in conflation to summarize how well a NWM reach and HEC-RAS model section align. The metrics are broken down into three categories: xs, lengths, and coverage.

  • xs. These metrics quantify the degree of alignment between the NWM reach centerline and the HEC-RAS model. The metrics below are measured at HEC-RAS cross-section and summary statistics are reported in the conflation metrics output.

    • centerline_offset measures the straightline distance between RAS centerline and NWM reach line

    • thalweg_offset measures the straightline distance between lowest point along each RAS section and NWM reach line

  • lengths. These metrics assess centerline length differences between HEC-RAS and the NWM reaches.

    • ras is the distance along the RAS centerline between upstream and downstream cross-section

    • network is the distance along the NWM reach between upstream and downstream cross-section

    • network_to_ras_ratio is the network length divided by ras length

  • coverage. These metrics quantify the portion of the NWM reach between the upstream and downstream cross-section.

    • start is the ratio of NWM reach length that occurs u/s of the upstream cross-section

    • end is the ratio of NWM reach length that occurs u/s of the downstream cross-section

compute_conflation_metrics also reports overlapped reaches and eclipsed reaches. Overlapped_reaches is a list of reaches that are intersected by the most d/s cross-section of this model. Eclipsed_reaches is a list of NWM reaches that are contained within the concave hull of the cross-sections.

ripple1d.ops.metrics.get_eclipsed_reaches(conflation_parameters, network_id)#

Walk the network to find all eclipsed reaches until the next non-eclipsed reach.

ripple1d.ops.ras_conflate module#

Conflate HEC-RAS Model.

ripple1d.ops.ras_conflate.clean_conflation(conflation)#

Remove any straggler NWM reaches with matching u/s and d/s sections.

Return type:

dict

ripple1d.ops.ras_conflate.conflate_model(source_model_directory, model_name, source_network, compute_metrics=True, min_flow_multiplier=0.9, max_flow_multiplier=1.2)#

Conflate a HEC-RAS model with NWM reaches.

Parameters:

  • source_model_directory (str) – The path to the directory containing HEC-RAS project, plan, geometry, and flow files.

  • model_name (str) – The name of the HEC-RAS model.

  • source_network (dict) –

    Information on the network to conflate

    • file_name (str):

      path/to/nwm_network.parquet (required)

    • type (str):

      must be ‘nwm_hydrofabric’ (required)

    • version (str):

      optional version number to log

  • compute_metrics (bool) – Boolean indicating if conflation metrics should be computed.

  • min_flow_multiplier (float) – Number that will be multiplied by the NWM “high flow threshold” to define the low_flow value in the conflation json.

  • max_flow_multiplier (float) – Number that will be multiplied by the NWM 100-year flow to define the high_flow value in the conflation json.

Returns:

Path to the .conflation.json file generated

Return type:

str

Raises:

  • KeyError – Raises when source_network dict does not contain a file_name value

  • ValueError – Raises when source_network type is not nwm_hydrofabric

Notes

The spatial extents of HEC-RAS river reaches and National Water model (NWM) reaches are not aligned. The conflate_model endpoint resolves these differences by associating HEC-RAS models and model components (e.g. cross-sections) with the NWM reaches they overlap.

  1. Generate a concave hull (bounding geometry) around the HEC-RAS source model cross-sections

  2. Extract NWM reaches intersecting the hull

  3. For each HEC-RAS river reach within the source model,

  1. Locate the NWM reaches nearest to the most upstream and most downstream cross-sections

  2. Extract all intermediate NWM reaches by walking the network from upstream to downstream

  1. For each NWM reach extracted,

  1. Locate the HEC-RAS cross-sections that intersect the reach

  1. Discard cross-sections that are not drawn right to left looking downstream

  2. If no cross-sections intersect the reach, mark the reach as “eclipsed”

  1. Mark the HEC-RAS cross-section closest to the upstream end of the reach as the “us_xs ”

  2. Identify the HEC-RAS cross-section that is closest to the downstream end of the reach, and then mark the next HEC-RAS cross-section downstream of it as the “ds_xs”

  1. If the “ds_xs” would be a HEC-RAS junction, mark the first cross-section downstream of the junction as “ds_xs”

  1. If “ds_xs” and “us_xs” are the same, mark the reach as eclipsed

  1. Generate a map of the conflated reaches and calculate conflation metrics

Additionally, high and low flows are generated for each reach to bound the SRC generated in later steps. The low flow is 0.9 times the high flow threshold listed for the reach in the NWM network. The high flow is the 1.2 times the 100 year flow from the NWM network.

ripple1d.ops.ras_conflate.conflate_single_nwm_reach(rfc, nwm_reach_id)#

Conflate a HEC-RAS model with a specific NWM reach.

ripple1d.ops.ras_conflate.find_eclipsed_reaches(rfc, conflation)#

Update the conflation dictionary to add NWM reaches between HEC-RAS sections.

Return type:

dict

ripple1d.ops.ras_conflate.fix_junctions(rfc, conflation)#

Update conflation such that confluences match between NWM and HEC-RAS.

Return type:

dict

ripple1d.ops.ras_conflate.generate_metadata(source_network, rfc)#

Log metadata about how conflation was generated.

Return type:

dict

ripple1d.ops.ras_conflate.get_linked_reaches(reaches)#

Return list of NWM IDs that share cross-sections (u/s, d/s).

Return type:

list

ripple1d.ops.ras_conflate.get_nwm_reaches(river_reach_name, rfc)#

Find a valid path of nwm reaches across a HEC-RAS river_reach_name (if one exists).

Return type:

list[str]

ripple1d.ops.ras_conflate.href_to_vsis(href, bucket)#

Convert public aws href to a virtual ref for gdal read.

Return type:

str

ripple1d.ops.ras_conflate.s3_public_href(bucket, key)#

Convert bucket and key to public href.

Return type:

str

ripple1d.ops.ras_run module#

Run HEC-RAS models.

ripple1d.ops.ras_run.create_flow_depth_array(flow, depth, increment=0.5)#

Interpolate flow values to a new depth array with a specified increment.

Return type:

tuple[array]

ripple1d.ops.ras_run.create_flow_depth_combinations(ds_depths, ds_wses, input_flows, min_depths)#

Create flow-depth-wse combinations.

Return type:

tuple

Parameters:

  • ds_depths (list) – downstream depths

  • ds_wses (list) – downstream water surface elevations

  • input_flows (np.array) – Flows to create profiles names from. Combine with incremental depths of the downstream cross section of the reach

  • min_depths (pd.Series) – minimum depth to be included. (typically derived from a previous noraml depth run)

Returns:

tuple: tuple of depths, flows, and wses

ripple1d.ops.ras_run.create_model_run_normal_depth(submodel_directory, plan_suffix, num_of_discharges_for_initial_normal_depth_runs=10, ras_version='631', show_ras=False)#

Write and compute initial normal depth runs to develop initial rating curves.

Parameters:

  • submodel_directory (str) – The path to the directory containing a sub model geopackage

  • plan_suffix (str) – characters to append to the end of the plan name, by default “_ind”

  • num_of_discharges_for_initial_normal_depth_runs (int, optional) – number of discharges to run, evenly spaced between low and high flow limits, by default 10

  • ras_version (str, optional) – which version of HEC-RAS to use, by default “631”

  • show_ras (bool, optional) – whether to run HEC-RAS headless or not, by default False

  • task_id (str, optional) – Task ID to use for logging, by default “”

Returns:

string representation of flow file data

Return type:

str

Raises:

  • FileNotFoundError – raised when .conflation.json file not found in submodel_directory

  • FileNotFoundError – raised when geopackage file not found in submodel_directory

Notes

create_model_run_normal_depth is intended to create an initial stage-discharge rating curve for the HEC-RAS submodel. Analysis flows are evenly spaced between the min and max discharge for the reach that were established by running conflate_model. The downstream boundary condition for these runs are set to normal depth with slope of 0.001.

ripple1d.ops.ras_run.determine_flow_increments(rm, plan_names, river, reach, nwm_id, depth_increment=0.5)#

Detemine flow increments corresponding to 0.5 ft depth increments using the rating-curve-run results.

Return type:

tuple[array]

ripple1d.ops.ras_run.establish_order_of_nwm_ids(conflation_parameters)#

Establish the order of NWM IDs based on the cross section IDs.

Return type:

list[str]

ripple1d.ops.ras_run.get_flow_depth_arrays(rm, river, reach, river_station, thalweg)#

Create new flow, depth,wse arrays from rating curve-plans results.

Return type:

tuple[Series]

ripple1d.ops.ras_run.get_kwse_from_ds_model(ds_nwm_id, ds_nwm_ras_project_file, plan_names)#

Get the kwse values from the downstream model.

Return type:

tuple[float]

ripple1d.ops.ras_run.run_incremental_normal_depth(submodel_directory, plan_suffix, ras_version='631', depth_increment=0.5, write_depth_grids=True, show_ras=False)#

Write and compute incremental normal depth runs to develop rating curves and depth grids.

Parameters:

  • submodel_directory (str) – The path to the directory containing a sub model geopackage

  • plan_suffix (str) – characters to append to the end of the plan name, by default “_nd”

  • ras_version (str, optional) – which version of HEC-RAS to use, by default “631”

  • depth_increment (float, optional) – stage increment to use for developing the stage-discharge rating curve, by default 0.5

  • write_depth_grids (str, optional) – whether to generate depth rasters after each model run, by default True

  • show_ras (bool, optional) – whether to run HEC-RAS headless or not, by default False

  • task_id (str, optional) – Task ID to use for logging, by default “”

Returns:

string representation of flow file data

Return type:

str

Raises:

FileNotFoundError – raised when .conflation.json file not found in submodel_directory

Notes

run_incremental_normal_depth is intended to resample a stage-discharge rating curve generated with create_model_run_normal_depth to a consistent stage increment. Min and max stages for the curve are taken from the sub model plan with suffix “_ind”. A set of evenly spaced stages are selected between the min and max, and discharge values are estimated with linear interpolation. The final set of estimated discharges are then run through the model with a normal depth downstream boundary condition with slope of 0.001.

ripple1d.ops.ras_run.run_known_wse(submodel_directory, plan_suffix, min_elevation, max_elevation, depth_increment=2, ras_version='631', write_depth_grids=True, show_ras=False)#

Write and compute known water surface elevation runs to develop rating curves and depth grids.

Parameters:

  • submodel_directory (str) – The path to the directory containing a sub model geopackage

  • plan_suffix (str) – characters to append to the end of the plan name, by default “_kwse”

  • min_elevation (float) – minimum value for downstream boundary condition

  • max_elevation (float) – maximum value for downstream boundary condition

  • depth_increment (int, optional) – depth to increment stages between min and max elevation, by default 2

  • ras_version (str, optional) – which version of HEC-RAS to use, by default “631”

  • write_depth_grids (str, optional) – whether to generate depth rasters after each model run, by default True

  • show_ras (bool, optional) – whether to run HEC-RAS headless or not, by default False

  • task_id (str, optional) – Task ID to use for logging, by default “”

Returns:

string representation of flow file data

Return type:

str

Raises:

FileNotFoundError – raised when .conflation.json file not found in submodel_directory

Notes

run_known_wse creates a catalog of stage-discharge rating curves conditioned on downstream water surface elevation. For each depth increment between min_elevation and max_elevation, a unique rating curve is generated. Discharges for the rating curves are selected from the HEC-RAS plan with suffix “_nd” generated with Run_incremental_normal_depth.

ripple1d.ops.ras_terrain module#

ripple1d.ops.subset_gpkg module#

Subset a geopackage based on clonfation with NWM hydrofabric.

class ripple1d.ops.subset_gpkg.RippleGeopackageSubsetter(src_gpkg_path, conflation_json, dst_project_dir, nwm_id=None, min_flow_multiplier_ras=1, max_flow_multiplier_ras=1, ignore_ras_flows=False, ignore_nwm_flows=False)#

Bases: object

Subset a geopackage based on conflation with NWM hydrofabric.

property conflation_parameters: dict#

Extract conflation parameters from the conflation json.

copy_metadata_to_ripple1d_gpkg()#

Copy metadata table from source geopackage to ripple1d geopackage.

correct_ras_data(row)#

Make ras_data names consistent with river_station.

property crs#

Extract the CRS from the cross sections.

property ds_reach: str#

Extract downstream reach from conflation parameters.

property ds_river: str#

Extract downstream river from conflation parameters.

property ds_river_reach: str#

Extract downstream river_reach from conflation parameters.

property ds_river_reach_rs: str#

Extract downstream river_reach_rs from conflation parameters.

property ds_rs: str#

Extract downstream river station from conflation parameters.

property max_flow: float#

Extract the max flow from the cross sections.

property min_flow: float#

Extract the min flow from the cross sections.

property nwm_reach_model: NwmReachModel#

Return the new NWM reach model object.

property reach_distance_modifiers: dict#

Get a dictionary of reach station offsets due to junction lengths.

rename_river_reach(gdf)#

Rename river, reach, and river_reach columns after the nwm reach id.

Return type:

GeoDataFrame

property ripple1d_parameters: dict#

Extract ripple1d parameters from the conflation json.

property ripple_ds_xs#

The most downstream cross section for the ripple model.

property ripple_gpkg_file: str#

Return the path to the new geopackage.

property ripple_river: GeoDataFrame#

Subset river geometry based on NWM reach.

property ripple_structure: GeoDataFrame#

Subset structures based on NWM reach.

property ripple_us_xs#

The most upstream cross section for the ripple model.

property ripple_xs: GeoDataFrame#

Subset cross sections based on NWM reach.

property ripple_xs_concave_hull#

Get the concave hull of the cross sections.

property source_hulls: GeoDataFrame#

Extract cross sections from the source geopackage.

property source_junction: GeoDataFrame#

Extract junctions from the source geopackage.

property source_model_metadata#

Metadata from the source model.

property source_river: GeoDataFrame#

Extract river geometry from the source geopackage.

property source_structure: GeoDataFrame#

Extract structures from the source geopackage.

property source_xs: GeoDataFrame#

Extract cross sections from the source geopackage.

property split_source_hull#

Split the concave hull of the source model using the upstream and downstream cross sections of the submodel.

property subset_gdfs: dict#

Subset the cross sections, structues, and river geometry for a given NWM reach.

property subset_reaches: list[str]#

Get a list of river_reach values on path from u/s to d/s XS.

property subset_river: GeoDataFrame#

Trim source centerline to u/s and d/s limits and add all intermediate reaches.

property subset_structures: GeoDataFrame#

Trim source structures to u/s and d/s limits and add all intermediate reaches.

property subset_xs: GeoDataFrame#

Trim source XS to u/s and d/s limits and add all intermediate reaches.

trim_reach(sections)#

Trim a XS gdf to the u/s and d/s limits.

Return type:

GeoDataFrame

update_ds_reach_lengths(row)#

Update ras data by increasing downstream distance at sections above a junction crossing.

Return type:

str

update_ripple1d_parameters(rsd)#

Update ripple1d_parameters with results of subsetting.

update_structure_names(structures)#

Update structure IDs to align with sections.

Return type:

GeoDataFrame

update_xs_names(sections)#

Update section IDs to auto-incremented.

Return type:

GeoDataFrame

property us_reach: str#

Extract upstream reach from conflation parameters.

property us_river: str#

Extract upstream river from conflation parameters.

property us_river_reach: str#

Extract upstream river_reach from conflation parameters.

property us_river_reach_rs: str#

Extract upstream river_reach_rs from conflation parameters.

property us_rs: str#

Extract upstream river station from conflation parameters.

write_ripple1d_parameters(ripple1d_parameters)#

Write ripple1d parameters to json file.

write_ripple_gpkg()#

Write the subsetted geopackage to the destination project directory.

Return type:

None

property xs_distance_modifiers: dict#

Get a dictionary mapping the lowest cross-section along a reach to the junction distance below it.

ripple1d.ops.subset_gpkg.extract_submodel(source_model_directory, submodel_directory, nwm_id, model_name, min_flow_multiplier_ras=1, max_flow_multiplier_ras=1, ignore_ras_flows=False, ignore_nwm_flows=False)#

Use ripple conflation data to create a new GPKG from an existing ras geopackage.

Create a new geopackage with information for a specific NWM reach. The new geopackage contains layer for the river centerline, cross-sections, and structures.

Parameters:

  • source_model_directory (str) – The path to the directory containing HEC-RAS project, plan, geometry, and flow files.

  • submodel_directory (str) – The path to export submodel HEC-RAS files to.

  • nwm_id (int) – The id of the NWM reach to create a submodel for

  • model_name (str) – The name of the HEC-RAS model.

  • min_flow_multiplier_ras (float) – Number that will be multiplied by the RAS min modeled flow. Default is 1

  • max_flow_multiplier_ras (float) – Number that will be multiplied by the RAS max modeled flow. Default is 1

  • ignore_ras_flows (bool) – Whether to ignore HEC-RAS min and max flow when defining flow ranges. Default is False

  • ignore_nwm_flows (bool) – Whether to ignore NWM min and max flow when defining flow ranges. Default is False

Returns:

Metadata for the submodel

Return type:

dict

Raises:

  • FileNotFoundError – Raised when no geopackage is found in the source model directory

  • FileNotFoundError – Raised when no .conflation.json is found in the source model directory

Module contents#

Initialize ops.

On this page
Show Source