riverjoin 0.1.11

Framework for Spatially Joining Two Hydrofabric Flowlines

riverjoin- Hydrofabric Flowlines Join Tool

	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

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

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

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

Using conda

conda create --name riverjoin python==3.10
conda activate riverjoin

Using venv

python -m venv riverjoin
# macOS/Linux
source riverjoin/bin/activate
# Windows
riverjoin\Scripts\activate

Install the package

pip install uv
uv pip install riverjoin
# OR
pip install riverjoin

For detail usage, refer to the riverjoin_docs.ipynb.

Citating This Tool

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

We welcome contributions. See CONTRIBUTING.md for more details.

Acknowledgements

	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

Dr. Sagy Cohen (sagy.cohen@ua.edu), Dr. Yixian Chen (ychen223@ua.edu), Supath Dhital (sdhital@ua.edu)