pygeoflood

class src.pygeoflood.PyGeoFlood(dem_path, project_dir=None, config=None)

A class to implement the height above nearest drainage method

apply_nonlinear_filter(custom_dem: str | PathLike = None, 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_demstr, os.PathLike, optional

Custom file path for input DEM. If not provided, default DEM used. A custom_path is required when a custom_dem is provided.

custom_pathstr, os.PathLike, optional

Custom file 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_dem: str | PathLike = None, custom_flowline: str | PathLike = None, 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_demstr, os.PathLike, optional

Custom file path to input dem. If not provided default dem is used. A custom_path is required when a custom_dem is provided.

custom_flowlinestr, os.PathLike, optional

Custom file path to input flowlines. If not provided default flowline is used. A custom_path is required when a custom_flowline is provided.

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_filtered_dem: str | PathLike = None, custom_path: str | PathLike = None, method: str = 'geometric')

Calculate curvature of DEM.

Parameters

custom_filtered_demstr, os.PathLike, optional

Custom file path for input filtered dem. If not provided default filtered_dem is used. A custom_path is required when a custom_filtered_dem is provided.

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_filled_dem: str | PathLike = None, custom_filtered_dem: str | PathLike = None, custom_path: str | PathLike = None, **wbt_args)

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

Parameters

custom_filled_demstr, os.PathLike, optional

Custom file path for input filled dem. If not provided default filled_dem is used. A custom_path is required when a custom_filtered_dem is provided.

custom_filtered_demstr, os.PathLike, optional

Custom file path for input filtered dem. If not provided default filtered_dem is used. A custom_path is required when a custom_filtered_dem is provided.

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_src: str | PathLike = None, custom_streamflow_forecast_path: str | PathLike = None, 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_srcstr, os.PathLike, optional

Custom file path to input synthetic rating curve. If not provided default src is used. A custom_path is required when a custom_src is provided.

custom_streamflow_forecast_pathstr, os.PathLike, optional

Custom file path to input streamflow_forecast_path. If not provided default is used. A custom_path is required when a custom_streamflow_forecast_path is provided.

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_curvature: str | PathLike = None, custom_mfd_fac: str | PathLike = None, custom_outlets: str | PathLike = None, custom_basins: str | PathLike = None, custom_combined_skeleton: str | PathLike = None, custom_filtered_dem: str | PathLike = None, 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_curvaturestr, os.PathLike, optional

Custom file path to input curvature. If not provided default curvature is used. A custom_path is required when a custom_curvature is provided.

custom_mfd_facstr, os.PathLike, optional

Custom file path to input mfd_fac. If not provided default mfd_fac is used. A custom_path is required when a custom_mfd_fac is provided.

custom_outletsstr, os.PathLike, optional

Custom file path to input outlets. If not provided default outlets is used. A custom_path is required when a custom_outlets is provided.

custom_basinsstr, os.PathLike, optional

Custom file path to input basins. If not provided default basins is used. A custom_path is required when a custom_basins is provided.

custom_combined_skeletonstr, os.PathLike, optional

Custom file path to input skeleton. If not provided default combined skeleton is used. A custom_path is required when a custom_combined_skeleton is provided.

custom_filtered_dem: str, os.PathLike, optional

Custom file path to input filtered dem. If not provided default filtered dem is used. A custom_path is required when a custom_filtered_dem is provided.

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_filled_dem: str | PathLike = None, custom_channel_network_raster: str | PathLike = None, 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_filled_demstr, os.PathLike, optional

Custom file path to input filled dem. If not provided default filled_dem is used. A custom_path is required when a custom_filled_dem is provided.

custom_channel_network_rasterstr, os.PathLike, optional

Custom file path to input channel network raster. If not provided default channel_network_raster is used. A custom_path is required when a custom_channel_network_raster is provided.

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_filled_dem: str | PathLike = None, custom_path: str | PathLike = None, **wbt_args)

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

Parameters

custom_filled_demstr, os.PathLike, optional

Custom file path for input filled dem. If not provided default filled_dem is used. A custom_path is required when a custom_filled_dem is provided.

custom_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_filtered_dem: str | PathLike = None, custom_path: str | PathLike = None)

Calculate slope of DEM.

Parameters

custom_filtered_demstr, os.PathLike, optional

Custom file path for input filtered dem. If not provided default filtered_dem is used. A custom_path is required when a custom_filtered_dem is provided.

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_dem: str | PathLike = None, custom_segmented_channel_network: str | PathLike = None, custom_segment_catchments_raster: str | PathLike = None, custom_catchments: str | PathLike = None, custom_hand: str | PathLike = None, 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_demstr, os.PathLike, optional

Custom file path to input dem. If not provided default DEM is used. A custom_path is required when a custom_dem is provided.

custom_segmented_channel_network_pathstr, os.PathLike, optional

Custom file path to input segmented channel network path. If not provided default is used. A custom_path is required when a custom_segmented_channel_network_path is provided.

custom_segment_catchments_rasterstr, os.PathLike, optional

Custom file path to input segmented catchment raster path. If not provided default is used. A custom_path is required when a custom_segment_catchments_raster is provided.

custom_catchments: str, os.PathLike, optional

Custom file path to input catchments. If not provided default catchments is used. A custom_path is required when a custom_catchments is provided.

custom_handstr, os.PathLike, optional

Custom file path to input HAND. If not provided default hand is used. A custom_path is required when a custom_hand is provided.

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_curvature: str | PathLike = None, custom_mfd_fac: str | PathLike = None, 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_curvaturestr, os.PathLike, optional

Custom file path for input curvature. If not provided default curvature is used. A custom_path is required when a custom_curvature is provided.

custom_mfd_facstr, os.PathLike, optional

Custom file path for input mfd_fac. If not provided default mfd_fac is used. A custom_path is required when a custom_mfd_fac is provided.

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_d8_fdr: str | PathLike = None, custom_path: str | PathLike = None, **wbt_args)

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

Parameters

custom_d8_fdrstr, os.PathLike, optional

Custom file path for input d8 flow direction. If not provided default d8_fdr is used. A custom_path is required when a custom_d8_fdr is provided.

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_segmented_channel_network: str | PathLike = None, custom_d8_fdr: str | PathLike = None, 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_segmented_channel_network_pathstr, os.PathLike, optional

Custom file path to input segmented channel network path. If not provided default is used. A custom_path is required when a custom_segmented_channel_network_path is provided.

custom_d8_fdrstr, os.PathLike, optional

Custom file path to input d8 fdr. If not provided default d8_fdr is used. A custom_path is required when a custom_d8_fdr is provided.

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_flowline: str | PathLike = None, custom_curvature: str | PathLike = None, custom_mfd_fac: str | PathLike = None, custom_endpoints: str | PathLike = None, custom_binary_hand: str | PathLike = None, custom_path: str | PathLike = None, retrace_flowline: bool = True, 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_flowlinestr, os.PathLike, optional

Custom file path to input flowlines. If not provided default flowline is used. Only used if retrace_flowline is False. A custom_path is required when a custom_flowline is provided.

custom_curvaturestr, os.PathLike, optional

Custom file path to input curvature. If not provided default curvature is used. A custom_path is required when a custom_curvature is provided.

custom_mfd_facstr, os.PathLike, optional

Custom file path to input mfd_fac. If not provided default mfd_fac is used. A custom_path is required when a custom_mfd_fac is provided.

custom_endpointsstr, os.PathLike, optional

Custom file path to input endpoints. If not provided default endpoints is used. A custom_path is required when a custom_endpoints is provided.

custom_binary_handstr, os.PathLike, optional

Custom file path to input binary_hand. If not provided default bindary_hand is used. A custom_path is required when a custom_binary_hand is provided.

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

retrace_flowlinebool, optional

Whether to retrace flowline. Default is True. If False, the existing NHD MR flowline will be used as the channel network, no extraction will be performed, and the channel network raster and vector will be written to file. Note: setting this option to False is not recommended, but may apply to specific use cases, such as on low-relief terrain.

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. Does not automatically use custom_flowline shapefile input, The custom_flowline raster should be set by running rasterize_custom_flowline method first.

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_filtered_dem: str | PathLike = None, custom_path: str | PathLike = None, **wbt_args)

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

Parameters

custom_filtered_demstr, os.PathLike, optional

Custom file path for input filtered dem. If not provided default filtered_dem is used. A custom_path is required when a custom_filtered_dem is provided.

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.

fill_spill_merge(uniform_depth: float = 0.5, gridded_depth: str | PathLike = None, custom_dem: str | PathLike = None, overwrite_dephier: bool = False, custom_path: str | PathLike = None)

Runs Fill-Spill-Merge function from RichDEM to simulate pluvial flooding.

The method will save intermediary json files of the depression hierarchy, flow directions, and flow labels to make successive runs faster.

Parameters

uniform_depthfloat

Uniform depth to inundate the landscape. Units will be the units of the DEM. Defaults to 0.5.

gridded_depthstr, os.PathLike, optional

Path to a gridded depth raster to inundate the DEM. If a gridded_depth is provided, the uniform_depth will be ignored. The gridded_depth will be clipped, reprojected, and resampled to have the same resolution as the DEM if it extends past it and is not the same spatial resolution.

custom_demstr, os.PathLike, optional

Custom file path to input dem. If not provided default DEM is used. A custom_path is required when a custom_hand is provided. Intermediary files will be saved to match the name of the input custom_dem and be within the default working folder.

overwrite_dephierbool

If True, fill_spill_merge will overwrite all existing .json files associated with that DEM.

custom_pathstr, os.PathLike, optional

Custom path to save the inundated raster. If not provided, flooded raster will be saved in the project directory with the default name.

find_endpoints(custom_flowline: str | PathLike = None, custom_path: str | PathLike = None)

Save flowline endpoints in a csv file.

Parameters

custom_flowlinestr, os.PathLike, optional

Custom file path to input flowlines. If not provided default flowline is used. A custom_path is required when a custom_flowline is provided.

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_d8_fdr: str | PathLike = None, 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_d8_fdrstr, os.PathLike, optional

Custom file path for input d8 flow direction. If not provided default d8_fdr is used. A custom_path is required when a custom_d8_fdr is provided.

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_combined_skeleton: str | PathLike = None, custom_geodesic_distance: str | PathLike = None, 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_combined_skeletonstr, os.PathLike, optional

Custom file path to input skeleton. If not provided default combined skeleton is used. A custom_path is required when a custom_combined_skeleton is provided.

custom_geodesic_distancestr, os.PathLike, optional

Custom file path to input geodesic distsance. If not provided default geodesic distance is used. A custom_path is required when a custom_geodesic_distance is provided.

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_hand: str | PathLike = None, custom_flood_stage: str | PathLike = None, custom_segment_catchments_raster: str | PathLike = None, custom_path: str | PathLike = None)

Calculate flood inundation raster based on HAND and flood stage.

Parameters

custom_handstr, os.PathLike, optional

Custom file path to input sHAND. If not provided default HAND is used. A custom_path is required when a custom_hand is provided.

custom_flood_stagestr, os.PathLike, optional

Custom file path to input flood stage. If not provided default is used. A custom_path is required when a custom_flood_stage is provided.

custom_segment_catchmentsstr, os.PathLike, optional

Custom file path to input segment_catchments. If not provided default is used. A custom_path is required when a custom_segment_catchments is provided.

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_flowline: str | PathLike = None, 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. Used to set the path properties self.custom_flowline_path and self.custom_flowline_raster_path

Parameters

custom_flowlinestr, os.PathLike, optional

Custom file path to input flowlines. If not provided default custom_flowline is used. A custom_path is required when a custom_flowline is provided.

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. Default path is project directory with suffix _custom_flowline.shp and _custom_flowline.tif

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_channel_network_vector: str | PathLike = None, 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_channel_network_vectorstr, os.PathLike, optional

Custom file path to input channel network vector. If not provided default channel_network_vector is used. A custom_path is required when a custom_channel_network_vector is provided.

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.