pygeoflood

class src.pygeoflood.PyGeoFlood(dem_path=None, project_dir=None, filtered_dem_path=None, slope_path=None, curvature_path=None, filled_path=None, mfd_fac_path=None, d8_fdr_path=None, basins_path=None, outlets_path=None, flow_skeleton_path=None, curvature_skeleton_path=None, combined_skeleton_path=None, cost_function_geodesic_path=None, geodesic_distance_path=None, channel_heads_path=None, flowline_path=None, endpoints_path=None, binary_hand_path=None, custom_flowline_path=None, custom_flowline_raster_path=None, channel_network_path=None, channel_network_raster_path=None, cost_function_channel_path=None, hand_path=None, segmented_channel_network_path=None, segmented_channel_network_raster_path=None, segment_catchments_raster_path=None, river_attributes_path=None, segment_catchments_path=None, catchment_path=None, src_path=None, streamflow_forecast_path=None, flood_stage_path=None, fim_path=None, config=None)

A class to implement the height above nearest drainage method

apply_nonlinear_filter(custom_path: str | PathLike = None, method: str = 'PeronaMalik2', smoothing_quantile: float = 0.9, time_increment: float = 0.1, n_iter: int = 50, sigma_squared: float = 0.05)

Apply nonlinear filter to DEM. The dem_path attribute must be set before calling this method.

Parameters

custom_pathstr, os.PathLike, optional

Custom path to save filtered DEM. If not provided, filtered DEM will be saved in project directory.

methodstr, optional

Filter method to apply to DEM. Options include: - “PeronaMalik1”: TODO: detailed description - “PeronaMalik2”: TODO: detailed description - “Gaussian”: Smoothes DEM with a Gaussian filter. Default is “PeronaMalik2”.

smoothing_quantilefloat, optional

Quantile for calculating Perona-Malik nonlinear filter edge threshold value (kappa). Default is 0.9.

time_incrementfloat, optional

Time increment for Perona-Malik nonlinear filter. Default is 0.1. AKA gamma, a higher makes diffusion process faster but can lead to instability.

n_iterint, optional

Number of iterations for Perona-Malik nonlinear filter. Default is 50.

sigma_squaredfloat, optional

Variance of Gaussian filter. Default is 0.05.

calculate_binary_hand(custom_path: str | PathLike = None)

Creates binary HAND raster with values of 1 given to pixels at a lower elevation than the NHD MR Flowline pixels they drain to (shortest D8 path). A value of zero is given to all other pixels in the image, i.e. pixels at a higher elevation than the NHD MR Flowlines.

Parameters

custom_pathstr, os.PathLike, optional

Custom path to save binary HAND raster. If not provided, binary HAND raster will be saved in project directory.

calculate_curvature(custom_path: str | PathLike = None, method: str = 'geometric')

Calculate curvature of DEM.

Parameters

custom_pathstr, os.PathLike, optional

Custom path to save curvature raster. If not provided, curvature raster will be saved in project directory.

methodstr, optional

Method for calculating curvature. Options include: - “geometric”: TODO: detailed description - “laplacian”: TODO: detailed description Default is “geometric”.

calculate_d8_flow_direction(custom_path: str | PathLike = None, **wbt_args)

Calculate D8 flow direction. This is a wrapper for the WhiteboxTools d8_pointer function.

Parameters

custom_pathstr, os.PathLike, optional

Path to save D8 flow direction raster. If not provided, D8 flow direction raster will be saved in project directory.

wbt_argsdict, optional

Additional arguments to pass to the WhiteboxTools d8_pointer function. See WhiteboxTools documentation for details.

calculate_flood_stage(custom_path: str | PathLike = None, custom_Q: int | float = None)

Calculate flood stage for each segment of the channel network. Forecasted streamflow values for each COMID (feature ID) must be set in PyGeoFlood.streamflow_forecast_path before running if custom_Q is not set. If the streamflow forecast is a netCDF file it must be in NWM format (in xarray: ‘streamflow’ variable with a “feature_id” or “COMID” dim/coord). If the streamflow forecast is a CSV file, it must have columns “feature_id” (or “COMID”) and “streamflow”.

Parameters

custom_pathstr, os.PathLike, optional

Custom path to save flood stage interpolated from synthetic rating curves. If not provided, flood stage will be saved in project directory.

custom_Qint or float, optional

Constant streamflow value to assign to all segments. Default is None. If set, custom_Q will be used to calculate flood stage instead of forecasted streamflow values.

calculate_geodesic_distance(custom_path: str | PathLike = None, write_cost_function: bool = False, basin_elements: int = 2, area_threshold: float = 0.1, normalize_curvature: bool = True, local_cost_min: float | None = None)

Calculate geodesic distance.

Parameters

custom_pathstr, os.PathLike, optional

Path to save geodesic distance raster. If not provided, geodesic distance raster will be saved in project directory.

write_cost_functionbool, optional

Whether to write cost function raster to file. Default is False.

basin_elementsint, optional

Number of basin elements. Default is 2.

area_thresholdfloat, optional

Area threshold for fast marching method. Default is 0.1.

normalize_curvaturebool, optional

Whether to normalize curvature. Default is True.

local_cost_minfloat, optional

Minimum local cost. Default is None.

calculate_hand(custom_path: str | PathLike = None, **wbt_args)

Calculate Height Above Nearest Drainage (HAND). Returns a raster with each cell’s vertical elevation above its nearest stream cell, measured along the downslope D8 flowpath from the cell. This is a wrapper for the WhiteboxTools elevation_above_stream function.

Parameters

custom_pathstr, os.PathLike, optional

Path to save HAND raster. If not provided, basins raster will be saved in project directory.

wbt_argsdict, optional

Additional arguments to pass to the WhiteboxTools elevation_above_stream function. See WhiteboxTools documentation for details.

calculate_mfd_flow_accumulation(custom_path: str | PathLike = None, **wbt_args)

Calculate MFD flow accumulation. This is a wrapper for the WhiteboxTools quinn_flow_accumulation function.

Parameters

mfd_fac_pathstr, os.PathLike, optional

Path to save MFD flow accumulation raster. If not provided, MFD flow accumulation raster will be saved in project directory.

wbt_argsdict, optional

Additional arguments to pass to the WhiteboxTools quinn_flow_accumulation function. See WhiteboxTools documentation for details.

calculate_slope(custom_path: str | PathLike = None)

Calculate slope of DEM.

Parameters

custom_pathstr, os.PathLike, optional

Custom path to save slope raster. If not provided, slope raster will be saved in project directory.

calculate_src(custom_path: str | PathLike = None, min_slope: float = 1e-06, max_stage: float = 20, incr_stage: float = 0.1, custom_roughness_path: str | PathLike = None)

Calculate synthetic rating curves (SRC) for each segment of the channel network. The SRC are based on the channel geometry attributes and the stage-height relationship. The SRC are written to a csv file.

Parameters

custom_pathstr, os.PathLike, optional

Custom path to save synthetic rating curves. If not provided, SRC will be saved in project directory.

min_slopefloat, optional

Minimum slope allowed on channel segments. Default is 0.000001.

max_stagefloat, optional

Maximum stage height in SRC. Default is 20.

incr_stagefloat, optional

Increment with which to calculate SRC, from 0 to max_stage. Default is 0.1.

custom_roughness_pathstr, os.PathLike, optional

Custom path to a csv file with roughness, a.k.a. Manning’s n values for each COMID in the study area. Must have columns “COMID” and “Roughness”. If not provided, default Manning’s n values, which have been determined for each COMID in CONUS, will be used. These default roughness values are determined from stream order:

stream order | roughness ———— | ——— 1 | 0.200 2 | 0.100 3 | 0.065 4 | 0.045 5 | 0.030 6 | 0.010 7 | 0.025

property config

Getter for the config property. Returns the PGF_Config instance.

define_skeleton(custom_path: str | PathLike = None, fac_threshold: float = 3000, write_flow_skeleton: bool = False, write_curvature_skeleton: bool = False)

Define skeleton from flow and curvature.

Parameters

custom_pathstr, os.PathLike, optional

Custom path to save combined skeleton. If not provided, combined skeleton will be saved in project directory.

fac_thresholdfloat, optional

Flow accumlulation threshold for defining flow skeleton. Default is 3000.

write_flow_skeletonbool, optional

Whether to write flow skeleton to file. Default is False.

write_curvature_skeletonbool, optional

Whether to write curvature skeleton to file. Default is False.

delineate_basins(custom_path: str | PathLike = None, **wbt_args)

Delineate basins. This is a wrapper for the WhiteboxTools basins function.

Parameters

custom_pathstr, os.PathLike, optional

Path to save basins raster. If not provided, basins raster will be saved in project directory.

wbt_argsdict, optional

Additional arguments to pass to the WhiteboxTools basins function. See WhiteboxTools documentation for details.

delineate_segment_catchments(custom_path: str | PathLike = None, **wbt_args)

Delineate catchments for each segment of the channel network. The D8 flow direction raster and segmented channel network vector are required to run delineate_segment_catchments. This is a wrapper for the WhiteboxTools watershed function.

Parameters

custom_pathstr, os.PathLike, optional

Custom path to save segment catchments raster. If not provided, segment catchments will be saved in project directory.

wbt_argsdict, optional

Additional arguments to pass to the WhiteboxTools

extract_channel_network(custom_path: str | PathLike = None, vector_extension: str = 'shp', write_cost_function: bool = False, use_custom_flowline: bool = False, no_flowline: bool = False, custom_weight_curvature: float | None = None, custom_weight_mfd_fac: float | None = None, custom_weight_binary_hand: float | None = None, custom_weight_custom_flowline: float | None = None)

Extract channel network. The channel network will be written to raster and vector datasets with the same name and different extensions. By default, curvature, flow accumulation, and binary HAND (information from NHD MR flowline) are used to calculate the cost function. A custom flowline such as the NHD HR flowline can be included in the cost function with use_custom_flowline=True. Only curvature and flow accumulataion will be considered if no_flowline=True. The cost function is calculated as the reciprocal of the weighted sum of these of these rasters. The cost function is thresholded and used to extract the channel network.

Parameters

custom_pathstr, os.PathLike, optional

Custom path to save channel network raster. If not provided, channel network raster will be saved in project directory. The channel network vector file will have an identical name and path, but with the extension vector_extension (shp by default).

vector_extensionstr, optional

Extension for vector file. Default is “shp”.

write_cost_functionbool, optional

Whether to write cost function raster to file. Default is False.

use_custom_flowlinebool, optional

Whether to use custom flowline raster in cost function. Default is False.

no_flowlinebool, optional

Whether to use the NHD MR flowline information (binary HAND raster) in the cost function. Default is False, so binary HAND raster will be used by default.

custom_weight_curvaturefloat, optional

Custom weight for curvature in cost function. Default is None.

custom_weight_mfd_facfloat, optional

Custom weight for flow accumulation in cost function. Default is None.

custom_weight_binary_handfloat, optional

Custom weight for binary HAND in cost function. Default is None.

custom_weight_custom_flowlinefloat, optional

Custom weight for custom flowline in cost function. Default is None.

fill_depressions(custom_path: str | PathLike = None, **wbt_args)

Fill filtered DEM depressions. This is a wrapper for the WhiteboxTools fill_depressions function.

Parameters

custom_pathstr, os.PathLike, optional

Path to save filled DEM. If not provided, filled DEM will be saved in project directory.

wbt_argsdict, optional

Additional arguments to pass to the WhiteboxTools fill_depressions function. See WhiteboxTools documentation for details.

find_endpoints(custom_path: str | PathLike = None)

Save flowline endpoints in a csv file.

Parameters

custom_pathstr, os.PathLike, optional

Custom path to save endpoints csv. If not provided, endpoints csv will be saved in project directory.

find_outlets(custom_path: str | PathLike = None)

Create outlets raster. Outlets are cells which have no downslope neighbors according to the D8 flow direction. Outlets are designated by 1, all other cells are designated by 0.

Parameters

custom_pathstr, os.PathLike, optional

Path to save outlets raster. If not provided, outlets raster will be saved in project directory.

identify_channel_heads(custom_path: str | PathLike = None, channel_head_median_dist: int = 30, vector_extension: str = 'shp', max_channel_heads: int = 10000)

Define channel heads.

Parameters

custom_pathstr, os.PathLike, optional

Custom path to save channel heads shapefile. If not provided, channel heads shapefile will be saved in project directory.

channel_head_median_distint, optional

Median hillslope of the input DEM, i.e. the distance between each pixel and the first channelized downslope pixel. Default is 30.

vector_extensionstr, optional

Extension for vector file. Default is “shp”.

max_channel_headsint, optional

Maximum number of channel heads to extract. Default is 10000. (useful for pre-allocation of memory for large rasters)

inundate(custom_path: str | PathLike = None)

Calculate flood inundation raster based on HAND and flood stage.

Parameters

custom_pathstr, os.PathLike, optional

Custom path to save flood inundation raster. If not provided, flood inundation raster will be saved in project directory.

rasterize_custom_flowline(custom_path: str | PathLike = None, layer: str | int = 0)

Create custom flowline raster from user-provided flowline vector file. This flowline could be obtained from the NHD HR dataset, for example. The attribute custom_flowline_path must be set before running this method. The flowline is buffered by 5 units and cropped to the extent of the DEM. The crs of the flowline will be reprojected to the crs of the DEM. Note: if you already have a custom flowline raster, you can skip this step and set the custom_flowline_raster_path attribute directly.

Parameters

custom_pathstr, os.PathLike, optional

Custom path to save custom flowline raster. If not provided, custom flowline raster will be saved in project directory. The flowline raster has data type int16 with 1=channel and 0=non-channel.

layerstr or int, optional

Layer name or number in flowline vector file. Default is 0.

run_fim_workflow()

Run the full PyGeoFlood workflow.

segment_channel_network(custom_path: str | PathLike = None, vector_extension: str = 'shp', segment_length: int | float = 1000)

Divide channel network into segments of a specified length.

Parameters

custom_pathstr, os.PathLike, optional

Custom path to save segmented channel network. If not provided, segmented channel network will be saved in project directory.

vector_extensionstr, optional

Extension for vector file. Default is “shp”.

segment_lengthint or float, optional

Length of segments. Default is 1000 units.