InVEST documentation





Many of the freshwater models in InVEST require watershed polygons to aggregate the ecosystem service provides to beneficiaries. However, we’ve found the creation of watersheds with existing tools to be difficult and often requiring specific expertise and/or proprietary toolsets. To address this need, we have developed our own watershed delineation algorithm released in the PyGeoprocessing GIS package, and wrapped into a UI inside of InVEST. All DEM routing is handled by PyGeoprocessing which resolves hydrological sinks and plateaus and uses D8 to route flow directions.

Also see the Working with the DEM section of this User Guide for more information about preparing a DEM for use in InVEST, and using it to create streams and watersheds.

Model Steps

Fill Pits

First, the model fills any pits (hydrologic sinks) in the DEM. This step helps ensure that all pixels drain off the defined area of the raster.

Calculate Flow Direction

The model applies the D8 routing algorithm to the filled DEM to calculate the direction that water flows off of each pixel.

Detect Pour Points

A pour point is a point where water flows off the defined area of the flow direction map, either off the edge of the raster or into a nodata pixel. If the Detect Pour Points option is selected, the model will place a pour point in the center of each pixel that flows either off the edge of the raster or into a nodata pixel. Alternately, you can provide your own pour point layer via the Watershed Outlets input.

Snap Points to Nearest Stream

If an outlet feature does not lie directly on a stream, a very small watershed will be generated which is usually not correct. DelineateIt can snap point outlet features to the nearest stream to make more robust watersheds. To do this, the tool constructs a stream map, and then relocates watershed outlet points to the nearest stream that is within the Snap Distance given as input to the model.

Calculate Flow Accumulation

The model calculates flow accumulation from the flow direction raster using the D8 algorithm. This represents the relative amount of water draining onto a pixel from its uphill area.

Threshold Flow Accumulation (TFA)

The model identifies streams by thresholding the flow accumulation raster by the TFA value. Areas with a flow accumulation greater than or equal to the TFA value are considered streams.

Delineate Watersheds

The model uses a D8 delineation algorithm to produce a polygon vector of watersheds from the flow direction raster and the watershed outlets geometries (if provided) or detected pour points (if Detect Pour Points is selected).

Tool Inputs

  • Workspace (directory, required): The folder where all the model’s output files will be written. If this folder does not exist, it will be created. If data already exists in the folder, it will be overwritten.

  • File Suffix (text, optional): Suffix that will be appended to all output file names. Useful to differentiate between model runs.

  • Digital Elevation Model (raster, units: m, required): Map of elevation above sea level. Hydrological sinks and flat plateau regions will be automatically resolved by PyGeoprocessing.

  • Detect Pour Points (true/false): Detect pour points (watershed outlets) based on the DEM, and use these instead of a user-provided outlet features vector. There is a pour point located at the center of each pixel that flows off the edge of the raster or into a nodata pixel. Flow direction is calculated from the DEM using the D8 algorithm.

  • Watershed Outlets (vector, point/multipoint/linestring/multilinestring/polygon/multipolygon, conditionally required): A map of watershed outlets from which to delineate the watersheds. Required if Detect Pour Points is not checked. These geometries may represent stream intake points, population centers, roads, municipality boundaries or other features of interest and may be of any geometry type including points, lines, or polygons. Any fields associated with this vector will be copied to the output watershed vector.

  • Skip Invalid Geometries (true/false): Skip delineation for any invalid geometries found in the Outlet Features. Otherwise, an invalid geometry will cause the model to crash. The log file will contain warning messages if any geometries are skipped. DelineateIt can only delineate watersheds from valid geometries, so it is up to the user to ensure that all geometries are valid. These may be resolved using the ArcGIS tool “Check Geometry” or QGIS tool “Fix geometries”.

  • Snap Points To the Nearest Stream (true/false): Whether to snap point geometries to the nearest stream pixel. If True, args['flow_threshold'] and args['snap_distance'] must also be defined. If a point is equally near to more than one stream pixel, it will be snapped to the stream pixel with the highest flow accumulation value. This has no effect if Detect Pour Points is selected. Only POINT geometries, or MULTIPOINT geometries with a single component point, will be relocated. All other geometry types will be unaltered. This input will have no effect if Detect Pour Points is selected.

  • Threshold Flow Accumulation (number, units: pixel, conditionally required): The number of upstream pixels that must flow into a pixel before it is classified as a stream. Required if Snap Points is selected. Smaller values of this threshold produce streams with more tributaries, larger values produce streams with fewer tributaries.

  • Snap Distance (number, units: pixel, conditionally required): Maximum distance to relocate watershed outlet points in order to snap them to a stream. Required if Snap Points is selected. Note that this is a distance in pixels, not meters, so scale this according to your pixel size.

Tool Outputs

All outputs can be found in the Workspace directory given previously. They include:

  • watersheds.gpkg A GeoPackage vector defining the areas that are upstream from the snapped outlet points, where upstream area is defined by the D8 flow algorithm implementation in PyGeoprocessing.

  • snapped_outlets.gpkg A vector that indicates where outlet points (point geometries only) were snapped to based on the values of Threshold Flow Accumulation and Pixel Distance to Snap Outlet Points. Any non-point geometries will also have been copied over to this vector, but will not have been altered.

  • preprocessed_geometries.gpkg A vector containing only those geometries that the model can verify are valid. The geometries appearing in this vector will be the ones passed to watershed delineation.

  • streams.tif The raster stream layer used to snap outlet points, produced from the DEM and Threshold Flow Accumulation value.

  • filled_dem.tif The DEM, but with hydrological sinks filled.

  • flow_direction.tif The D8 flow direction raster, created from the filled DEM.

  • flow_accumulation.tif The D8 flow accumulation raster, created from flow_direction.tif.