riverjoin-v1.0

RiverJoin

A Python framework for spatially joining two hydrofabric flowline datasets. RiverJoin reconciles river networks that come from different sources - each with its own segmentation, attributes, and topology- into a single, unified representation. It handles the hard parts of hydrofabric matching automatically: bifurcations, downstream tracing, geometry mismatches, and attribute transfer across frameworks.

Developed under the Surface Dynamics Modeling Lab (SDML) at the University of Alabama.

What it does

• Spatial join of two flowline networks — match and align river segments between a join network and a target network using buffer intersection and perpendicular cross-section matching.
• Attribute transfer — carry attributes from one network to the other, with nearest-flowline joins and aggregation back to the target reach IDs.
• Bifurcation detection & reconstruction — automatically detect multi-valued downstream splits and reconstruct them, with optional width-based pruning.
• Downstream network tracing — trace and reconnect disconnected segments along the downstream direction.
• Geometry situation checking — classify extraction outcomes and terminate gracefully when no meaningful match exists.
• Line-length comparison & statistics — quantify how well the extracted network matches the target.
• Interactive visualization — generate interactive HTML maps of the joined output for quick inspection.
• Single-call workflow — run the entire end-to-end pipeline through one run_riverjoin entry point, or compose individual modules as needed.

Tested against

RiverJoin has been validated across major hydrofabric frameworks, joining each against SWORD:

• GeoGLOWS
• MERIT (MERIT-Hydro / MERIT-Basins)
• GRIT (Global River Topology)
• FIM-HF (Flood Inundation Mapping Hydrofabric)

Installation

pip install riverjoin
# or
uv pip install riverjoin

Requires Python ≥ 3.10. For detailed usage, see docs/riverjoin_docs.ipynb.