easy_vic_build.tools.hydroanalysis_func.hydroanalysis_wbw.stream_network

Stream-network extraction and threshold utilities.

Functions

calculate_streamnetwork_threshold(flow_acc_path)

Estimate a stream-extraction threshold from flow accumulation.

clip_stream_for_basin(wbe, stream_vector, ...)

Clip stream vectors by a basin polygon and save the clipped output.

d8_streamnetwork(wbe, flow_acc, ...[, ...])

Extract and analyze a D8-based stream network.

threshold_drainage_area(dem_path, flow_acc_path)

Calculate threshold from a minimum drainage-area constraint.

threshold_dynamic_elbow(flow_acc[, ...])

Calculate threshold using curvature-based elbow detection.

threshold_max_ratio(flow_acc, max_ratio)

Calculate threshold as a fraction of maximum flow accumulation.

threshold_multiscale(flow_acc, scale_levels)

Calculate threshold using a multi-scale adaptive approach.

threshold_percentile(flow_acc, percentile)

Calculate threshold from a percentile of flow accumulation.
easy_vic_build.tools.hydroanalysis_func.hydroanalysis_wbw.stream_network.d8_streamnetwork(wbe, flow_acc, flow_direction, filled_dem, stream_acc_threshold=100.0, output_file_stream_raster='stream_raster.tif', output_file_stream_raster_vector='stream_raster_vector.shp', output_file_stream_raster_link='stream_raster_link.tif', output_file_stream_vector='stream_vector.shp', output_file_stream_vector_repaired='stream_vector_repaired.shp', output_file_stream_lines_vector='stream_lines_vector.shp', output_file_confluences_points_vector='confluences_points_vector.shp', output_file_outlet_points_vector='outlet_points_vector.shp', output_file_channel_head_points_vector='channel_head_points_vector.shp', kwargs_extract_streams={}, kwargs_vector_stream_network_analysis={}, snap_dist=0.001, esri_pointer=True)[source]

Extract and analyze a D8-based stream network.

Parameters:

  • wbe (WbEnvironment) – WhiteboxTools workflow environment instance.

  • flow_acc (WbRaster) – Flow-accumulation raster or raster object.

  • flow_direction (WbRaster) – D8 flow-direction raster or raster object.

  • filled_dem (WbRaster) – Hydrologically conditioned DEM raster or raster object.

  • stream_acc_threshold (float, optional) – Flow-accumulation threshold for stream initiation.

  • output_file_stream_raster (str, optional) – Output path for stream raster.

  • output_file_stream_raster_vector (str, optional) – Output path for vectorized stream raster.

  • output_file_stream_raster_link (str, optional) – Output path for stream-link raster.

  • output_file_stream_vector (str, optional) – Output path for stream vector before topology repair.

  • output_file_stream_vector_repaired (str, optional) – Output path for repaired stream vector.

  • output_file_stream_lines_vector (str, optional) – Output path for stream-line vector.

  • output_file_confluences_points_vector (str, optional) – Output path for confluence points vector.

  • output_file_outlet_points_vector (str, optional) – Output path for outlet points vector.

  • output_file_channel_head_points_vector (str, optional) – Output path for channel-head points vector.

  • kwargs_extract_streams (dict, optional) – Additional keyword arguments passed to wbe.extract_streams.

  • kwargs_vector_stream_network_analysis (dict, optional) – Additional keyword arguments passed to wbe.vector_stream_network_analysis.

  • snap_dist (float, optional) – Snap distance used in topology repair and vector network analysis.

  • esri_pointer (bool, optional) – Whether flow_direction uses ESRI D8 pointer encoding.

Returns:

(stream_raster, stream_vector, repaired_stream_vector, vector_stream_network_analysis_result).

Return type:

tuple

Notes

filled_dem should be hydrologically conditioned before use.

easy_vic_build.tools.hydroanalysis_func.hydroanalysis_wbw.stream_network.calculate_streamnetwork_threshold(flow_acc_path, dem_path=None, method='hybrid', **kwargs)[source]

Estimate a stream-extraction threshold from flow accumulation.

Parameters:

  • flow_acc_path (str) – Path to the flow-accumulation raster file.

  • dem_path (str, optional) – Path to DEM raster. Required when method='drainage_area'.

  • method ({'hybrid', 'max_ratio', 'percentile', 'drainage_area', 'dynamic_elbow', 'multiscale'}, optional) – Threshold estimation method.

  • **kwargs (dict, optional) – Optional method parameters: max_ratio, percentile, drainage_area_km2, elbow_sensitivity, and scale_levels.

Returns:

Stream-extraction threshold in flow-accumulation units.

Return type:

float

Raises:

  • ValueError – If method is not supported.

  • RuntimeError – If no valid flow-accumulation values are found, or DEM is missing for method='drainage_area'.

easy_vic_build.tools.hydroanalysis_func.hydroanalysis_wbw.stream_network.threshold_max_ratio(flow_acc, max_ratio)[source]

Calculate threshold as a fraction of maximum flow accumulation.

Parameters:

  • flow_acc (numpy.ndarray) – Flow-accumulation values.

  • max_ratio (float) – Ratio applied to the maximum value.

Returns:

Threshold value.

Return type:

float

easy_vic_build.tools.hydroanalysis_func.hydroanalysis_wbw.stream_network.threshold_percentile(flow_acc, percentile)[source]

Calculate threshold from a percentile of flow accumulation.

Parameters:

  • flow_acc (numpy.ndarray) – Flow-accumulation values.

  • percentile (float) – Percentile value in [0, 100].

Returns:

Threshold value.

Return type:

float

easy_vic_build.tools.hydroanalysis_func.hydroanalysis_wbw.stream_network.threshold_drainage_area(dem_path, flow_acc_path, drainage_area_km2=0.1, max_ratio=0.1, min_cells=30)[source]

Calculate threshold from a minimum drainage-area constraint.

Parameters:

  • dem_path (str) – Path to DEM raster file.

  • flow_acc_path (str) – Path to flow-accumulation raster file.

  • drainage_area_km2 (float, optional) – Minimum drainage area in square kilometers.

  • max_ratio (float, optional) – Upper-limit ratio relative to maximum flow accumulation.

  • min_cells (int, optional) – Lower bound of threshold in cell count.

Returns:

Threshold value.

Return type:

float

easy_vic_build.tools.hydroanalysis_func.hydroanalysis_wbw.stream_network.threshold_dynamic_elbow(flow_acc, elbow_sensitivity=0.3)[source]

Calculate threshold using curvature-based elbow detection.

Parameters:

  • flow_acc (numpy.ndarray) – Flow-accumulation values.

  • elbow_sensitivity (float, optional) – Sensitivity factor applied to the detected elbow value.

Returns:

Threshold value.

Return type:

float

easy_vic_build.tools.hydroanalysis_func.hydroanalysis_wbw.stream_network.threshold_multiscale(flow_acc, scale_levels)[source]

Calculate threshold using a multi-scale adaptive approach.

Parameters:

  • flow_acc (numpy.ndarray) – Flow-accumulation values.

  • scale_levels (list of float) – Proportions used to build sub-scale masks.

Returns:

Mean threshold across scales.

Return type:

float

easy_vic_build.tools.hydroanalysis_func.hydroanalysis_wbw.stream_network.clip_stream_for_basin(wbe, stream_vector, basin_vector, output_file_clipped_stream_vector='clipped_stream_vector.shp')[source]

Clip stream vectors by a basin polygon and save the clipped output.

Parameters:

  • wbe (WbEnvironment) – WhiteboxTools workflow environment.

  • stream_vector (str or WbVector) – Stream layer path or an already loaded stream vector.

  • basin_vector (str or WbVector) – Basin polygon path or an already loaded basin vector.

  • output_file_clipped_stream_vector (str, optional) – Output path for clipped stream vectors.

Returns:

Clipped stream vector object.

Return type:

WbVector