API

basmati.downloader

basmati.hydrosheds

basmati.hydrosheds.load_hydrobasins_geodataframe(hydrosheds_dir: Union[str, pathlib.Path], region: str, levels: Iterable = range(1, 7), hydrobasins_file_tpl: str = 'hybas_{region}_lev{level:02}_v1c.shp') → geopandas.geodataframe.GeoDataFrame

Load all data for the desired region and levels.

Parameters

  • hydrosheds_dir – directory of HydroSHEDS datasets

  • region – 2 character region code

  • levels – Pfafstetter levels to load

  • hydrobasins_file_tpl – filename template

Returns

geodataframe containing all the data for the desired region and levels

basmati.hydrosheds.load_hydrosheds_dem(hydrosheds_dir: Union[str, pathlib.Path], region: str, resolution: str = '30s', hydrosheds_dem_file_tpl: str = '{region}_dem_{resolution}.bil') → Tuple[numpy.ndarray, affine.Affine, numpy.ndarray, numpy.ndarray]

Load a HydroSHEDS Digital Elevation Model (DEM).

Parameters

  • hydrosheds_dir – directory of HydroSHEDS datasets

  • region – 2 character region code

  • resolution – resolution to load

  • hydrosheds_dem_file_tpl – filename template

Returns

bounds, affine transform, DEM and mask of the DEM

basmati.hydrosheds.is_downstream(pfaf_id_a: Union[int, str], pfaf_id_b: Union[int, str]) → bool

Calculate if pfaf_id_b is downstream of pfaf_id_a

Implemented as in https://en.wikipedia.org/wiki/Pfafstetter_Coding_System#Properties Works even if pfaf_id_a and pfaf_id_b are at different levels.

Parameters

  • pfaf_id_a – first Pfafstetter id (upstream)

  • pfaf_id_b – second Pfafstetter id (downstream)

Returns

True if pfaf_id_b is downstream of pfaf_id_a, False otherwise or if a == b

basmati.hydrosheds._find_downstream(gdf: geopandas.geodataframe.GeoDataFrame, start_basin_pfaf_id: int) → geopandas.geodataframe.GeoDataFrame

Find all downstream basins at the same level as the start basin.

Can also be used as a method on a gpd.GeoDataFrame: gdf.find_downstream(start_basin_pfaf_id)

Parameters

  • gdf – hydrobasins geodataframe to traverse

  • start_basin_pfaf_id – Pfafstetter id of start basin

Returns

filtered geodataframe at level of start basin based on which basins are downstream of start basin

basmati.hydrosheds._find_upstream(gdf: geopandas.geodataframe.GeoDataFrame, start_basin_pfaf_id: int) → geopandas.geodataframe.GeoDataFrame

Find all upstream basins at the same level as the start basin.

Can also be used as a method on a gpd.GeoDataFrame: gdf.find_upstream(start_basin_pfaf_id)

Parameters

  • gdf – hydrobasins geodataframe to traverse

  • start_basin_pfaf_id – Pfafstetter id of start basin

Returns

filtered geodataframe at level of start basin based on which basins are upstream of start basin

basmati.hydrosheds._find_next_level_larger(gdf: geopandas.geodataframe.GeoDataFrame, start_basin_pfaf_id: int) → geopandas.geodataframe.GeoDataFrame

Find basin one level lower (i.e. found basin is larger).

if start_basin_pfaf_id == 913, will return basin 91. Can return 0 or 1 basins.

Can also be used as a method on a gpd.GeoDataFrame: gdf.find_next_level_larger(start_basin_pfaf_id)

Parameters

  • gdf – hydrobasins geodataframe to traverse

  • start_basin_pfaf_id – Pfafstetter id of start basin

Returns

filtered geodataframe with 0 or 1 basins at level lower

basmati.hydrosheds._find_next_level_smaller(gdf: geopandas.geodataframe.GeoDataFrame, start_basin_pfaf_id: int) → geopandas.geodataframe.GeoDataFrame

Find basins one level higher (i.e. found basins are smaller).

if start_basin_pfaf_id == 91, will return basins 911, 912… 919. Can return 0-9 basins.

Can also be used as a method on a gpd.GeoDataFrame: gdf.find_next_level_smaller(start_basin_pfaf_id)

Parameters

  • gdf – hydrobasins geodataframe to traverse

  • start_basin_pfaf_id – Pfafstetter id of start basin

Returns

filtered geodataframe with 0-9 basins at level higher

basmati.hydrosheds._area_select(gdf: geopandas.geodataframe.GeoDataFrame, min_area: float, max_area: float) → geopandas.geodataframe.GeoDataFrame

Select basins from lower to higher levels that are between min_area and max_area in area.

Start by working out if any basins at e.g. level 1 are selected. Then move on to higher levels (smaller basins). At each level, only add basins if the basin at the level below has not been added. e.g. level 3 basins 411 to 419 will not be added if at level 2 basin 41 was added.

Can also be used as a method on a gpd.GeoDataFrame: gdf.area_select(min_area, max_area)

Parameters

  • gdf – hydrobasins geodataframe to traverse

  • min_area – minimum area of basin

  • max_area – maximum area of basin

Returns

filtered geodataframe from any level (favouring lower levels) with area between min and max

basmati.utils