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', overviews=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”

  • overviews (bool, optional) – whether to generate overviews 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.fim_lib_item(item_id, assets, stac_json, metadata)#

Create a PySTAC Item for a fim_lib_item.

Return type:

Item

Parameters:

  • (str) (stac_json)

  • (str)

  • (str)

Returns:

pystac.Item: The PySTAC Item representing the raster file. The Item has an Asset with the raster file, the title set to the name of the raster file, the media type set to COG, and the role set to “ras-depth-grid”. The Asset’s extra fields are updated with the basic object metadata of the raster file and the metadata of the raster file. The Item’s bbox is set to the geographic bounds of the raster file in the WGS 84 (EPSG:4326) coordinate reference system, the datetime is set to the current datetime, and the geometry is set to the GeoJSON representation of the bbox.

ripple1d.ops.fim_lib.fim_lib_stac(ras_project_directory, nwm_reach_id, s3_prefix=None, bucket=None)#

Create a stac item for a fim library.

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

Find missing depth grids.

ripple1d.ops.fim_lib.nwm_reach_model_stac(ras_project_directory, ras_model_s3_prefix=None, bucket=None)#

Convert a FIM RAS model to a STAC item.

ripple1d.ops.fim_lib.post_process_depth_grids(rm, plan_name, dest_directory, accept_missing_grid=False, overviews=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.fim_lib.update_stac_s3_location(stac_item_file, bucket, s3_prefix)#

Update the href locations for a stac item and its assets.

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, 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.

  • 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.conflate_model(source_model_directory, source_network)#

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.

  • 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:

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 1.2 times the high flow threshold listed for the reach in the NWM network. The high flow is 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.conflated(metadata)#

Determine if any reaches conflated.

Return type:

bool

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)#

Bases: object

Subset a geopackage based on conflation with NWM hydrofabric.

property conflation_parameters: dict#

Extract conflation parameters from the conflation json.

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_rs: str#

Extract downstream river station from conflation parameters.

junctions_to_dicts()#

Make dicts that map trib->outflow and trib->d/s distance for all junctions.

Return type:

tuple[dict, dict]

property juntion_dist_dict: dict#

Create a dictionary mapping trib->outflow for all junctions.

property juntion_tree_dict: dict#

Create a dictionary mapping trib->outflow for all junctions.

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.

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_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_river: GeoDataFrame#

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

property subset_structures: GeoDataFrame | None#

Extract structures between u/s and d/s limits.

property subset_xs: GeoDataFrame#

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

trim_reach(reach_xs)#

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

Return type:

GeoDataFrame

update_ripple1d_parameters(rsd)#

Update ripple1d_parameters with results of subsetting.

update_river_station(subset_gdfs)#

Convert river stations to autoincrementing names.

Return type:

dict

property us_reach: str#

Extract upstream reach from conflation parameters.

property us_river: str#

Extract upstream river 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

ripple1d.ops.subset_gpkg.extract_submodel(source_model_directory, submodel_directory, nwm_id)#

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

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

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