Metadata-Version: 2.4
Name: nldi-flowtools
Version: 0.3.8
Summary: NLDI Flowtools
Project-URL: Homepage, https://code.usgs.gov/wma/nhgf/toolsteam/nldi-flowtools
Project-URL: Repository, https://code.usgs.gov/wma/nhgf/toolsteam/nldi-flowtools
Project-URL: Documentation, https://nldi-flowtools.readthedocs.io
Project-URL: Changelog, https://code.usgs.gov/wma/nhgf/toolsteam/nldi-flowtools/-/releases
Author-email: Anders Hopkins <ahopkins@usgs.gov>
License: # License
        
        Unless otherwise noted, This project is in the public domain in the United
        States because it contains materials that originally came from the United
        States Geological Survey, an agency of the United States Department of
        Interior. For more information, see the official USGS copyright policy at
        https://www.usgs.gov/information-policies-and-instructions/copyrights-and-credits
        
        Additionally, we waive copyright and related rights in the work
        worldwide through the CC0 1.0 Universal public domain dedication.
        
        ## CC0 1.0 Universal Summary
        
        This is a human-readable summary of the
        [Legal Code (read the full text)][1].
        
        ### No Copyright
        
        The person who associated a work with this deed has dedicated the work to
        the public domain by waiving all of his or her rights to the work worldwide
        under copyright law, including all related and neighboring rights, to the
        extent allowed by law.
        
        You can copy, modify, distribute and perform the work, even for commercial
        purposes, all without asking permission.
        
        ### Other Information
        
        In no way are the patent or trademark rights of any person affected by CC0,
        nor are the rights that other persons may have in the work or in how the
        work is used, such as publicity or privacy rights.
        
        Unless expressly stated otherwise, the person who associated a work with
        this deed makes no warranties about the work, and disclaims liability for
        all uses of the work, to the fullest extent permitted by applicable law.
        When using or citing the work, you should not imply endorsement by the
        author or the affirmer.
        
        [1]: https://creativecommons.org/publicdomain/zero/1.0/legalcode
License-File: LICENSE.md
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <3.15,>=3.10
Requires-Dist: click<9,>=8.0
Requires-Dist: geojson<3,>=2.5.0
Requires-Dist: numpy>=2.0.0
Requires-Dist: pyproj<4,>=3
Requires-Dist: rasterio<2,>=1.3.4
Requires-Dist: requests<3,>=2.26.0
Requires-Dist: shapely<3,>=2
Description-Content-Type: text/markdown

# NLDI Flowtools

NLDI Flowtools provides basin delineation and flow path tracing services.

[![PyPI](https://img.shields.io/pypi/v/nldi-flowtools.svg)](https://pypi.org/project/nldi-flowtools/) [![conda](https://anaconda.org/conda-forge/nldi-flowtools/badges/version.svg)](https://anaconda.org/conda-forge/nldi-flowtools)
[![Status](https://img.shields.io/pypi/status/nldi-flowtools.svg)](https://pypi.org/project/nldi-flowtools/)
[![Python Version](https://img.shields.io/pypi/pyversions/nldi-flowtools)](https://pypi.org/project/nldi-flowtools)
[![License](https://img.shields.io/pypi/l/nldi-flowtools)](https://creativecommons.org/publicdomain/zero/1.0/legalcode)


[![Read the documentation at https://nldi-flowtools.readthedocs.io/](https://img.shields.io/readthedocs/nldi-flowtools/latest.svg?label=Read%20the%20Docs)](https://nldi-flowtools.readthedocs.io/)
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://code.usgs.gov/pre-commit/pre-commit)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)


# 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](https://nldi-flowtools.readthedocs.io/en/latest/).

# 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](https://pip.pypa.io/) from [PyPI](https://pypi.org/project/nldi-flowtools/):

```{.sourceCode .console}
$ pip install nldi-flowtools
```

## For Developers:

First, clone the repo. Navigate to the repo directory and install [UV](https://docs.astral.sh/uv/), then sync the project with its dev dependencies:

```{.sourceCode .console}
$ uv sync --group dev
```

Activate the virtual environment:

```{.sourceCode .console}
$ source .venv/bin/activate
```

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

```{.sourceCode .console}
$ nox --list
```

To run all of the Nox tests, simply run:

```{.sourceCode .console}
$ nox
```

To only run a single test, run:

```{.sourceCode .console}
$ 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:

```python
from nldi_flowtools.nldi_flowtools import splitcatchment, flowtrace
```

### Split Catchment

```python
# 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:

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

### Flow Trace

```python
# 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:

| Feature ID                                                | Description                                             |
| --------------------------------------------------------- | ------------------------------------------------------- |
| `downstreamFlowline` / `upstreamFlowline` / `nhdFlowline` | The NHD stream segment (varies by `direction`)          |
| `raindropPath`                                            | The traced flow path from the input point to the stream |

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

See the [package documentation](https://nldi-flowtools.readthedocs.io/en/latest/) for additional details.

# Contributing

Contributions are very welcome.
To learn more, see the [Contributor Guide](CONTRIBUTING.md).

# License

Distributed under the terms of the [CC0 1.0 Universal license](https://creativecommons.org/publicdomain/zero/1.0/legalcode),
_NLDI Flowtools_ is free and open source software.

# Issues

If you encounter any problems,
please [file an issue](https://code.usgs.gov/wma/nhgf/toolsteam/nldi-flowtools/-/issues) along with a detailed description.

# Disclaimer

[DISCLAIMER.md](DISCLAIMER.md)

# Authors

Anders Hopkins - _Lead Developer_ - [USGS Web Informatics & Mapping](https://wim.usgs.gov/)

# Citation

```{.sourceCode .console}
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](https://water.usgs.gov/catalog/datasets/8a60b6b4-d785-4265-af99-cd1870ea7928/) using the [Network Linked Data Index](https://waterdata.usgs.gov/blog/nldi-intro/).
- Flow direction and flow accumulation rasters from [NHDPlus Version 2 ](https://www.sciencebase.gov/catalog/item/66f42a51d34e791ae5dfc2ea) are also used in this package.
- This project was generated from
  [@hillc-usgs](https://github.com/hillc-usgs)'s [Pygeoapi Plugin
  Cookiecutter](https://code.usgs.gov/wma/nhgf/pygeoapi-plugin-cookiecutter)
  template.

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