Metadata-Version: 2.4
Name: riverjoin
Version: 0.1.10
Summary: This is a river join implementation in Python.
Author-email: Supath Dhital <sdhital@ua.edu>, Yixian Chen <ychen223@ua.edu>
Project-URL: Homepage, https://github.com/sdmlua/riverjoin_py
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: geopandas
Requires-Dist: pathlib
Requires-Dist: fiona
Requires-Dist: folium
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: black; extra == "dev"

## Framework for Spatially Joining Two Hydrofabric Flowlines
<hr style="border: 1px solid black; margin: 0;">

[![Version](https://img.shields.io/github/v/release/sdmlua/riverjoin_py)](https://github.com/sdmlua/riverjoin_py/releases)
[![Issues](https://img.shields.io/github/issues/sdmlua/riverjoin_py)](https://github.com/sdmlua/riverjoin_py/issues)
[![PyPI version](https://badge.fury.io/py/riverjoin.svg?icon=si%3Apython)](https://badge.fury.io/py/riverjoin)
[![PyPI Downloads](https://static.pepy.tech/badge/riverjoin)](https://pepy.tech/projects/riverjoin)

### ```riverjoin```- Hydrofabric Flowlines Join Tool 
<hr style="border: 1px solid black; margin: 0;">

| | |
| --- | --- |
| <a href="https://sdml.ua.edu"><img src="https://sdml.ua.edu/wp-content/uploads/2023/01/SDML_logo_Sq_low.png" alt="SDML Logo" width="400"></a> | This Python framework provides a streamlined pipeline for spatially joining two hydrofabric flowline datasets. It handles complex spatial relationships including bifurcations, downstream tracing, and attribute transfer across different hydrofabric frameworks (e.g., SWORD, FIM, GeoGLOWS, MERIT, GRIT). It is developed under the Surface Dynamics Modeling Lab (SDML) at the University of Alabama. |

### Background
<hr style="border: 1px solid black; margin: 0;">

Hydrofabric datasets from different sources (NWM, SWORD, GeoGLOWS, MERIT, GRIT) often represent the same river network but with different segmentation, attributes, and topologies. **RiverJoin** enables users to spatially join these datasets — transferring attributes, detecting bifurcations, tracing downstream networks, and resolving mismatches between flowline geometries — providing a unified representation for cross-framework hydrological analysis.

### Package Structure
<hr style="border: 1px solid black; margin: 0;">

```bash

riverjoin_py/
├── docs/
│   └── riverjoin_docs.ipynb        # Detailed documentation and usage examples
├── images/
│   └── Flowchart_SpatialJoin.png   # Framework workflow diagram
├── src/
│   └── riverjoin/
│       ├── combined_workflow.py     # End-to-end combined join pipeline
│       ├── utilis.py               # Shared utility functions
│       └── modules/
│           ├── attribute_transfer.py                    # Transfer attributes between flowlines
│           ├── bifurcation_detector.py                  # Detect river bifurcations
│           ├── compare_linelength.py                    # Compare segment line lengths
│           ├── flowlines_buffer.py                      # Buffer-based spatial matching
│           ├── interactive_map.py                       # Interactive map visualization
│           ├── perpendicularlines.py                    # Generate perpendicular cross-sections
│           ├── project_initialization.py                # Project setup and configuration
│           ├── setup_hydrofabric.py                     # Hydrofabric data preparation
│           ├── situation_checker.py                     # Geometry situation classification
│           ├── traced_downstream.py                     # Downstream network tracing
│           └── traced_downstream_trace_bifurcation.py  # Downstream tracing with bifurcation handling
└── tests/                          # Test cases for all modules
```

### Installation and Usage
<hr style="border: 1px solid black; margin: 0;">

We recommend using a virtual environment to avoid dependency conflicts. Though it only depends on few light weight Python libraries.

**Using conda**
```bash
conda create --name riverjoin python==3.10
conda activate riverjoin
```

**Using venv**
```bash
python -m venv riverjoin
# macOS/Linux
source riverjoin/bin/activate
# Windows
riverjoin\Scripts\activate
```

**Install the package**
```bash
pip install uv
uv pip install riverjoin
# OR
pip install riverjoin
```
**For detail usage, refer to the [riverjoin_docs.ipynb](./docs/riverjoin_docs.ipynb).**

### Citating This Tool
<hr style="border: 1px solid black; margin: 0;">

Chen, Y., Cohen, S., Baruah, A. et al. Merging Remote Sensing Derived River Slope Datasets with High-Resolution Hydrofabrics for the United States. Sci Data 12, 1657 (2025). https://doi.org/10.1038/s41597-025-05941-6

### Contributing
<hr style="border: 1px solid black; margin: 0;">

We welcome contributions. See [CONTRIBUTING.md](./CONTRIBUTING.md) for more details.

### Acknowledgements
<hr style="border: 1px solid black; margin: 0;">

| | |
| --- | --- |
| ![CIROH Logo](https://ciroh.ua.edu/wp-content/uploads/2022/08/CIROHLogo_200x200.png) | Funding for this project was provided by the National Oceanic & Atmospheric Administration (NOAA), awarded to the Cooperative Institute for Research to Operations in Hydrology (CIROH) through the NOAA Cooperative Agreement with The University of Alabama (NA22NWS4320003). |

### For More Information
<hr style="border: 1px solid black; margin: 0;">

<a href="https://geography.ua.edu/people/sagy-cohen/" target="_blank">Dr. Sagy Cohen</a> (sagy.cohen@ua.edu), Dr. Yixian Chen (ychen223@ua.edu), Supath Dhital (sdhital@ua.edu)
