Usage

NLDI Flowtools provides two tools: Split Catchment for basin delineation and Flow Trace for raindrop path tracing. Both accept WGS 84 longitude/latitude coordinates and return GeoJSON FeatureCollections.

from nldi_flowtools.nldi_flowtools import splitcatchment, flowtrace

Tip

When delineating a point on a stream, run it through flowtrace first to snap the point to the flowline. Use the returned intersection point as input to splitcatchment for the most accurate basin boundary.

Flow Trace

Traces the raindrop path from an input point downhill along a 30m flow direction grid until it intersects an NHD flowline. Returns the traced path and the intersected stream segment.

Parameters

Name	Type	Description
`lon`	float	Longitude in WGS 84 decimal degrees.
`lat`	float	Latitude in WGS 84 decimal degrees.
`direction`	str	Which portion of the intersected flowline to return: `"up"` (upstream), `"down"` (downstream), or `"none"` (entire segment).

Returns

A GeoJSON FeatureCollection with two features:

Feature ID	Description
`upstreamFlowline` / `downstreamFlowline` / `nhdFlowline`	The NHD stream segment (varies by `direction`). Properties include `comid`, `gnis_name`, `reachcode`, `measure`, `intersection_point`, and `raindrop_pathDist`.
`raindropPath`	The traced flow path from the input point to the stream.

Examples

Downstream trace:

flowtrace(-93.17298889291125, 41.99318001025908, "down")

Upstream trace:

flowtrace(-93.17298889291125, 41.99318001025908, "up")

Algorithm Details

The raindrop path follows a 30m NHDPlus V2 flow direction grid from the query point downhill to an NHD flowline.
The intersection point is constrained to a flow accumulation cell value of 900 or greater, ensuring the trace lands on a meaningful stream cell.
If the trace extends beyond the local catchment before reaching a flowline, an additional NLDI query fetches the downstream catchment and flowline data automatically.

Split Catchment

Identifies the NHD catchment containing a point and delineates the upstream contributing area. Can return either the local split portion or the full upstream drainage basin.

Parameters

Name	Type	Description
`lon`	float	Longitude in WGS 84 decimal degrees.
`lat`	float	Latitude in WGS 84 decimal degrees.
`upstream`	bool	`True`: return the full upstream drainage basin (if the point is on a flowline). `False`: return only the local split catchment.
`simplified`	bool	`True`: request a simplified upstream basin geometry from NLDI. `False`: request the full-resolution geometry.

Returns

A GeoJSON FeatureCollection with two features:

Feature ID	Description
`catchment`	The local NHD catchment polygon. Includes a `catchmentID` property.
`splitCatchment`	The portion of the catchment upstream of the point (returned when `upstream=False`).
`drainageBasin`	The full upstream drainage basin (returned when `upstream=True` and the point is on a flowline).

Examples

Full upstream basin:

splitcatchment(-93.02933761928982, 41.79037842455216, True, False)

Local split catchment only:

splitcatchment(-93.02933761928982, 41.79037842455216, False, False)

Notes

Split Catchment does not snap the input point to the NHD flowline. For stream-based delineations, use flowtrace first to get the intersection point, then pass that to splitcatchment.
The simplified parameter only affects the upstream basin geometry requested from NLDI. The local split catchment is always full-resolution.