Usage

NLDI-Flowtools provides two services: delineating drainage basins and tracing the flow path of water. The Split Catchment tool provides basin delineation functionality, while the Flowtrace tool provides raindrop tracing functionality.

Recommended Workflow:

When delineating a point on a stream, it is recommended to run the point through the Flowtrace function first to ‘snap’ the point to the stream line. The intersection point returned from Flowtrace can then be used as input for Split Catchment. This ensures that the delineation starts from an accurate stream location, as Split Catchment does not enforce point snapping and performs a ‘true’ delineation from the input point.

Flowtrace Tool

The flowtrace function traces the raindrop path from the input point to the NHD (National Hydrologic Dataset) Flowline that it drains to. Depending on the inputs, this function returns the raindrop path from the input point to the flowline and either a portion or the entire NHD Flowline.

Parameters:

• lon (float): Longitude coordinate of the input point in WGS 84 decimal degrees.

• lat (float): Latitude coordinate of the input point in WGS 84 decimal degrees.

• direction (str): Determines which portion of the flowline is returned.

  • ‘up’: Returns the upstream portion of the NHD Flowline.

  • ‘down’: Returns the downstream portion of the NHD Flowline.

  • ‘none’: Returns the entire NHD Flowline.

Returns:

A GeoJSON FeatureCollection containing:

1. The NHD Flowline feature (upstream, downstream, or entire flowline based on direction). Feature properties:

• comid

• gnis_name

• intersectionPoint

• measure

• raindropPathDist

• reachcode

2. The raindrop path feature.

Example Usage:

from nldi_flowtools import nldi_flowtools
nldi_flowtools.flowtrace(-93.17298889291125, 41.99318001025908, 'down')

nldi_flowtools.flowtrace(-93.17298889291125, 41.99318001025908, 'up')

Algorithm Details:

• The raindrop path follows a 30-meter Flow Direction (FDR) grid from the query point downhill to an NHD flowline.

• The intersection point is constrained to a Flow Accumulation Cell (FAC) of 900 or greater, ensuring correct delineation of the entire drainage basin.

• In rare cases, if the raindrop path extends beyond its local catchment before reaching the flowline, an additional query to NLDI is made to fetch downstream catchment and flowline data.

Split Catchment Tool

The splitcatchment function identifies the area that drains directly to a given point location. It will return the local catchment and either the local catchment portion of the drainage basin or the full upstream drainage basin.

Parameters:

• lon (float): Longitude coordinate of the input point in WGS 84 decimal degrees.

• lat (float): Latitude coordinate of the input point in WGS 84 decimal degrees.

• upstream (bool):

  • True: Returns both the local catchment and the entire upstream drainage basin if the point is on an NHD Flowline.

  • False: Returns only the local catchment and the split catchment geometries.

Returns:

A GeoJSON FeatureCollection containing:

1. Local Catchment: The NHD catchment where the input point falls.

2. Split Catchment (optional): A portion of the drainage basin, returned only if upstream=False.

3. Drainage Basin (optional): The entire upstream drainage basin, returned only if upstream=True.

Example Usage:

from nldi_flowtools import nldi_flowtools
nldi_flowtools.splitcatchment(-93.02933761928982, 41.79037842455216, True)

nldi_flowtools.splitcatchment(-93.02933761928982, 41.79037842455216, False)

Notes:

• The function does not enforce snapping to the NHD Flowline.

• To ensure the point is on the stream, use flowtrace() first to determine the intersection point before calling splitcatchment().