Metadata-Version: 2.4
Name: hydrosensenet
Version: 0.2.0
Summary: An Open-Source Python Package for Optimal Hydrological Monitoring Network Design
Author: Jeil Oh, John Lee, Matthew Bartos
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/future-water/hydrosensenet
Project-URL: Repository, https://github.com/future-water/hydrosensenet
Project-URL: Issues, https://github.com/future-water/hydrosensenet/issues
Keywords: hydrology,sensor networks,streamgauge,optimization,QR decomposition
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Hydrology
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: xarray>=0.19.0
Requires-Dist: geopandas>=0.10.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: shapely>=1.8.0
Requires-Dist: pyarrow>=10.0.0
Requires-Dist: requests>=2.25.0
Provides-Extra: viz
Requires-Dist: matplotlib>=3.4.0; extra == "viz"
Requires-Dist: cartopy>=0.20.0; extra == "viz"
Provides-Extra: nwm
Requires-Dist: fsspec>=2021.11.0; extra == "nwm"
Requires-Dist: dask[distributed]>=2021.11.0; extra == "nwm"
Requires-Dist: pynhd>=0.14.0; extra == "nwm"
Requires-Dist: pygeohydro>=0.14.0; extra == "nwm"
Requires-Dist: s3fs>=2021.11.0; extra == "nwm"
Requires-Dist: zarr>=2.10.0; extra == "nwm"
Provides-Extra: dev
Requires-Dist: pytest>=6.2.0; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: flake8>=3.9.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: furo; extra == "docs"
Requires-Dist: myst-parser>=2.0; extra == "docs"
Dynamic: license-file

# hydrosensenet

An Open-Source Python Package for Optimal Hydrological Monitoring Network Design

**⚠️ In active development**

## Installation

Requires Python >= 3.9.

```bash
pip install hydrosensenet

# With optional extras:
pip install "hydrosensenet[viz]"   # map plotting (matplotlib, cartopy)
pip install "hydrosensenet[nwm]"   # NWM streamflow download stack (fsspec, dask, pynhd, ...)
```

The core install covers network design, evaluation, and I/O.
`NetworkDesignResult.plot()` and the NWM download utilities tell you
which extra to install if it is missing.

### Development

```bash
git clone https://github.com/future-water/hydrosensenet.git
cd hydrosensenet
pip install -e ".[dev]"   # editable install with tests, linting, build tooling
pytest                    # run the test suite
```

## Quick Start

### Examples

- [design_texas_gulf_baseline.ipynb](https://github.com/future-water/hydrosensenet/blob/main/design_texas_gulf_baseline.ipynb) - Baseline HUC2-scale design with data download and USGS network comparison
- [design_texas_gulf_flexible.ipynb](https://github.com/future-water/hydrosensenet/blob/main/design_texas_gulf_flexible.ipynb) - Flexible planning: per-HUC6 batch design across sub-basins
- [design_texas_gulf_risk.ipynb](https://github.com/future-water/hydrosensenet/blob/main/design_texas_gulf_risk.ipynb) - Risk-aware design using FEMA flood-risk weights

### Basic Usage

Try it immediately on the bundled sample basin (368 reaches of the
lower Colorado River, Texas — NWM v3.0 daily streamflow):

```python
from hydrosensenet import SensorNetworkDesigner, load_example_basin

streamflow_df, locations_gdf = load_example_basin()
designer = SensorNetworkDesigner(streamflow_df, locations_gdf)
result = designer.design_network(n_sensors=20)
result.print_summary()
```

Or with your own data:

```python
from hydrosensenet import SensorNetworkDesigner
from hydrosensenet.io import load_streamflow
import geopandas as gpd

# Load data
streamflow_df = load_streamflow("streamflow_2000.parquet")
locations_gdf = gpd.read_file("gauges.geojson")

# Design network
designer = SensorNetworkDesigner(
    streamflow_data=streamflow_df.values,
    locations=locations_gdf,
    location_labels=list(streamflow_df.columns)
)
result = designer.design_network(n_sensors=50, evaluate=True)
result.print_summary()
```
