BasinMaker developer documentation

BasinMaker - postprocessing tools

Extract the region of interest

basinmaker.basinmaker.postprocess.Select_Subregion_Of_Routing_Structure(path_output_folder, routing_product_folder, gis_platform, most_down_stream_subbasin_ids=[], most_up_stream_subbasin_ids=[])

Select subregion of hydrologic routing network based on provided subbasin IDs

Parameters:

• path_output_folder (string) – is the folder path that stores generated outputs

• routing_product_folder (string) – is the folder path where the input hydrologic routing network is stored

• gis_platform (string) – is the parameter indicating which gis platform is used. It can be either “qgis” or “arcgis”.

• most_down_stream_subbasin_ids (list) – A list of subbasin ID, the subbasin IDs in this list should be the most downstream subbasin ID of each interested watershed.

• most_up_stream_subbasin_ids (list) – A list of subbasin ID, the subbasins that drainage to the SubID in this list will be excluded. Value [-1] is required to indicate no upstream subbasin needs to be removed.

Notes

This function has no return values, The extracted hydrological routing network will be generated in the path_output_folder including following files:

finalcat_info.shpshapefile

The finalized hydrologic routing network. the GIS layer containing subbasin polygons which respect the lake inflow and outflow routing structures. This layer contains all the necessary information for hydrologic routing through the lake-river network.

finalcat_info_riv.shpshapefile

The finalized hydrologic routing network. the GIS layer containing river network polylines in the routing network.

catchment_without_merging_lakes.shpshapefile

The GIS layer containing subbasin polygons of an incomplete hydrologic routing network. In this incomplete hydrologic routing network subbasin polygons covered by the same lake are not merged into one lake subbasin yet. This incomplete hydrologic routing network is only intended as input to customize the routing network with our BasinMaker GIS toolbox (for example by defining new lake area thresholds and/or a new catchment minimum drainage area threshold)

river_without_merging_lakes.shpshapefile

The GIS layer containing river polylines of an incomplete hydrologic routing network. In this incomplete hydrologic routing network, the river polylines covered by the same lake are not merged into one river segment yet. This incomplete hydrologic routing network is only intended as input to customize the routing network with our BasinMaker GIS toolbox (for example by defining new lake area thresholds and/or a new catchment minimum drainage area threshold)

sl_connected_lake.shpshapefile

the GIS layer containing the lake polygons of lakes that are connected by the river_without_merging_lakes.shp

sl_non_connected_lake.shpshapefile

the GIS layer containing the lake polygons of lakes that are not connected by the river_without_merging_lakes.shp

poishapefile

It is the point shapefile that represent the point of interest after snap to river network.

Examples

Filter lakes

basinmaker.basinmaker.postprocess.Remove_Small_Lakes(path_output_folder, routing_product_folder, gis_platform, connected_lake_area_thresthold=-1, non_connected_lake_area_thresthold=-1, selected_lake_ids=[], area_thresthold=0.009)

This function is to simplify the hydrologic routing network by removing lakes.

Parameters:

• path_output_folder (string) – is the folder path that stores generated outputs

• routing_product_folder (string) – is the folder path where the input hydrologic routing network is stored

• gis_platform (string) – is the parameter indicating which gis platform is used. It can be either “qgis” or “arcgis”.

• connected_lake_area_thresthold (float (optional)) – is a lake area thresthold for connected lakes in km2. Connected lake with lake area below which lake will be removed

• non_connected_lake_area_thresthold (float (optional)) – is a lake area thresthold for non-connected lakes in km2 Non connected lake with lake area below below which lake will be removed

• selected_lake_ids (list (optional)) – A list of lake IDs from in the hydrologic routing network (Column ‘HyLakeId’). Lakes with their lake ID in this list will be kept by the BasinMaker even if their area smaller than the lake area threstholds

• area_thresthold (float (optional)) – This parameter sets a subbasin area threshold in square kilometers (km²). Subbasins with an area below this threshold will be merged with downstream or upstream subbasins, depending on their location within the river network. This can be useful for simplifying the river network and reducing computational requirements. The parameter is optional and has a default value of 0.009 km2. If the parameter is set to 0, no subbasin merging will be performed.

Notes

This function has no return values, The simplified hydrological routing network will be generated in the path_output_folder including following files:

finalcat_info.shpshapefile

The finalized hydrologic routing network. the GIS layer containing subbasin polygons which respect the lake inflow and outflow routing structures. This layer contains all the necessary information for hydrologic routing through the lake-river network.

finalcat_info_riv.shpshapefile

The finalized hydrologic routing network. the GIS layer containing river network polylines in the routing network.

catchment_without_merging_lakes.shpshapefile

The GIS layer containing subbasin polygons of an incomplete hydrologic routing network. In this incomplete hydrologic routing network subbasin polygons covered by the same lake are not merged into one lake subbasin yet. This incomplete hydrologic routing network is only intended as input to customize the routing network with our BasinMaker GIS toolbox (for example by defining new lake area thresholds and/or a new catchment minimum drainage area threshold)

river_without_merging_lakes.shpshapefile

The GIS layer containing river polylines of an incomplete hydrologic routing network. In this incomplete hydrologic routing network, the river polylines covered by the same lake are not merged into one river segment yet. This incomplete hydrologic routing network is only intended as input to customize the routing network with our BasinMaker GIS toolbox (for example by defining new lake area thresholds and/or a new catchment minimum drainage area threshold)

sl_connected_lake.shpshapefile

the GIS layer containing the lake polygons of lakes that are connected by the river_without_merging_lakes.shp

sl_non_connected_lake.shpshapefile

the GIS layer containing the lake polygons of lakes that are not connected by the river_without_merging_lakes.shp

poishapefile

It is the point shapefile that represent the point of interest after snap to river network.

Examples

Increase catchment area

basinmaker.basinmaker.postprocess.Decrease_River_Network_Resolution(path_output_folder, routing_product_folder, gis_platform, minimum_subbasin_drainage_area, area_thresthold)

This function is to simplify the hydrologic routing network by removing subbasins/river reaches with their drainage area below user provided drainage area thresthold.

Parameters:

• path_output_folder (string) – is the folder path that stores generated outputs

• routing_product_folder (string) – is the folder path where the input hydrologic routing network is stored

• gis_platform (string) – is the parameter indicating which gis platform is used. It can be either “qgis” or “arcgis”.

• minimum_subbasin_drainage_area (float) – is a subbasin drainage area thresthold, subbasin with their drainage area smaller than this thresthold will be removed.

• area_thresthold (float (optional)) – This parameter sets a subbasin area threshold in square kilometers (km²). Subbasins with an area below this threshold will be merged with downstream or upstream subbasins, depending on their location within the river network. This can be useful for simplifying the river network and reducing computational requirements. The parameter is optional and has a default value of 0.009 km2. If the parameter is set to 0, no subbasin merging will be performed.

Notes

This function has no return values, The simplified hydrological routing network will be generated in the path_output_folder including following files:

finalcat_info.shpshapefile

The finalized hydrologic routing network. the GIS layer containing subbasin polygons which respect the lake inflow and outflow routing structures. This layer contains all the necessary information for hydrologic routing through the lake-river network.

finalcat_info_riv.shpshapefile

The finalized hydrologic routing network. the GIS layer containing river network polylines in the routing network.

catchment_without_merging_lakes.shpshapefile

The GIS layer containing subbasin polygons of an incomplete hydrologic routing network. In this incomplete hydrologic routing network subbasin polygons covered by the same lake are not merged into one lake subbasin yet. This incomplete hydrologic routing network is only intended as input to customize the routing network with our BasinMaker GIS toolbox (for example by defining new lake area thresholds and/or a new catchment minimum drainage area threshold)

river_without_merging_lakes.shpshapefile

The GIS layer containing river polylines of an incomplete hydrologic routing network. In this incomplete hydrologic routing network, the river polylines covered by the same lake are not merged into one river segment yet. This incomplete hydrologic routing network is only intended as input to customize the routing network with our BasinMaker GIS toolbox (for example by defining new lake area thresholds and/or a new catchment minimum drainage area threshold)

sl_connected_lake.shpshapefile

the GIS layer containing the lake polygons of lakes that are connected by the river_without_merging_lakes.shp

sl_non_connected_lake.shpshapefile

the GIS layer containing the lake polygons of lakes that are not connected by the river_without_merging_lakes.shp

poishapefile

It is the point shapefile that represent the point of interest after snap to river network.

Examples

Modify point of interest in the routing product

basinmaker.basinmaker.postprocess.Add_Point_Of_Interest_Sites_In_Routing_Product(path_output_folder, routing_product_folder, gis_platform, clean_exist_pois, area_thresthold)

This function allows the user to modify point of interest (POI) sites in a pre-existing BasinMaker-generated user input hydrologic routing network/product. Specific modifications this function can make are to add new POI sites, remove existing POI sites, or modify the location of existing POI sites in the input routing network. This function will use the location of the provided POI and link them to the subbasins in the routing network. At least one POI should be provided in the point shapefile.

Parameters:

• path_output_folder (string) – is the folder path that stores generated outputs

• routing_product_folder (string) – is the folder path where the input hydrologic routing network is stored

• path_to_points_of_interest_points (string) –

  is the path to the point shapefile that contains the point of interest (POI) sites. The shapefile must have an attribute table that includes the following columns:

  • Obs_NM (string): This column should contain the name or ID of the POI site. When the provided POI has the same Obs_NM as the existing POI in the routing product, this function will assume that the user wants to relocate the existing POI. Otherwise, the clean_exist_pois variable below controls whether the new POI sites fully replace existing POI sites or augment the existing POI sites.

  • DA_Obs (float): This column should contain the drainage area of the POI site.

  • SRC_obs (string): This column should contain the source of the POI site.

  • Type (string): This column should contain the type of the POI site. Each POI can only have one type. The following types are currently supported: “Lake”: the POI is located on a lake waterbody surface. “River”: the POI is located on a river channel. Note that the “Lake” type POI should be located within a lake subbasin and the “River” type POI should be located within a non-lake subbasin. The POI located in the wrong subbasin will be ignored and not added to the routing product. The “River” type POI will be linked to a non-lake subbasin that contains the POI. The “Lake” type POI will be linked to the lake subbasin that contains the POI.

• gis_platform (string) – is the parameter indicating which gis platform is used. Currenly, only “purepy” is allowed for this parameter.

• clean_exist_pois (boolean) – Indicates if the user wants to remove all existing POI in the input routing product. When it is true, all existing POI will be removed, and only the POI sites provided in the path_to_points_of_interest_points will be added to the input routing network.

Notes

This function does not return any values. If the user only wants to add POI to the routing product, they should set clean_exist_pois to False. This will keep the existing POI and add the provided POI to the routing product. If the user wants to remove all existing POI and add new POI, they should set clean_exist_pois to True. This will remove all existing POI from the routing product and then add the provided POI to the routing product. The modified hydrological routing network will be generated in the path_output_folder and will include the following files:

finalcat_info.shpshapefile

The finalized hydrologic routing network. the GIS layer containing subbasin polygons which respect the lake inflow and outflow routing structures. This layer contains all the necessary information for hydrologic routing through the lake-river network.

finalcat_info_riv.shpshapefile

The finalized hydrologic routing network. the GIS layer containing river network polylines in the routing network.

catchment_without_merging_lakes.shpshapefile

The GIS layer containing subbasin polygons of an incomplete hydrologic routing network. In this incomplete hydrologic routing network subbasin polygons covered by the same lake are not merged into one lake subbasin yet. This incomplete hydrologic routing network is only intended as input to customize the routing network with our BasinMaker GIS toolbox (for example by defining new lake area thresholds and/or a new catchment minimum drainage area threshold)

river_without_merging_lakes.shpshapefile

The GIS layer containing river polylines of an incomplete hydrologic routing network. In this incomplete hydrologic routing network, the river polylines covered by the same lake are not merged into one river segment yet. This incomplete hydrologic routing network is only intended as input to customize the routing network with our BasinMaker GIS toolbox (for example by defining new lake area thresholds and/or a new catchment minimum drainage area threshold)

sl_connected_lake.shpshapefile

the GIS layer containing the lake polygons of lakes that are connected by the river_without_merging_lakes.shp

sl_non_connected_lake.shpshapefile

the GIS layer containing the lake polygons of lakes that are not connected by the river_without_merging_lakes.shp

poishapefile

It is the point shapefile that represent the point of interest after snap to river network.

Examples

Generate HRUs

basinmaker.basinmaker.postprocess.Generate_HRUs(path_output_folder, gis_platform, path_subbasin_polygon, path_landuse_info, path_soil_info, path_veg_info, prjected_epsg_code='EPSG:3573', path_connect_lake_polygon='#', path_non_connect_lake_polygon='#', path_landuse_polygon='#', path_soil_polygon='#', path_vegetation_polygon='#', path_other_polygon_1='#', area_ratio_thresholds=[0, 0, 0], path_to_dem='#')

This function is to generate HRU map based on subbasin polygon, lake polygon (optional), Land use polygon (optional), soil type polygon(optional), vegetation polygon (optional), and two other user defined polygons (optional).

Parameters:

• path_output_folder (string) – is the folder path that stores generated outputs

• gis_platform (string) – is the parameter indicating which gis platform is used. It can be either “qgis” or “arcgis”.

• path_subbasin_polygon (string) – is the path of the subbasin polygon, which is generated by BasinMaker.

• path_landuse_info (string) –

  Path to a csv file that contains landuse information, including the following attributes:

  Landuse_ID (integer) – the landuse ID in the landuse polygon,-1 for lake

  LAND_USE_C (string) – the landuse class name for each landuse type

• path_soil_info (string) –

  is the path to a csv file that contains soil information, including following attributes:

  Soil_ID (integer) – the soil ID in the soil polygon,-1 for lake

  SOIL_PROF (string) – the soil profile name for each soil profile type

• path_veg_info (string) –

  is the path to a csv file that contains vegetation information, including following attributes:

  Veg_ID (integer) – the vegetation ID in the vegetation polygon,-1 for lake

  VEG_C (string) – the vegetation class name for each vegetation Type

• projected_epsg_code (string (optional)) – is a EPSG code to indicate a projected coordinate system. If the routing network generated by basinmaker is under a projected system, please assgin the EPSG code of that projected system to projected_epsg_code. If the routing network generated by basinmaker is under a geographic system, please use EPSG code from any projected system. The coordinate system of routing network from basinmaker is determined by the coordinate system of input DEM.

• path_connect_lake_polygon (string (Optional)) – is the path to the connected lake’s polygon

• path_non_connect_lake_polygon (string (Optional)) – is the path to the non connected lake’s polygon

• path_landuse_polygon (string (Optional)) – is the path to the landuse polygon. when path_landuse_polygon is not provided. The Landuse ID in path_landuse_info should be 1: land, -1: lake

• path_soil_polygon (string (Optional)) – is the path to the soil polygon. when soil polygon is not provided. The Soil ID in path_soil_info should be the same as Landuse ID.

• path_vegetation_polygon (string (Optional)) – is the path to the vegetation polygon. when vegetation polygon is not provided. The Veg ID in path_veg_info should be the same as Landuse ID.

• path_other_polygon_1 (string (Optional)) – is the path to the other polygon that will be used to define HRU, such as elevation band, or aspect.

• DEM (string (optional)) – is the path to a raster elevation dataset, that is used to calcuate average apspect, elevation and slope within each HRU. if no data is provided, subbasin averaged value will be used for each HRU.

• area_ratio_thresholds (list (optional)) – It is a list of HRU area thresthold for landuse, soil and other_1 layer respectively. In BasinMaker HRU calculation, each layer will firstly be overlaid to the subbasin map. Attributes falling into each subbasin with their area ratios (i.e., the intersected area to the subbasin area) smaller than the defined threshold values will then be dissolved into the largest part. For example, if forest area ratio in a subbasin, say subbasin #10, is 0.05, while we set the area threshold for land cover is 0.1. The forest polygons will then be dissolved to the largest land cover type in subbasin #10.

Notes

This function has no return values, but a HRU map saved in the path_output_folder

Examples

Generate Raven input files

basinmaker.basinmaker.postprocess.Generate_Raven_Model_Inputs(path_output_folder, path_hru_polygon, aspect_from_gis, model_name='test', subbasingroup_nm_channel=['Allsubbasins'], subbasingroup_length_channel=[-1], subbasingroup_nm_lake=['AllLakesubbasins'], subbasingroup_area_lake=[-1])

This function is to generate Raven input files. A subfolder ‘RavenInput’ in path_output_folder is created to sotre resultant outputs.

Parameters:

• path_output_folder (string) – is the folder path that stores generated Raven input fiels

• path_hru_polygon (string) – is path of the output HRU shapefile from BasinMaker which includes all required hydrologic attributes and parameters; Each row in the attribute table of this shapefile represent a HRU.

• aspect_from_gis (string) – is a string indicating how aspect of each HRU in path_hru_polygon is caculated. “grass” represent the aspect is calcuated by GRASS GIS; “arcgis” represent the aspect is calcuated by ArcGIS.

• model_name (string (optional)) – is the The Raven model base name.

• subbasingroup_names_channel (list (optional)) – is a list of names for subbasin groups, which are grouped based on channel length of each subbsin. Should at least has one name

• subbasingroup_length_channel (list (optional)) –

  is a list of channel length thresthold in meter, that divides subbasin into different groups. For example, [1,10,20] divides subbasins into four groups:

  1) group 1 with channel length range from (0,1];

  2) group 2 with channel length range from (1,10];

  3) group 3 with channel length range from (10,20];

  4) group 4 with channel length range from (20,Max channel length].

• subbasingroup_name_lake (list (optional)) – is a list of names for subbasin groups, which are grouped based on area of lakes in lake subbasins. Should at least has one name

• subbasingroup_area_lake (list (optional)) –

  is a list of lake area thresthold in m2, that divides subbasin into different groups. For example, [1,10,20] divides subbasins into four groups:

  1) group 1 with lake area range from (0,1];

  2) group 2 with lake are range from (1,10],

  3) group 3 with lake are range from (10,20],

  4) group 4 with lake are range from (20,max_lake_area].

Notes

The following ouput files will be generated in “<path_output_folder>/RavenInput”

modelname.rvh - contains subbasins and HRUs

Lakes.rvh - contains definition and parameters of lakes

channel_properties.rvp - contains definition and parameters for channels

Examples

BasinMaker - delineate lake-river routing product tools

In order to fully delineate a lake-river routing network from scratch, users need to sequentially apply five BasinMaker functions (ND1 to ND5) described in this section.

The overview of the workflow is summarized in the Figure below.

Figure Caption: This is Figure 3 from han et al. (2023). Workflow, including inputs and outputs, of the BasinMaker network delineation mode functions for generating a hydrological routing network with lakes and rivers given a DEM and a lake polygon layer. Notes: 1. Flow direction raster dataset is optional user input here. 2. The channel profile coefficient map to define bankfull channel widths and depths across the extent can alternatively be replaced by coefficients that are constant across the spatial extent of the project.

Define project spatial extent

basinmaker.basinmaker.delineate.Define_Project_Spatial_Extent(mode, path_to_dem_input, watershed_outlet_coordinates=[-1, -1], path_to_spatial_extent_polygon='#', buffer_distance=0.0, path_to_hydrobasin_polygon='#', hydrobasin_id_of_watershed_outlet=-1)

This function is to define project spatial extent (PSE). Domain ouside of the PSE is not processed by BasinMaker functions.

Parameters:

• mode (string (required)) –

  is a string indicating which to define PSE

  ’using_dem’ : the extent of input dem is used

  ’using_hybasin’ : the extent is defined by subbasins that are drainage to the provided watershed outlet subbasins ID in HydroBASINS product

  ’using_outlet_pt’ : the extent is defined by the watershed generated from input dem and the watershed outlet coordinates

  ’using_provided_ply’ : the extent of provided polygon is used

• path_to_dem_input (string (required)) – is the path to input dem

• watershed_outlet_coordinates (list (optional)) – is a list that indicate the outlet coordinates of the region of interest in [lat, lon]. It is needed when mode = ‘using_outlet_pt’.

• path_to_spatial_extent_polygon (string (optional)) – is the path of a polygon shapefile, the extent of which will be used as PSE.

• buffer_distance (float (optional)) – is a float number to enlarge the PSE. It is needed when mode = ‘using_hybasin’ or mode = ‘using_provided_ply’. It is the distance around the PSE from HydroBASINS or provided polygons that will be buffered. The unit is the same with the spatial unit of input DEM.

• path_to_hydrobasin_polygon (string (optional)) – is a path to the HydroBASINs product. It is needed when mode = ‘using_hybasin’

• hydrobasin_id_of_watershed_outlet (int (optional)) – is a HydroBASINS subbasin ID of the watershed outlet. It is needed when mode = ‘using_hybasin’

Notes

Outputs are following files in GRASS GIS database loacated in os.path.join(path_working_folder,’grassdb’)

MASK.*raster/shp

it is a mask raster stored in grass database, which indicate the PSE.

dem.*raster/shp

it is a dem raster stored in grass database, which is has the same extent with MASK.

Examples

Delineate routing structure without lakes

basinmaker.basinmaker.delineate.Delineation_Initial_Subbasins_Without_Lakes(fac_thresold, mode='using_dem', path_flow_dirction_in='#', max_memroy=4096)

Function that used to generate a initial routing structure with user provied flow accumulation thresthold without considering lake.

Parameters:

• fac_thresold (float) – is the flow accumulation thresthold, used to determine subbsains and river network. Increasing of this paramter will increase the size of generated subbasins, reduce the number subbasins and reduce the number of generated stream reaches

• mode (string (required)) –

  is a string indicate which dataset will be used to delineate watershed.

  ’using_dem’ : dem is used for initial subbasin delineation

  ’using_fdr’ : flow direction data is used for subbasin delineation

• path_flow_dirction (string (optional)) – is a path indicating the path of flow direction input dataset only needed when mode = ‘using_fdr’

• max_memroy (integer) – is the maximum memeory that allow to be used in MB.

Notes

Outputs are following files in GRASS GIS database loacated in os.path.join(path_working_folder,’grassdb’)

fdr_grassraster

is a raster represent flow direction dataset, which is using 1 - 8 to represent different directions

fdr_arcgisraster

is a raster represent flow direction dataset, which is using 1,2,4,…64,128 to represent different directions

str_vvector

is a river network in vector format

str_rraster

is a river network in raster format

cat_no_lakeraster

is the raster represent the delineated subbasins without considering lakes

accraster

is the raster represent the flow accumulation

Examples

Add lake control points and points of interest

basinmaker.basinmaker.delineate.Add_New_Subbasin_Outlet_Points(path_lake_polygon='#', lake_attributes=[], connected_lake_area_thresthold=0, non_connected_lake_area_thresthold=0, path_point_of_interest='#', point_of_interest_attributes=[], max_memroy=4096)

Update the subbasin delineation result by adding lake inflow and outflow points and observation gauges as a new subbasin outlets. The output is not the final delineation result. because:

1) Hydrologcial related attributes for each subbasin are not calcuated yet.

2) Some lakes may cover several subbasins. The output needs to be finalized by combing those subbasins with the same lake as one subbasin only.

Parameters:

• path_lake_polygon (string (optional)) – is a path of the lake polygon shapefile

• lake_attributes (list (optional)) –

  the columns names in the input lake polygon that indicate following items (mandatory). It is needed only when path_lake_polygon_in is provided. Columns (2-4 in following list) in lake poylon can be fill with any number, when these infomation is not avaiable.

  1) column name for the unique Id of each lake, datatype is integer

  2) column name for type of the lake, datatype is integer

  3) column name for the volume of lakes in km3, datatype is float

  4) column name for the average depth of lakes in m, datatype is float

  5) column name for the area of lakes in km2, datatype is float

• connected_lake_area_thresthold (float (optional)) – is a lake area thresthold for connected lakes in km2. Connected lake with lake area below this value will not be considerd

• non_connected_lake_area_thresthold (float (optional)) – is a lake area thresthold for non-connected lakes in km2 Non connected lake with lake area below this value will not be considered

• path_point_of_interest – is a path of the point shapefile that indicate points of interest,which can include different observation gauges.

• point_of_interest_attributes (list (optional)) –

  the columns names in the point of interest shapefile that indicate following items (mandatory). It is needed only when path_point_of_interest is provided. Columns (2-4 in following list) in point shapefile can be fill with any value, when these infomation is not avaiable.

  1) column name for the unique Id of each observation point, datatype is integer

  2) column name for the unique name of each observation point, datatype is string

  3) column name for the drainage area of each observation point in km3, datatype is float

  4) column name for the source of the observation point: ‘CA’ for observation in canada; ‘US’ for observation in US, or any user-provided names, datatype is string

• max_memroy (integer (optional)) – is the maximum memeory that allow to be used in MB.

Notes

Output raster and vector files that will be used by next step are list as following. All files are saved in GRASS GIS database loacated in os.path.join(path_working_folder,’grassdb’)

selected_lakesraster

it is a raster represent all lakes that are selected by two lake area threstholds

sl_nonconnect_lakeraster

it is a raster represent all non connected lakes that are selected by lake area threstholds

sl_connected_lakeraster

it is a raster represent all connected lakes that are selected by lake area threstholds

river_without_merging_lakesraster/vector

it is the updated river segment for each subbasin

catchment_without_merging_lakesraster/vector

it is a raster represent updated subbasins after adding lake inflow and outflow points as new subbasin outlet.

snapped_obs_pointsraster/vector

it is a name of the point gis file represent successfully sanpped point of interest points

Examples

Guidance on Points of Interest input layer preparation

For those running BasinMaker with QGIS & GRASS, points of interest will be snapped by this function automatically to the closest delineated river channel and as such, no input layer preparation is strictly required. However, in our experience this auto-snapping approach is only modestly successful. Please inspect snapped results carefully. If users ensure that points of interest associated with lake levels are located within a lake polygon, then this function will include the point of interest at the lake (and lake subbasin) outlet.

For those running BasinMaker in ArcGIS pro, the user needs to carefully prepare the points of interest shapefile as input. Specifically, the location of each non-lake point of interest should be carefully snapped to the the appropriate eventual delineated river channel. To do this, we recommend users build a temporary channel raster and snap to that. We also recommend users ensure that points of interest associated with lake levels are located within a lake polygon. These POI will be ignored by this function and must be added separately from this function using the function called “Add_Point_Of_Interest_Sites_In_Routing_Product”.

A robust new function that can help users automatically snap points of interest to delineated river channels/lakes is coming in the next version of BasinMaker.

Add hydrology related attributes

basinmaker.basinmaker.delineate.Generate_Hydrologic_Routing_Attributes(path_output_folder, prjected_epsg_code='EPSG:3573', path_bkfwidthdepth_polyline='#', bkfwd_attributes=[], k=-1, c=-1, path_landuse='#', path_landuse_and_manning_n_table='#', lake_attributes=[], point_of_interest_attributes=[])

Calculate hydrological paramters for each subbasin.

Parameters:

• path_output_folder (string) – The path to a folder to save outputs

• projected_epsg_code (string (optional)) – is a EPSG code to indicate a projected coordinate system. If the routing network generated by basinmaker is under a projected system, please assgin the EPSG code of that projected system to projected_epsg_code. If the routing network generated by basinmaker is under a geographic system, please use EPSG code from any projected system. The coordinate system of routing network from basinmaker is determined by the coordinate system of input DEM.

• path_bkfwidthdepth_polyline (string (optional)) – is a path of the polyline shapefile that contains bankfull width (w) and depth (d) data.Following the methodology in Andreadis et al. (2013), the w, and d of each subbasin can be calculated by these two equation w= 7.2 Q**0.5 and d=0.27Q**0.39 , respectively. And the the bankfull discharge Q of each subbasin can be estimated using the relationship between Q and the drainage area (DA in [km2]), which is the Q=k×DA**c. If the bankfull width and depth polyline data is provided, basinmaker will use it to estimate the k and c for the entire watershed.

• bkfwd_attributes (list (optional)) –

  the columns names that indicate following items (mandatory).It is only needed with path_bkfwidthdepth is provided

  1) column name for the Bankfull width in m;

  2) column name for the Bankfull depth in m;

  3) column name for the annual mean discharge in m3/s;

  4) column name for the drainage area in km2;

• k (float (optional)) – the coefficient in Q=k×DA**c.if k and c is provided, the path_bkfwidthdepth_polyline will not be used

• c (float (optional)) – the coefficient in Q=k×DA**c.if k and c is provided, the path_bkfwidthdepth_polyline will not be used

• path_landuse (string (optional)) – is a path of the landuse raster.It is used to estimate the floodplain Manning’s coefficient. Require the same projection with the DEM data and formatted in “.tif”.

• path_landuse_and_manning_n_table (string (optional)) –

  is a path of the table in ‘.csv’ format.The table describe the floodplain Manning’s coefficient correspond to a given landuse type. The table should have two columns:

  RasterV: is the landuse value in the landuse raster for each land use type

  MannV: is the roughness coefficient value for each landuse type.

• lake_attributes (list (optional)) –

  the columns names in the input lake polygon that indicate following items (mandatory). It is needed only when path_lake_polygon_in is provided. Columns (2-4 in following list) in lake poylon can be fill with any number, when these infomation is not avaiable.

  1) column name for the unique Id of each lake, datatype is integer

  2) column name for type of the lake, datatype is integer

  3) column name for the volume of lakes in km3, datatype is float

  4) column name for the average depth of lakes in m, datatype is float

  5) column name for the area of lakes in km2, datatype is float

• point_of_interest_attributes (list (optional)) –

  the columns names in the point of interest shapefile that indicate following items (mandatory). It is needed only when path_point_of_interest is provided. Columns (2-4 in following list) in point shapefile can be fill with any value, when these infomation is not avaiable.

  1) column name for the unique Id of each observation point, datatype is integer

  2) column name for the unique name of each observation point, datatype is string

  3) column name for the drainage area of each observation point in km3, datatype is float

  4) column name for the source of the observation point: ‘CA’ for observation in canada; ‘US’ for observation in US, or any user-provided names, datatype is string

Notes

Five vector files will be generated in the output folder. these files can be further finalized as hydrologcial routing network by function “combine_catchments_covered_by_the_same_lake” or be used as input for BasinMaker post processint tools. The attributes included in each GIS file can be found in http://hydrology.uwaterloo.ca/basinmaker/index.html

catchment_without_merging_lakes.shpshapefile

The GIS layer containing subbasin polygons of an incomplete hydrologic routing network. In this incomplete hydrologic routing network subbasin polygons covered by the same lake are not merged into one lake subbasin yet. This incomplete hydrologic routing network is only intended as input to customize the routing network with our BasinMaker GIS toolbox (for example by defining new lake area thresholds and/or a new catchment minimum drainage area threshold)

river_without_merging_lakes.shpshapefile

The GIS layer containing river polylines of an incomplete hydrologic routing network. In this incomplete hydrologic routing network, the river polylines covered by the same lake are not merged into one river segment yet. This incomplete hydrologic routing network is only intended as input to customize the routing network with our BasinMaker GIS toolbox (for example by defining new lake area thresholds and/or a new catchment minimum drainage area threshold)

sl_connected_lake.shpshapefile

the GIS layer containing the lake polygons of lakes that are connected by the river_without_merging_lakes.shp

sl_non_connected_lake.shpshapefile

the GIS layer containing the lake polygons of lakes that are not connected by the river_without_merging_lakes.shp

poishapefile

It is the point shapefile that represent the point of interest after snap to river network.

Examples

Combine catchment covered by the same lake

basinmaker.basinmaker.delineate.Combine_Subbasins_Covered_by_The_Same_Lake(routing_product_folder, gis_platform='qgis')

Finalize a incomplete hydrologic routing network by merging subbasin polygons that are covered by the same lake.

Parameters:

• routing_product_folder (string) – is the folder where the input routing product is stored

• gis_platform (string) – It is the parameter indicate which gis platform is used. It can be either “qgis” or “arcgis”.

Notes

This function has no return values, two vector files will be generated in the routing_product_folder

finalcat_info.shpshapefile

The finalized hydrologic routing network. the GIS layer containing subbasin polygons which respect the lake inflow and outflow routing structures. This layer contains all the necessary information for hydrologic routing through the lake-river network.

finalcat_info_riv.shpshapefile

The finalized hydrologic routing network. the GIS layer containing river network polylines in the routing network.

Examples