NLDI Flowtools
==============

**Version:** |version|

Basin delineation and flow path tracing for any point within CONUS, powered by
`NHDPlus V2 <https://water.usgs.gov/catalog/datasets/8a60b6b4-d785-4265-af99-cd1870ea7928/>`_
data and the `Network Linked Data Index <https://waterdata.usgs.gov/blog/nldi-intro/>`_.

.. code-block:: python

   from nldi_flowtools.nldi_flowtools import splitcatchment, flowtrace

   # Delineate the full upstream drainage basin
   basin = splitcatchment(lon=-93.0, lat=45.0, upstream=True, simplified=True)

   # Trace the flow path to the nearest stream
   trace = flowtrace(lon=-93.0, lat=45.0, direction="down")

Both functions accept WGS 84 longitude/latitude coordinates and return GeoJSON
FeatureCollections.

Tools
-----

**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 merged with all upstream catchments.

**Flow Trace** — Follows the 30m flow direction grid downhill from a point
until it intersects an NHD stream. Returns the traced raindrop path and the
intersected stream segment (upstream, downstream, or full geometry).

.. 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.

Installation
------------

.. code-block:: bash

   pip install nldi-flowtools

Requirements: Python 3.10 -- 3.14.

For development setup, see the :doc:`contributing`.

Authors
-------

Anders Hopkins — *Lead Developer* —
`USGS Web Informatics & Mapping <https://wim.usgs.gov/>`_

Acknowledgments
---------------

- Hydrologic delineations use an algorithm borrowed from
  `SS-Delineate <https://code.usgs.gov/StreamStats/web-services-and-apis/ss-delineate>`_.
- Developed in collaboration with `@rmcd <https://code.usgs.gov/rmcd>`_'s
  `NLDI XStools <https://code.usgs.gov/wma/nhgf/toolsteam/nldi-xstool>`_.
- Cloud-optimized flow direction raster hosted by
  `@dblodgett <https://code.usgs.gov/dblodgett>`_.

.. toctree::
   :hidden:
   :maxdepth: 2

   Usage <usage.rst>
   Modules <modules.rst>
   Contributing <contributing.rst>
   Code of Conduct <codeofconduct.rst>
   Disclaimer <disclaimer.rst>
   License <license.rst>
   Reference <reference.rst>