top of page
Search

Using PySheds Python Library for Advanced GIS Watershed Modeling

  • Writer: Anvita Shrivastava
    Anvita Shrivastava
  • 2 days ago
  • 4 min read

Updated: 1 hour ago

Watershed modeling is critical for hydrologists, environmental managers, flood risk assessors, and water resource planners. With the increased availability of high-resolution Digital Elevation Models (DEMs), GIS professionals and data scientists now need to analyze terrain and drainage networks with tools that analyze terrain and drainage networks quickly and efficiently.


PySheds is one of the most powerful open source hydrological terrain processing libraries available in Python. The PySheds library provides users with a straightforward way to perform advanced watershed delineation, flow direction, flow accumulation, extraction of river networks, and, at times, drainages with only a few lines of Python code.


PySheds
PySheds


What is PySheds?


PySheds is a raster-based hydrological analysis library with efficient algorithms that read DEMs and extract features such as:


  • Watersheds

  • Catchments

  • Streams

  • Flow directions

  • Flow accumulation surfaces

  • Rivers


In addition, the library has been optimized for large raster datasets and seamlessly integrates with popular Python GIS ecosystems, including:



For this reason, PySheds is a suitable choice for hydrologists, GIS analysts, environmental engineers, and geospatial data scientists.


Reasons to Use PySheds for Watershed Modeling:


  1. Speed of Processing


The optimized numerical operations make PySheds process data faster than traditional desktop GIS tools.


  1. Free Open Source


Most GIS products are proprietary; PySheds is an open-source and free product.


  1. Integration with Python


Users can automate processes for hydrology and use PySheds to integrate hydrological modeling into ML and GIS data pipelines.


  1. Scalable Analysis


PySheds processes large DEM (Digital Elevation Model) datasets efficiently, making it feasible to conduct hydrologic studies across different regions or nations.



Using PySheds Python Library for Advanced GIS Watershed Modeling

Installing PySheds


Install PySheds using pip:

pip install pysheds

For visualization and raster processing, install additional dependencies:

pip install rasterio geopandas matplotlib numpy

Verify the installation:

from pysheds.grid import Grid

print("PySheds installed successfully!")


Understanding the Watershed Modeling Workflow


The typical method for delineation of a watershed includes:


  1. Load DEM data

  2. Fill in any depressions.

  3. Resolve flat areas

  4. Calculate flow directions

  5. Calculate flow accumulation

  6. Define pour points

  7. Delineate the watershed boundaries.

  8. Extract stream networks


Let's examine each step.


Step 1: Load a Digital Elevation Model (DEM)

A DEM serves as the foundation for hydrological analysis.

from pysheds.grid import Grid

grid = Grid.from_raster('dem.tif')
dem = grid.read_raster('dem.tif')

Visualize the DEM:

import matplotlib.pyplot as plt

plt.imshow(dem, cmap='terrain')
plt.colorbar(label='Elevation (m)')
plt.title('Digital Elevation Model')
plt.show()

Step 2: Fill Depressions and Sinks

DEM datasets often contain artificial depressions that disrupt flow routing.

Fill pits:

pit_filled_dem = grid.fill_pits(dem)

Fill larger depressions:

flooded_dem = grid.fill_depressions(pit_filled_dem)

Resolve flats:

inflated_dem = grid.resolve_flats(flooded_dem)

These preprocessing steps ensure accurate hydrological flow paths.


Step 3: Calculate Flow Direction

Flow direction determines how water moves across the landscape.

dirmap = (64, 128, 1, 2, 4, 8, 16, 32)

flow_dir = grid.flowdir(inflated_dem, dirmap=dirmap)

The D8 algorithm assigns flow from each cell to one of its eight neighboring cells.

Visualize results:

plt.imshow(flow_dir)
plt.title('Flow Direction')
plt.show()

Step 4: Compute Flow Accumulation

Flow accumulation identifies areas where water converges.

acc = grid.accumulation(flow_dir, dirmap=dirmap)

Display accumulation values:

plt.imshow(acc, cmap='cubehelix')
plt.colorbar(label='Accumulated Flow')
plt.title('Flow Accumulation')
plt.show()

High accumulation values often indicate stream channels and river networks.


Step 5: Define the Watershed Outlet

A pour point represents the watershed outlet.

Example coordinates:

x, y = 500000, 4200000

Snap the point to the nearest high-flow cell:

x_snap, y_snap = grid.snap_to_mask(acc > 1000, (x, y))

This improves watershed delineation accuracy.


Step 6: Delineate the Watershed

Create a catchment based on the outlet location:

catchment = grid.catchment(
    x=x_snap,
    y=y_snap,
    fdir=flow_dir,
    dirmap=dirmap,
    xytype='coordinate'
)

Convert to a watershed mask:

grid.clip_to(catchment)

Visualize the watershed:

plt.imshow(catchment)
plt.title('Watershed Boundary')
plt.show()

Step 7: Extract Stream Networks

Generate stream channels from flow accumulation thresholds.

streams = acc > 1000

Display streams:

plt.imshow(streams)
plt.title('Stream Network')
plt.show()

Adjust the threshold value depending on watershed size and DEM resolution.


Advanced Watershed Modeling Techniques


River Network Extraction

Extract vector stream segments:

branches = grid.extract_river_network(
    flow_dir,
    streams,
    dirmap=dirmap
)

These outputs can be exported to GIS software for further analysis.


Multiple Catchment Delineation

PySheds can delineate multiple watersheds simultaneously.

Applications include:

  • Regional flood studies

  • Basin management

  • Watershed inventory projects

  • Stormwater planning


Topographic Wetness Index (TWI)

TWI helps identify areas prone to water accumulation.

Formula:

TWI = ln(a / tanβ)

Where:

  • a = contributing area

  • β = slope angle

This metric is commonly used in hydrology and ecological modeling.


Flood Risk Assessment

PySheds enables:

  • Floodplain mapping

  • Surface runoff modeling

  • Drainage pattern analysis

  • Stormwater impact studies

By combining flow accumulation and watershed boundaries, analysts can identify high-risk flood zones.


Exporting Results to GIS Platforms


PySheds outputs can be exported for use in GIS software.

Export watershed raster:

grid.to_raster(
    catchment,
    'watershed.tif'
)

Export stream networks:

import geopandas as gpd

gdf = gpd.GeoDataFrame.from_features(branches['features'])
gdf.to_file('streams.shp')

These files can be opened directly in:


The PySheds Python library is currently one of the most valuable libraries for watershed modeling and hydrological terrain analysis. It allows users to process digital elevation models with high precision, delineate watersheds and find flow accumulation values, and extract stream networks quickly and efficiently, making PySheds a necessary tool for GIS professionals and environmental data scientists.


PySheds provides scalable and workflow-friendly solutions to flood risk assessment, watershed delineation, stream network extraction, and large-scale hydrological studies, so there is no limit to the number of applications for which you can use these tools.


As organizations continue to implement Python-based GIS analysis, mastering the PySheds library will significantly improve your capabilities for modeling watersheds and decrease your reliance on proprietary GIS software.


To learn more about PySheds and its geospatial capabilities, click here.


For more information or any questions regarding the LizardTech suite of products, please don't hesitate to contact us at:



USA (HQ): (720) 702–4849


(A GeoWGS84 Corp Company)



bottom of page