NLDI Flowtools

NLDI Flowtools provides basin delineation and flow path tracing services.

Description

NLDI Flowtools is a Python package for basin delineation and flow path tracing from any point within CONUS. It can return either the full upstream drainage basin or just the portion within the local NHD catchment (i.e., splitcatchment). The flow path tracing tool follows terrain downhill until it intersects the nearest NHD stream line, returning both the traced path and the intersected stream segment (upstream, downstream, or full geometry). NLDI Flowtools uses NHDPlus V2 data and NLDI services.

Documentation

Check out our Read the Docs documentation page.

Requirements

• python = ">=3.10,<=3.14"
• click = ">=7.1.2"
• geojson = "^2.5.0"
• numpy = ">=2.0.0"
• pyproj = "^3.4.0"
• rasterio = "^1.3.9"
• requests = "^2.32.0"
• Shapely = ">=2.0.0"

Installation

For users:

You can install NLDI-Flowtools via pip from PyPI:

$ pip install nldi-flowtools

For Developers:

First, clone the repo. Navigate to the repo directory and install UV, then sync the project with its dev dependencies:

$ uv sync --group dev

Activate the virtual environment:

$ source .venv/bin/activate

Nox is used for organizing the suite of testing libraries used. To list all of the Nox test options, run:

$ nox --list

To run all of the Nox tests, simply run:

$ nox

To only run a single test, run:

$ nox -s mypy

Features

Split Catchment

Delineate the drainage basin upstream of any point within CONUS. Given a longitude/latitude coordinate pair, splitcatchment returns a GeoJSON FeatureCollection containing:

• The local NHD catchment the point falls within.
• Either the portion of that catchment that drains to the point (upstream=False), or the full upstream drainage basin including all upstream NHD catchments (upstream=True).

Flow Trace

Trace the path water takes from any point downhill to the nearest NHD stream. Given a longitude/latitude coordinate pair, flowtrace returns a GeoJSON FeatureCollection containing:

• The raindrop path from the input point to the NHD flowline.
• The intersected NHD stream segment — either the full geometry, or just the upstream or downstream portion depending on the direction parameter.

Both functions return metadata about the intersected stream, including COMID, reach code, GNIS name, and the reach measure at the point of intersection.

Usage

Import the two main functions:

from nldi_flowtools.nldi_flowtools import splitcatchment, flowtrace

Split Catchment

# Local split only (portion of catchment draining to the point)
result = splitcatchment(lon=-93.0, lat=45.0, upstream=False, simplified=False)

# Full upstream drainage basin
result = splitcatchment(lon=-93.0, lat=45.0, upstream=True, simplified=True)

The returned FeatureCollection contains two features:

Flow Trace

# Downstream portion of the intersected stream
result = flowtrace(lon=-93.0, lat=45.0, direction="down")

# Upstream portion
result = flowtrace(lon=-93.0, lat=45.0, direction="up")

# Full stream segment
result = flowtrace(lon=-93.0, lat=45.0, direction="none")

The returned FeatureCollection contains two features:

The flowline feature includes properties like comid, gnis_name, reachcode, measure, and raindrop_pathDist (distance in meters).

See the package documentation for additional details.

Contributing

Contributions are very welcome. To learn more, see the Contributor Guide.

License

Distributed under the terms of the CC0 1.0 Universal license, NLDI Flowtools is free and open source software.

Issues

If you encounter any problems, please file an issue along with a detailed description.

Disclaimer

DISCLAIMER.md

Authors

Anders Hopkins - Lead Developer - USGS Web Informatics & Mapping

Citation

Hopkins, A.L., 2025, NLDI Flowtools, U.S. Geological Survey Software Release, https://doi.org/10.5066/P9W5UK7Z.

Credits

• Streams and catchment geometries are queried from NHDPlus Version 2 using the Network Linked Data Index.
• Flow direction and flow accumulation rasters from NHDPlus Version 2 are also used in this package.
• This project was generated from @hillc-usgs's Pygeoapi Plugin Cookiecutter template.

Acknowledgments

• Hydrologic delineations use an algorithm borrowed from SS-Delineate.
• Developed in collaboration with @rmcd's NLDI XStools.
• Cloud-optimized flow direction raster hosted by @dblodgett.